stdlib-js / stdlib-js/stdlib

[RFC]: add `blas/ext/base/wasm/dapxsumkbn2`

Aperta
#5,506 1 commento 0 reazioni 0 assegnatari Vedi su GitHub
Accepted difficulty: 3 Feature Help Wanted JavaScript priority: Normal RFC WebAssembly
Lingua principale
JavaScript
Stelle
6k
Fork
1.3k
Merge medio
1g 3h
PR unite (30g)
611

Descrizione

## Description

This RFC proposes adding a new package to the `blas/ext/base/wasm/*` namespace: `@stdlib/blas/ext/base/wasm/dapxsumkbn2`.

This package is the WebAssembly counterpart to [`@stdlib/blas/ext/base/dapxsumkbn2`](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/ext/base/dapxsumkbn2).

### Key Points

When implementing this package, you'll need to do the following:

#### Install the Emscripten SDK

If you have not already installed the Emscripten SDK via stdlib, run the following [command](https://github.com/stdlib-js/stdlib/tree/c4898b75e43d00fccc2591254486e73548c909d5/tools/make/lib/install#emscripten-sdk) to install the Emscripten SDK, which is necessary for compiling C source files to WebAssembly.

```bash
make install-deps-emsdk
```

Please do **not** attempt to install the Emscripten SDK outside of stdlib, as we rely on specific known installation paths.

#### Install the WebAssembly Binary Toolkit

Similar to the step above, run the following [command](https://github.com/stdlib-js/stdlib/tree/c4898b75e43d00fccc2591254486e73548c909d5/tools/make/lib/install#webassembly-binary-toolkit) to install the WebAssembly binary toolkit, which is necessary for compiling a WebAssembly binary to the WebAssembly text format.

```bash
make install-deps-wabt
```

Please do **not** attempt to install the WebAssembly Binary Toolkit (WABT) outside of stdlib.

#### Create package files

To see examples of similar packages, see [`@stdlib/blas/ext/base/wasm/dapxsumkbn`](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/ext/base/wasm/dapxsumkbn) (returns a scalar) and [`@stdlib/blas/base/wasm/daxpy`](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/base/wasm/daxpy) (mutates and returns a vector).

While the package proposed in this RFC will **not** match the implementations found in the above packages, those packages should provide a conceptual idea of what is desired. Do **not** simply copy-paste the code found in those packages without reasoning about expected behavior and API design.

When creating package files, the source directory should **not** include either a `main.wasm` or a `main.wat` file. Both of those files will be generated during a subsequent step.

#### Update exports file

Consult the equivalent JavaScript package [`@stdlib/blas/ext/base/dapxsumkbn2`](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/ext/base/dapxsumkbn2). In particular, examine the `src` folder and determine the names of the functions which are publicly exposed in the C source files. They should be similar to `stdlib_strided_foo` and `stdlib_strided_foo_ndarray`.

In `src/exports.json` file in the WebAssembly package, include the names of those exported functions, making sure to prefix each function name with a leading underscore.

#### Update manifest file

In the `manifest.json` file in the WebAssembly package, update the source dependency to point to the upstream JavaScript package. This package also happens to include the C implementation which will be what is compiled to WebAssembly.

```diff
+ "dependencies": [
+ "@stdlib/blas/ext/base/dapxsumkbn2"
+ ]
```

#### Compile WebAssembly

To compile the upstream C implementation to WebAssembly, run the following command from the root stdlib repository directory (not the package folder!)

```bash
make wasm PKGS_WASM_PATTERN="blas/ext/base/wasm/dapxsumkbn2"
```

After running the above command, check the `src` folder to confirm that both a `*.wasm` and a `*.wat` file were created.

If, for whatever reason, you need to recompile WebAssembly, you first need to remove any generated files using the following command

```bash
make clean-wasm PKGS_WASM_PATTERN="blas/ext/base/wasm/dapxsumkbn2"
```

and then rerun

```bash
make wasm PKGS_WASM_PATTERN="blas/ext/base/wasm/dapxsumkbn2"
```

#### Add a license header

In the `*.wat` file, add a license header.

```
;; @license Apache-2.0
;;
;; Copyright (c) 2025 The Stdlib Authors.
;;
;; Licensed under the Apache License, Version 2.0 (the "License");
;; you may not use this file except in compliance with the License.
;; You may obtain a copy of the License at
;;
;; http://www.apache.org/licenses/LICENSE-2.0
;;
;; Unless required by applicable law or agreed to in writing, software
;; distributed under the License is distributed on an "AS IS" BASIS,
;; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
;; See the License for the specific language governing permissions and
;; limitations under the License.

```

For reference, see [`@stdlib/blas/ext/base/wasm/dapxsumkbn`](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/ext/base/wasm/dapxsumkbn).

Note that, if you regenerate the `*.wat` file at any point, you'll need to manually re-add the license header above.

#### Update all tests, documentation, and examples

Now that the WebAssembly binary has been generated, proceed to update all tests, documentation, and examples to reflect the API and expected behavior for the package. You should spend some time studying the tests in [`@stdlib/blas/ext/base/dapxsumkbn2`](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/ext/base/dapxsumkbn2). We expect the WebAssembly package to have equivalent and fully comprehensive tests.

To see an example of what is expected, study the tests in

- [`@stdlib/blas/ext/base/wasm/dapxsumkbn`](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/ext/base/wasm/dapxsumkbn) and [`@stdlib/blas/ext/base/dapxsumkbn`](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/ext/base/dapxsumkbn) — this is a package which returns a scalar value.
- [`@stdlib/blas/base/daxpy`](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/base/daxpy) and [`@stdlib/blas/base/wasm/daxpy`](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/blas/base/wasm/daxpy) — this is a package which mutates and returns a vector.

Compare and contrast the tests in those pairs of packages. As should be inferred from those packages, all tests for various strides, offsets, and other behavior should be carried over and modified for the WebAssembly package.

For each of the following commands, please run them from the root stdlib repository directory (not the package folder!).

To run unit tests,

```bash
make test TESTS_FILTER=".*/blas/ext/base/wasm/dapxsumkbn2/.*"
```

To run examples,

```bash
make examples EXAMPLES_FILTER=".*/blas/ext/base/wasm/dapxsumkbn2/.*"
```

To run benchmarks,

```bash
make benchmark BENCHMARKS_FILTER=".*/blas/ext/base/wasm/dapxsumkbn2/.*"
```

### Create pull request

Provided all tests, examples, and benchmarks successfully execute and pass and that you've updated the package's documentation, you are now ready to open a pull request!

* * *

## Notes

- If you are interested in contributing a PR which addresses this RFC and still getting familiar with our project conventions, please do **not** submit LLM-generated code. Please consult our [contributing guidelines](https://github.com/stdlib-js/stdlib/blob/develop/CONTRIBUTING.md) and the associated [development guide](https://github.com/stdlib-js/stdlib/blob/develop/docs/development.md). Failure to respect project conventions will result in your PR being rejected without review. Thank you for understanding!

### Checklist

- [X] I have read and understood the [Code of Conduct](https://github.com/stdlib-js/stdlib/blob/develop/CODE_OF_CONDUCT.md).
- [X] Searched for existing issues and pull requests.
- [X] The issue name begins with `[RFC]:`.

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Start by comparing the JavaScript package @stdlib/blas/ext/base/dapxsumkbn2 with the analogous WebAssembly packages @stdlib/blas/ext/base/wasm/dapxsumkbn and @stdlib/blas/base/wasm/daxpy. Create the package files, exports.json, and manifest.json, then generate the wasm and wat files with the specified make command and add the license header. Update tests, documentation, examples, and benchmarks, and run each listed make target from the repository root.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
c, javascript, wasm
Ambito
backend, build-system, testing
Tipo di issue
Funzionalità
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Ferma
Chiarezza
Specificata chiaramente
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.