[RFC]: Auto-injecting the license header into main.wat

[0PrashantYadav0]

Description

This RFC proposes automatically prepending the standard Apache-2.0 license header to every generated WebAssembly text (.wat) file as the final step of a successful make wasm build.

Today, when C source is compiled to WebAssembly, the toolchain emits src/main.wasm (the binary) and src/main.wat (the text format, produced by wasm2wat). wasm2wat emits main.wat without a license header, so the header must currently be pasted into each file by hand after every build. This is tedious, easy to forget, and produces inconsistent copyright years across packages.

Proposed change: add the header injection to a single central script — tools/scripts/compile_wasm — which every repository-level make wasm funnels through:

make wasm PKGS_WASM_PATTERN=...              (repo root)
  -> tools/make/lib/wasm/Makefile            (iterates matched packages)
    -> tools/scripts/compile_wasm <pkg>      <-- single choke-point
      -> compile(): cd src/ && make wasm     (per-package Makefile runs wasm2wat)

A new add_license_header() function runs after a successful compile(). It stamps the current year via date +'%Y', iterates the *.wat files in the package src/ directory, and prepends the Apache-2.0 block (matching stdlib's committed .wat convention: ;; line comments, quoted "License"/"AS IS", indented license URL, followed by a single blank line before (module).

The function is idempotent: files already beginning with ;; @license are skipped, so re-running make wasm never produces duplicate headers. When main.wasm is rebuilt, a fresh header-less main.wat is regenerated and the header is re-applied — always present, never doubled.

Related Issues

None

Questions

1. Should the copyright year always be the current build year (date +'%Y'), or pinned to a fixed value for reproducible builds?
2. Should coverage extend to running make wasm directly inside a package's src/ directory (which bypasses compile_wasm)? Doing so would require editing the per-package src/Makefile template and its generator — a much larger change deliberately left out of this RFC.

Other

Implementation notes

• Single-file change: tools/scripts/compile_wasm. The alternative — editing the $(wat_targets) rule in each package's src/Makefile — would touch 150+ duplicated template files plus the template generator, and is neither DRY nor maintainable.
• Maintainer documentation added at tools/scripts/WASM_LICENSE_HEADER.md.

Sample output (head -4 src/main.wat after make wasm):

;; @license Apache-2.0
;;
;; Copyright (c) 2026 The Stdlib Authors.
;;

Verification

# Auto-add on rebuild:
rm lib/node_modules/@stdlib/stats/strided/wasm/smeanwd/src/main.wat
make wasm PKGS_WASM_PATTERN="stats/strided/wasm/smeanwd"
head -3 lib/node_modules/@stdlib/stats/strided/wasm/smeanwd/src/main.wat

# Idempotency (prints 1):
make wasm PKGS_WASM_PATTERN="stats/strided/wasm/smeanwd"
grep -c "@license" lib/node_modules/@stdlib/stats/strided/wasm/smeanwd/src/main.wat

Checklist

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

[0PrashantYadav0]

I am thinking of adding this section inside the tools/scripts/compile_wasm file, so that it produce headers along with wasm text.

# Prepends the Apache-2.0 license header to generated WebAssembly text files.
#
# ## Notes
#
# -   The copyright year is stamped using the current year.
# -   The function is idempotent: files which already begin with a license
#     header are left untouched, so re-running `make wasm` never produces
#     duplicate headers.
#
# $1 - source directory
add_license_header() {
	local year
	local tmp
	local f

	year=$(date +'%Y')
	for f in "$1"/*.wat; do
		# Skip if no `.wat` files exist:
		if [[ ! -e "${f}" ]]; then
			continue
		fi
		# Skip files which already have a license header:
		if head -n 1 "${f}" | grep -q '^;; @license'; then
			continue
		fi
		tmp="${f}.tmp"
		{
			echo ';; @license Apache-2.0'
			echo ';;'
			echo ";; Copyright (c) ${year} The Stdlib Authors."
			echo ';;'
			echo ';; Licensed under the Apache License, Version 2.0 (the "License");'
			echo ';; you may not use this file except in compliance with the License.'
			echo ';; You may obtain a copy of the License at'
			echo ';;'
			echo ';;    http://www.apache.org/licenses/LICENSE-2.0'
			echo ';;'
			echo ';; Unless required by applicable law or agreed to in writing, software'
			echo ';; distributed under the License is distributed on an "AS IS" BASIS,'
			echo ';; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.'
			echo ';; See the License for the specific language governing permissions and'
			echo ';; limitations under the License.'
			echo ''
			cat "${f}"
		} > "${tmp}" && mv "${tmp}" "${f}"
	done
}

[0PrashantYadav0]

Also i would like to know about your thought on this as well, along with the answers of my questions if possible. @kgryte @Planeshifter

[kgryte]

@0PrashantYadav0 You previously explored and suggested a different workaround for the problem you describe. I believe this was on one of your other open PRs.

Regardless, regarding your proposal above, as proposed, I am not inclined to support this. Moving up to the top-level is an odd choice given that the package's local makefile is intended to be the locus of compilation. The top-level script is simply a coordination mechanism. It shouldn't be involved in the intricacies of how artifacts are actually put together. That is the package's responsibility.

I did, however, go ahead and sketch out a solution in the following commit: 223bde6

Basically, the idea would be to add a postbuild.wat.js file and a line to the package's src/Makefile, which is consistent with how we already have precedent for calling local package Node.js scripts from that file.

[kgryte]

In short, a package should be considered something of a black box when it comes to generating its artifacts (i.e., *.wasm and *.wat files). If the package is not generating a license header during artifact generation that is on the package, not for external tooling to workaround. This is supported by the fact that elsewhere we do generate artifacts within a package (e.g., the ./lib artifact) which do include a license header. So, in short, it should be the responsibility of the package to ensure its artifacts are correctly generated.

Yes, this means adding a separate script to each wasm package, but this better reflects where the responsibility lies, just as we already have scripts/build.js which generates the ./lib artifact. And how that license header gets inserted in *.wat files should be purely at the discretion of individual packages, not by top-level tooling making assumptions about the artifacts produced.