dotnet/runtime 中构建 WebAssembly 库Wasm 工具链缓存机制、子集构建命令与配置要点【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime本文围绕 dotnet/runtime 仓库的 WebAssembly 库构建指南 展开完整覆盖 Emscripten/WASI SDK 等外部工具的按需下载与共享缓存机制、针对浏览器目标-os browser的 Mono 运行时与托管库构建子集命令、单库构建方式以及 Debug 构建的日志行为。读完本文后你可以独立完成 Mono WASM 运行时、System.Private.CoreLib、库的 native 组件的构建并正确管理跨分支、跨 worktree 的工具链缓存。前置条件与适用前提开始构建前请先阅读 构建要求文档了解你的操作系统对应的构建依赖。需要特别说明的是目前不需要额外安装任何构建依赖就可以开始 WebAssembly 构建——Emscripten 会在构建过程中自动下载并安装到共享缓存下文详述。针对特定平台的完整构建方式见 Mono browser README。本文档面向在 runtime 或 libraries 层面做开发的场景理解配置configuration概念前建议先阅读配置说明。Wasm 工具链的按需供应与共享缓存WebAssembly 构建与测试工作流依赖一批外部工具Emscripten SDK、WASI SDK、wasmtime、Chrome、chromedriver、Firefox、geckodriver 和 V8。这些工具按需下载到仓库主检出main checkout下的共享缓存中目录布局如下main checkout/.dotnet/wasm-tools/tool/version-host rid/ # 工具本体 main checkout/.dotnet/wasm-tools/tool/version-host rid.complete # 可用后写入的哨兵文件由于版本号是缓存路径的一部分这一设计天然带来两个好处升级版本等于新增一个缓存条目不会静默复用旧工具在不同分支间切换各自 pin 了不同版本时两个版本都会被复用无需重新下载。缓存锚定在主检出而非工作目录缓存锚定在主检出而不是各个工作目录因此同一个 clone 的所有 git worktree 共享同一份缓存——不需要按 worktree 重复下载同时删除仓库时缓存也会被一并删除。缓存还位于artifacts/之外所以不会被clean清理掉。这一机制在 WasmToolCache.props 中实现从源码结构看可以确认几个细节缓存目录由WasmToolCacheDir属性决定host RID$(HostOS)-$(BuildArchitecture)参与缓存条目命名因此同一版本的 x64/arm64 工具包可以共存主检出的解析是纯文件 I/O 完成的读取.git文件若内容形如gitdir: main/.git/worktrees/name则提取主检出前缀作为缓存锚点相对路径的 gitdir 或非 git 检出则回退到当前仓库根最后兜底到$(ArtifactsDir)/wasm-tools。注释中说明采用这种方式是为了廉价到每个项目都可以评估且与原生侧脚本保持一致下载用的临时解压目录WasmToolDownloadDir放在artifacts下因为它是一次性临时空间。版本 pin 文件各工具的版本由以下文件锁定当前仓库中的实际取值工具版本文件当前版本Emscriptensrc/mono/browser/emscripten-version.txt6.0.2WASI SDKeng/wasm/wasi-sdk-version.txt33.0wasmtimesrc/mono/wasi/wasmtime-version.txt45.0.0浏览器与 JS 引擎eng/testing/BrowserVersions.props—这些 txt 文件是唯一事实来源MSBuild 侧由 WasmToolCache.props 读取原生构建侧eng/native/configurecompiler.cmake与eng/native/gen-buildsys.*也会直接读这些文本文件因为 CMake/脚本无法求值 MSBuild 属性。手动供应与清理只供应 Emscripten、不构建其他内容./build.sh -s provision.emsdk -os browser删除当前检出已经不再引用的缓存条目./build.sh -s clean.wasmtools追加/p:PruneAllWasmToolstrue则清空整个缓存。清理逻辑实现在 PruneWasmToolCache.proj 中它通过 glob 缓存目录下所有*.complete哨兵文件确定在用条目再与当前检出的版本清单Emscripten、WASI SDK、wasmtime 以及有条件定义的 Chrome/chromedriver、V8、Firefox/geckodriver 哨兵做差集删除哨兵与对应工具目录。相关环境变量设置DOTNET_WASM_TOOL_CACHE_DIR可以移动缓存位置——例如放到用户全局的~/.dotnet/wasm-tools让多个无关 clone 共享或指向 CI agent 的持久缓存目录设置EMSDK_PATH或WASI_SDK_PATH对对应 SDK 仍然优先于缓存生效WASMTIME_PATH不被支持目前把构建指向本地 wasmtime 已被禁用对应上游 issue #101528文中不做外链此处仅作追踪编号说明。另外注意 src/mono/browser/README.md 中的一个 Windows 陷阱EMSDK 初始化隐式依赖 Python。若首次构建尝试时系统未装 Python自动供应会失败并留下无效状态的缓存条目之后补装 Python需要手动删除main checkout/.dotnet/wasm-tools/emscripten/下对应的条目再重新构建。该目录还有一个独立的make provision-wasm目标它安装的是可打补丁的上游 emsdk 克隆到src/mono/browser/emsdk与共享缓存完全独立只有需要修改 emscripten 本身时才需要。重要注意事项不要混合 runtime 与 library 的配置当前不支持为 runtime 和 libraries 分别指定不同配置把 Release 的-runtimeConfiguration与 Debug 的-libraryConfiguration或-configuration混用以及单线程/多线程配置的混搭都不行。请只使用-configuration选项并取值Debug或Release不要分别指定-runtimeConfiguration和-libraryConfiguration。此限制由上游 issue #42553 跟踪。构建 Mono 的 System.Private.CoreLib 或运行时如果你在开发 Mono 的核心部分通常需要构建 Mono 运行时和 System.Private.CoreLib。构建两者./build.sh mono -os browser -c Debug|Release只构建 System.Private.CoreLib不含 Mono 运行时使用Mono.CoreLib子集./build.sh mono.corelib -os browser -c Debug|Release只构建 Mono 运行时不含 System.Private.CoreLib使用Mono.Runtime子集./build.sh mono.runtime -os browser -c Debug|Release同时构建 Mono/System.Private.CoreLib 与托管库./build.sh monolibs -os browser -c Debug|Release构建 WebAssembly 运行时文件Mono.WasmRuntime 子集WebAssembly 的实现文件在库源码构建之后生成并输出到 artifacts 目录。如果你只需要重新编译这些模块构建Mono.WasmRuntime子集即可./build.sh mono.wasmruntime -os browser -c Debug|Release这里有一条原文档强调的重建纪律代码改动后用build.sh重建时即使改动只涉及 Mono也必须保证mono.wasmruntime与libs.pretest两个子集都被包含否则 artifacts 中的目录不会被更新libs.pretest的作用见下一节。更新 in-tree 运行时包libs.pretest 子集如果不跑完整的Libs子集可以用Libs.PreTest子集把更新后的 runtime/corelib 二进制拷贝到运行测试所用的运行时包runtime pack中./build.sh libs.pretest -os browser -c Debug|Release只构建库的 native 组件库构建中包含一部分原生代码包括对 libc、openssl、gssapi 和 zlib 的 shim垫片。构建系统用 CMake 生成 Makefile、以 clang 编译并借助 git 生成部分版本信息。只构建这些组件./build.sh libs.native -os browser -c Debug|Release构建单个库指定要构建的项目即可构建个别库。原文档给出的两个示例路径请替换为你本地的仓库全路径构建某库如 System.Net.Http的全部项目包括测试./build.sh -os browser -c Release --projects full-repository-path/src/libraries/System.Net.Http/System.Net.Http.slnx只构建某库的源码工程./build.sh -os browser -c Release --projects full-repository-path/src/libraries/System.Net.Http/src/System.Net.Http.csproj更完整的--projects用法与参数位置要求-f、-c等选项需放在目录参数之后可参考 libraries 构建文档。Debug 构建的默认行为Debug构建会默认设置以下环境变量理解它们有助于看懂构建后的控制台输出1. 开启调试与日志输出其中 GC 信息会被打印到控制台MONO_LOG_LEVELdebug MONO_LOG_MASKgc典型输出示例L: GC_MAJOR_SWEEP: major size: 752K in use: 39K L: GC_MAJOR: (user request) time 3.00ms, stw 3.00ms los size: 0K in use: 0K2. 将System.Diagnostics.Debug的输出重定向到stderr在浏览器环境中显示到控制台。原文档引用的设置代码// Setting this env var allows Diagnostic.Debug to write to stderr. In a browser environment this // output will be sent to the console. Right now this is the only way to emit debug logging from // corlib assemblies. monoeg_g_setenv (DOTNET_DebugWriteToStdErr, 1, 0);即DOTNET_DebugWriteToStdErr1是 corlib 程序集内部目前唯一可以发出调试日志的通道。更新 Docker 镜像中的 Emscripten 版本CI 使用的 Docker 镜像中 Emscripten 版本的更新流程在dotnet-buildtools-prereqs-docker仓库src/azurelinux目录中更新当前 WebAssembly 镜像定义里的 Emscripten 版本。当前启用的 WebAssembly 镜像清单由该仓库 Azure Linux 目录下的manifest.json跟踪提交包含 Dockerfile 改动的 PR等待镜像发布流程完成镜像发布后到dotnet/versions仓库对应的 image-info 文件image-info.dotnet-dotnet-buildtools-prereqs-docker-main.json中查找新 tag回到本仓库更新其中的 WebAssembly 镜像引用涉及 eng/pipelines/helix-platforms.yml 与eng/pipelines/libraries/helix-queues-setup.yml两个文件用更新后的镜像引用提交 PR。注意此流程只影响 CI 镜像不影响本地开发——本地构建的 Emscripten 走的是上文所述的共享缓存版本由 emscripten-version.txt 锁定。测试库库测试JS 引擎 v8/SpiderMonkey/JavaScriptCore 与浏览器 Chrome 两种方式的运行方法见 Mono browser README 的 Libraries tests 一节其中 macOS 下以make run-tests-v8-lib_name形式按引擎选择运行浏览器测试依赖 chromedriver 与 Google Chrome。小结本文档给出的 WebAssembly 库构建路径可以归纳为一条主线所有外部工具由共享缓存自动供应版本 pin 在若干 txt/props 文件中缓存按版本 host RID组织并锚定主检出构建命令统一是./build.sh subset -os browser -c Debug|Release的形式按需选择mono、mono.corelib、mono.runtime、mono.wasmruntime、libs.pretest、libs.native等子集并始终遵守runtime 与 library 配置不可混合这一约束。相关实现证据集中在 eng/wasm/WasmToolCache.props、eng/wasm/PruneWasmToolCache.proj 与 eng/wasm/wasm-tool-cache.sh可供进一步深入阅读。【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址: https://gitcode.com/GitHub_Trending/runtime6/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考