Provision wasm build/test tools into a shared, version-keyed cache

[lewing]

Summary

The externally-acquired WebAssembly tools were each provisioned by a bespoke target into one of three locations, with three different version schemes and three different staleness strategies:

Tool	Old location	Version source	Stale on bump?
emsdk	src/mono/browser/emsdk/	eng/Versions.props + emscripten-version.txt	yes (gated on !Exists(dir))
wasi-sdk	artifacts/wasi-sdk/	hardcoded in the target	no
wasmtime	artifacts/obj/wasmtime/	wasmtime-version.txt	yes (gated on !Exists(dir))
chrome / chromedriver / firefox / geckodriver / v8	artifacts/bin/<tool>/	BrowserVersions.props	no

This put mono in the emsdk path even though CoreCLR-wasm consumes it (src/coreclr/runtime.proj), re-downloaded ~2 GB per worktree, was wiped by cleaning artifacts/, and — because emsdk and wasmtime were gated only on directory existence — kept silently reusing a stale tool after a version bump.

Approach

Consolidate all eight tools onto a single cache:

<root>/<tool>/<version>-<host rid>/           the tool
<root>/<tool>/<version>-<host rid>.complete    sentinel written last

Because the version and host RID are part of the path, a version bump is a cache miss by construction — no staleness comparison to get wrong, switching branches reuses both versions, and x64/arm64 payloads coexist.

Default root: the repository's main checkout (<main checkout>/.dotnet/wasm-tools), derived by reading the worktree .git file (no git process spawn). All worktrees of one clone share a single copy, yet the cache is deleted with the repo. DOTNET_WASM_TOOL_CACHE_DIR overrides it (e.g. a user-global cache, or a CI agent cache); EMSDK_PATH / WASI_SDK_PATH / WASMTIME_PATH still take precedence per tool.

A generic eng/wasm/AcquireWasmTool.proj (invoked once per tool) replaces the duplicated download/extract/stamp logic: it extracts to a unique temp directory and only then moves into the final name, so an interrupted or concurrent acquisition can never leave a half-populated entry. wasi-sdk and wasmtime now download native arm64 builds instead of x86_64.

The native build scripts (gen-buildsys.sh/.cmd) and the two wasm Makefiles resolve the same cache through eng/wasm/wasm-tool-cache.sh/.cmd; the out-of-tree WasmApp.LocalBuild.props mirrors the resolution. A clean.wasmtools subset prunes unreferenced entries. The wasi-sdk version moves into eng/wasm/wasi-sdk-version.txt, and the now-unused eng/download-wasi-sdk.ps1 is removed.

Validation (osx-arm64)

• ✅ ./build.sh mono+libs -os browser
• ✅ ./build.sh mono+libs -os wasi
• ✅ ./build.sh clr+libs -os browser (CoreCLR-wasm — the mono-in-path motivator)
• ✅ emsdk / wasi-sdk / wasmtime / v8 provision natively into the anchored cache; re-runs are no-ops
• ✅ MSBuild and the shell/cmd helpers proven consistent across worktree / relative-gitdir / normal-clone cases

Still needs validation on Linux and Windows agents in CI.

Note

This pull request was authored with the assistance of GitHub Copilot.

[azure-pipelines]

Azure Pipelines:
Successfully started running 6 pipeline(s).
10 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

Pull request overview

This PR refactors WebAssembly tool acquisition (emscripten, wasi-sdk, wasmtime, browsers/engines) to use a shared, version-keyed cache and updates build/test infrastructure to resolve tools from that cache instead of per-worktree / artifacts/ locations.

Changes:

• Introduces eng/wasm/WasmToolCache.props and shared cache helpers/projects to key tool installs by <tool>/<version>-<hostrid> with .complete sentinels.
• Updates MSBuild targets, native build scripts, and Makefiles to resolve tools from the shared cache and stage copies for Helix payloads where needed.
• Moves wasi-sdk version to eng/wasm/wasi-sdk-version.txt, adds a cache-prune subset (clean.wasmtools), and updates documentation/pipeline path triggers accordingly.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/tests/FunctionalTests/WebAssembly/Directory.Build.props	Switch functional tests to use cached emsdk path when provisioned.
src/tests/Common/helixpublishwitharcade.proj	Stage wasmtime for Helix using the new stamp/sentinel scheme.
src/mono/wasm/Makefile	Resolve EMSDK_PATH via the shared wasm tool cache helper.
src/mono/wasm/build/WasmApp.LocalBuild.props	Mirror cache resolution logic for out-of-tree consumers.
src/mono/wasi/build/WasiApp.targets	Allow expected wasi-sdk version to be overridden by in-tree targets.
src/mono/wasi/build/WasiApp.InTree.targets	Feed in-tree wasi-sdk version into the shared version check.
src/mono/sample/wasi/wasi.mk	Resolve wasmtime provisioning directory via the shared cache helper.
src/mono/browser/README.md	Update docs to describe shared wasm tool cache and version pins.
src/mono/browser/build/WasmApp.InTree.props	Resolve EMSDK_PATH from shared cache when provisioned.
src/mono/browser/browser.proj	Remove now-unneeded version-line clearing tied to old provisioning flow.
src/mono/.gitignore	Stop ignoring wasi-sdk under src/mono (no longer provisioned there).
src/libraries/sendtohelix-browser.targets	Stage browser/engine tools from cache into Helix-safe staging paths.
eng/wasm/WasmToolCache.props	Define shared cache root, host RID keying, and core tool cache paths/stamps.
eng/wasm/wasm-tool-cache.sh	Provide POSIX helper to resolve provisioned tool directories from cache.
eng/wasm/wasm-tool-cache.cmd	Provide Windows helper to resolve provisioned tool directories from cache.
eng/wasm/wasi-sdk-version.txt	New single source of truth for pinned wasi-sdk version.
eng/wasm/PruneWasmToolCache.proj	Add pruning project for removing unreferenced cache entries.
eng/wasm/AcquireWasmTool.proj	Add generic download/extract/publish project for cached tools.
eng/testing/wasm-provisioning.targets	Provision browsers/V8 into cache via generic acquisition project.
eng/testing/wasi-provisioning.targets	Provision wasmtime into cache via generic acquisition project.
eng/testing/tests.browser.targets	Update CI emsdk path resolution to shared cache when provisioned.
eng/Subsets.props	Add clean.wasmtools subset wiring to the prune project.
eng/pipelines/common/templates/browser-wasm-coreclr-build-tests.yml	Ensure pipeline provisions emsdk into the shared cache (comment update).
eng/pipelines/common/evaluate-default-paths.yml	Update “wasmbuildtests” path triggers to include new wasm cache infrastructure.
eng/native/gen-buildsys.sh	Resolve EMSDK/WASI_SDK paths via the shared cache helper on wasm builds.
eng/native/gen-buildsys.cmd	Resolve EMSDK via shared cache helper for wasm builds.
eng/download-wasi-sdk.ps1	Remove old Windows wasi-sdk download script (no longer used).
eng/AcquireWasiSdk.targets	Acquire wasi-sdk into the shared cache keyed by version/host RID.
eng/AcquireEmscriptenSdk.targets	Provision emscripten SDK into shared cache with version-keyed sentinel.
docs/workflow/debugging/mono/wasm-debugging.md	Update deterministic patching guidance to match cached provisioning.
docs/workflow/building/libraries/webassembly-instructions.md	Document shared wasm tool provisioning and prune commands.
docs/workflow/building/coreclr/wasm.md	Note emsdk is installed into a shared cache under the main checkout.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (3)

eng/wasm/WasmToolCache.props:14

• Comment is inconsistent with the actual default cache location. The default cache is under the repo's main checkout (e.g. /.dotnet/wasm-tools), not "outside the repository"; it is only outside artifacts/. This can mislead readers about lifetime/cleanup expectations.

  The cache deliberately lives outside the repository so that it survives `clean`, is shared
  by every clone and git worktree, and isn't tied to any one runtime flavor's source directory.

eng/wasm/AcquireWasmTool.proj:58

• AcquireWasmTool downloads into a shared $(WasmToolDownloadDir) and later deletes the downloaded archive. If multiple builds acquire the same tool/version concurrently, one invocation can delete the archive while another is still extracting it, causing intermittent acquisition failures. Downloading into the per-invocation temp directory avoids cross-process races.

    <DownloadFile SourceUrl="$(WasmToolUrl)"
                  DestinationFolder="$(WasmToolDownloadDir)"
                  Retries="3"
                  SkipUnchangedFiles="true">
      <Output TaskParameter="DownloadedFile" PropertyName="_Archive" />

eng/native/gen-buildsys.cmd:20

• This update resolves EMSDK_PATH via the shared wasm tool cache, but later in this same script the WASI branch still falls back to %__repoRoot%\artifacts\wasi-sdk (the old location). That makes Windows WASI builds inconsistent with the new cache layout and can fail after artifacts cleanup even if the shared cache is populated. Please update the WASI branch to resolve wasi-sdk through eng/wasm/wasm-tool-cache.cmd as well.

:: Set up the EMSDK environment before setlocal so that it propagates to the caller.
:: Written without a parenthesized block so that %WASM_TOOL_CACHE_RESULT% expands without
:: delayed expansion, which cannot be enabled here without discarding emsdk_env's variables.
if /i not "%__Os%" == "browser" goto :AfterEmsdkEnv
if not "%EMSDK_PATH%" == "" goto :CallEmsdkEnv

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 34 out of 34 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 34 out of 34 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 34 out of 34 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 34 out of 34 changed files in this pull request and generated 1 comment.

[azure-pipelines]

Azure Pipelines:
Successfully started running 6 pipeline(s).
10 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[maraf]

Hmm. I thought we migrated away from the "LocalBuild". I see it's imported in https://github.com/dotnet/runtime/blob/main/src/mono/wasm/data/aot-tests/Directory.Build.props#L26. Did you see it fail because of these?

[maraf]

Could we potentially do the same with .dotnet folder?