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

[kgryte]

Description

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

This package is the WebAssembly counterpart to @stdlib/blas/ext/base/dnansumkbn2.

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 to install the Emscripten SDK, which is necessary for compiling C source files to WebAssembly.

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 to install the WebAssembly binary toolkit, which is necessary for compiling a WebAssembly binary to the WebAssembly text format.

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 (returns a scalar) and @stdlib/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 src directory should not include either a main.wasm or a main.wat file. Both of those files will be generated during a subsequent step.

Additionally, the lib directory should not include the file binary.browser.js. This file will also be generated during a subsequent step.

Update package.json

In the package's package.json file, ensure that there is a private __stdlib__ configuration object with the following field

  "__stdlib__": {
    ...,
+    "wasm": true
    ...
  }

Setting this field ensures that project tooling is able to resolve this package as one containing WebAssembly.

Update exports file

Consult the equivalent JavaScript/C package @stdlib/blas/ext/base/dnansumkbn2. 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 the upstream package's manifest file

Next, in the upstream JavaScript/C package @stdlib/blas/ext/base/dnansumkbn2, closely examine the manifest.json file in that package. In particular, confirm that the file has a "wasm" field and an associated build configuration.

For an example of a package's having a WebAssembly configuration, see @stdlib/blas/ext/base/dapxsumkbn.

If the upstream package lacks a WebAssembly build configuration, you'll need to add such a configuration. For an example of a commit adding a WebAssembly configuration to an upstream package, see b0d1c0e.

Update the WebAssembly package's manifest file

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

+     "dependencies": [
+        "@stdlib/blas/ext/base/dnansumkbn2"
+      ]

Compile WebAssembly

Before attempting to compile WebAssembly, go ahead and run the clean command from the root stdlib repository directory (not the package folder!) to remove any generated files.

make clean-wasm PKGS_WASM_PATTERN="blas/ext/base/wasm/dnansumkbn2"

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

make wasm PKGS_WASM_PATTERN="blas/ext/base/wasm/dnansumkbn2"

After running the above command, check the src folder to confirm that both a *.wasm and a *.wat file were created, and check the lib folder to confirm that a binary.browser.js was created.

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

make clean-wasm PKGS_WASM_PATTERN="blas/ext/base/wasm/dnansumkbn2"

and then rerun

make wasm PKGS_WASM_PATTERN="blas/ext/base/wasm/dnansumkbn2"

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.

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/dnansumkbn2. 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 and @stdlib/blas/ext/base/dapxsumkbn — this is a package which returns a scalar value.
• @stdlib/blas/base/daxpy and @stdlib/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,

make test TESTS_FILTER=".*/blas/ext/base/wasm/dnansumkbn2/.*"

To run examples,

make examples EXAMPLES_FILTER=".*/blas/ext/base/wasm/dnansumkbn2/.*"

To run benchmarks,

make benchmark BENCHMARKS_FILTER=".*/blas/ext/base/wasm/dnansumkbn2/.*"

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 and the associated development guide. Failure to respect project conventions will result in your PR being rejected without review. Thank you for understanding!

Checklist

• I have read and understood the Code of Conduct.
• Searched for existing issues and pull requests.
• The issue name begins with [RFC]:.