Merge 25d5361c95 into 02596ba8d9

2025-07-30 22:34:37 +08:00 · 2025-07-30 22:34:37 +08:00 · 065b7f079e
parent 02596ba8d9 25d5361c95
commit 065b7f079e
8 changed files with 76 additions and 13 deletions
--- a/src/mono/browser/README.md
+++ b/src/mono/browser/README.md
@ -228,6 +228,36 @@ They are handy to quickly disassemble functions and inspect webassembly module s

 There is also the [wa-edit](https://github.com/radekdoulik/wa-info#wa-edit) tool, which is now used to prototype improved warm startup.

+## Properties That Trigger Relinking
+
+### What is Relinking?
+
+Relinking is the process of rebuilding the native WebAssembly runtime (`dotnet.native.js`, `dotnet.native.wasm`, etc.) with updated or trimmed content, often resulting in a smaller or more optimized output. This is necessary when certain configuration properties or source changes require regeneration of the native artifacts.
+
+### Properties That Trigger Relinking in `browser.proj`
+
+The following MSBuild properties will trigger a relinking (full rebuild of native artifacts) during the browser/wasm build process:
+
+- **`WasmBuildNative`** - `/p:WasmBuildNative=true` - Forces a fresh build of the native runtime components.
+- **`WasmRelinkNative`** - `/p:WasmRelinkNative=true` - Explicitly requests relinking, even if not otherwise required by other property changes.
+- **`RunAOTCompilation`** - `/p:RunAOTCompilation=true` - Enables Ahead-of-Time (AOT) compilation. Changing this requires relinking to produce the correct output.
+- **`WasmEnableExceptionHandling`** - `/p:WasmEnableExceptionHandling=true` - Changes exception handling mechanisms in the native runtime.
+- **`EnableDiagnostics`** - `/p:EnableDiagnostics=true` - Enables or disables diagnostic features in the native runtime.
+- **`WasmProfilers`** - `/p:WasmProfilers=...` - Changes profiler configuration in the native runtime.
+- **`EmccMaximumHeapSize`** - `/p:EmccMaximumHeapSize=...` - Controls memory layout configuration.
+- **`EmccInitialHeapSize`** - `/p:EmccInitialHeapSize=...` - Controls memory layout together with `EmccMaximumHeapSize`. Heap size configuration applies only for browser scenarios.
+- **`WasmBuildArgs`** - Any change to arguments passed via `/p:WasmBuildArgs=...` (such as enabling/disabling additional features or options) will trigger a relink.
+- **Configuration/Target Architecture** - Changing `/p:Configuration=Debug|Release` or `/p:RuntimeIdentifier=browser-wasm`, etc., can require relinking for correct native output.
+
+#### Notes
+
+- Relinking ensures that the produced WebAssembly binaries reflect the current set of build options and runtime features.
+- For incremental developer workflows, minimizing unnecessary relinks speeds up build times.
+- The relink process is managed by MSBuild targets in `browser.proj`—refer to that file for the most up-to-date logic.
+- Source changes to native code (C/C++/Emscripten sources) in `src/mono/browser` or dependent directories will naturally trigger a relink.
+
+For questions or advanced scenarios, see the [WebAssembly build instructions](../../../docs/workflow/building/libraries/webassembly-instructions.md).
+
 ## Upgrading Emscripten

 Bumping Emscripten version involves these steps:
--- a/src/mono/browser/browser.proj
+++ b/src/mono/browser/browser.proj
@ -341,7 +341,9 @@
      { "identity": "WasmEnableExceptionHandling",  "defaultValueInRuntimePack": "$(WasmEnableExceptionHandling)" },
      { "identity": "EnableDiagnostics",            "defaultValueInRuntimePack": "$(EnableDiagnostics)" },
      { "identity": "WasmProfilers",                "defaultValueInRuntimePack": "$(WasmProfilers)" },
-      { "identity": "EmccMaximumHeapSize",          "defaultValueInRuntimePack": "$(EmccMaximumHeapSize)" }
+      { "identity": "EmccMaximumHeapSize",          "defaultValueInRuntimePack": "$(EmccMaximumHeapSize)" },
+      { "identity": "EmccInitialHeapSize",          "defaultValueInRuntimePack": "$(EmccInitialHeapSize)" },
+      { "identity": "RunAOTCompilation",            "defaultValueInRuntimePack": "$(RunAOTCompilation)" }
    ]
  }
 }
--- a/src/mono/wasi/README.md
+++ b/src/mono/wasi/README.md
@ -42,6 +42,35 @@ you will need to separately download a WASI SDK from https://github.com/WebAssem
 - `InvariantGlobalization` - remove globalization support, decrease the publish size.
 - More details can be found at https://github.com/dotnet/runtime/blob/main/src/mono/wasm/build/WasmApp.Common.targets and https://github.com/dotnet/runtime/blob/main/src/mono/wasi/build/WasiApp.targets

+## Properties That Trigger Relinking
+
+### What is Relinking?
+
+Relinking in WASI builds refers to regenerating the native WASI runtime artifacts (such as `dotnet.native.wasi`, etc.) to reflect changes in configuration, features, or source. This process is essential for producing correct, optimized binaries for WASI environments.
+
+### Properties That Trigger Relinking in `wasi.proj`
+
+The following MSBuild properties will trigger a relinking during the WASI build process:
+
+- **`WasiBuildNative`** - `/p:WasiBuildNative=true` - Forces a rebuild of all native WASI binaries, regardless of detected changes.
+- **`WasiRelinkNative`** - `/p:WasiRelinkNative=true` - Explicitly requests relinking of native WASI artifacts.
+- **`RunAOTCompilation`** - `/p:RunAOTCompilation=true` - Enables AOT compilation for WASI. Changing this property requires relinking for correct WASI output.
+- **`WasmSingleFileBundle`** - `/p:WasmSingleFileBundle=true` - Bundles all assets into the `.wasm` file, requiring native relinking.
+- **`EnableDiagnostics`** - `/p:EnableDiagnostics=true` - Enables or disables diagnostic features in the native runtime.
+- **`WasmProfilers`** - `/p:WasmProfilers=...` - Changes profiler configuration in the native runtime.
+- **`WasmEnableSIMD`** - `/p:WasmEnableSIMD=true` - Enables or disables SIMD instruction support.
+- **`WasiBuildArgs`** - Any change to `/p:WasiBuildArgs=...` (custom build flags or feature toggles) can trigger a relink.
+- **Configuration/Target Architecture** - Changing `/p:Configuration=Debug|Release` or `/p:RuntimeIdentifier=wasi-wasm`, etc., may require relinking.
+
+#### Notes
+
+- Correct relinking ensures WASI binaries are up-to-date and accurately reflect the intended configuration.
+- Avoid unnecessary relinking for faster incremental builds.
+- The relink logic is defined in `wasi.proj` and supporting MSBuild files.
+- Source changes to native sources in `src/mono/wasi` or related directories will always trigger a relink.
+
+For more detailed WASI build and configuration guidance, see the [WASI build documentation](../../../docs/workflow/building/libraries/webassembly-instructions.md).
+
 ## How it works

 The mechanism for executing .NET code in a WASI runtime environment is equivalent to how `dotnet.wasm` executes .NET code in a browser environment. That is, it runs the Mono interpreter to execute .NET bytecode that has been built in the normal way. It should also work with AOT but this is not yet attempted.
--- a/src/mono/wasi/wasi.proj
+++ b/src/mono/wasi/wasi.proj
@ -165,7 +165,8 @@
      { "identity": "WasmSingleFileBundle",   "defaultValueInRuntimePack": "$(WasmSingleFileBundle)" },
      { "identity": "EnableDiagnostics",      "defaultValueInRuntimePack": "$(EnableDiagnostics)" },
      { "identity": "WasmProfilers",          "defaultValueInRuntimePack": "$(WasmProfilers)" },
-      { "identity": "WasmEnableSIMD",         "defaultValueInRuntimePack": "$(WasmEnableSIMD)" }
+      { "identity": "WasmEnableSIMD",         "defaultValueInRuntimePack": "$(WasmEnableSIMD)" },
+      { "identity": "RunAOTCompilation",      "defaultValueInRuntimePack": "$(RunAOTCompilation)" }
    ]
  }
 }
--- a/src/mono/wasm/Wasm.Build.Tests/Blazor/MiscTests.cs
+++ b/src/mono/wasm/Wasm.Build.Tests/Blazor/MiscTests.cs
@ -66,14 +66,14 @@ public class MiscTests : BlazorWasmTestBase
                                    : "<RunAOTCompilation>true</RunAOTCompilation>";
        ProjectInfo info = CopyTestAsset(config, aot: true, TestAsset.BlazorBasicTestApp, "blz_aot_prj_file", extraProperties: extraProperties);

-        // No relinking, no AOT
-        BlazorBuild(info, config);
+        // build relinks
+        BlazorBuild(info, config, isNativeBuild: true);

        // will aot
        BlazorPublish(info, config, new PublishOptions(UseCache: false, AOT: true));

        // build again
-        BlazorBuild(info, config, new BuildOptions(UseCache: false));
+        BlazorBuild(info, config, new BuildOptions(UseCache: false), isNativeBuild: true);
    }

    [Fact]
--- a/src/mono/wasm/Wasm.Build.Tests/BuildPublishTests.cs
+++ b/src/mono/wasm/Wasm.Build.Tests/BuildPublishTests.cs
@ -55,7 +55,7 @@ namespace Wasm.Build.Tests
            ProjectInfo info = CopyTestAsset(config, aot, TestAsset.WasmBasicTestApp, "build_publish");
            
            bool isPublish = false;
-            (_, string output) = BuildProject(info, config, new BuildOptions(Label: "first_build", AOT: aot));
+            (_, string output) = BuildProject(info, config, new BuildOptions(Label: "first_build", AOT: aot), isNativeBuild: aot);
            
            BuildPaths paths = GetBuildPaths(config, forPublish: isPublish);
            IDictionary<string, (string fullPath, bool unchanged)> pathsDict =
@ -63,10 +63,10 @@ namespace Wasm.Build.Tests
            
            string mainDll = $"{info.ProjectName}.dll";
            var firstBuildStat = StatFiles(pathsDict);
-            Assert.False(firstBuildStat["pinvoke.o"].Exists);
+            Assert.True(firstBuildStat["pinvoke.o"].Exists);
            Assert.False(firstBuildStat[$"{mainDll}.bc"].Exists);
-            
-            CheckOutputForNativeBuild(expectAOT: false, expectRelinking: isPublish, info.ProjectName, output);
+
+            CheckOutputForNativeBuild(expectAOT: false, expectRelinking: isPublish || aot, info.ProjectName, output);

            if (!_buildContext.TryGetBuildFor(info, out BuildResult? result))
                throw new XunitException($"Test bug: could not get the build result in the cache");
@ -88,7 +88,7 @@ namespace Wasm.Build.Tests
            IDictionary<string, FileStat> publishStat = StatFiles(pathsDict);
            Assert.True(publishStat["pinvoke.o"].Exists);
            Assert.True(publishStat[$"{mainDll}.bc"].Exists);
-            CheckOutputForNativeBuild(expectAOT: true, expectRelinking: isPublish, info.ProjectName, output);
+            CheckOutputForNativeBuild(expectAOT: true, expectRelinking: isPublish || aot, info.ProjectName, output);
            
            // source maps are created for build but not for publish, make sure CompareStat won't expect them in publish:
            pathsDict["dotnet.js.map"] = (pathsDict["dotnet.js.map"].fullPath, unchanged: false);
@ -98,11 +98,11 @@ namespace Wasm.Build.Tests

            // second build
            isPublish = false;
-            (_, output) = BuildProject(info, config, new BuildOptions(Label: "second_build", UseCache: false, AOT: aot));
+            (_, output) = BuildProject(info, config, new BuildOptions(Label: "second_build", UseCache: false, AOT: aot), isNativeBuild: aot);
            var secondBuildStat = StatFiles(pathsDict);
            
            // no relinking, or AOT
-            CheckOutputForNativeBuild(expectAOT: false, expectRelinking: isPublish, info.ProjectName, output);
+            CheckOutputForNativeBuild(expectAOT: false, expectRelinking: isPublish || aot, info.ProjectName, output);

            // no native files changed
            pathsDict.UpdateTo(unchanged: true);
--- a/src/mono/wasm/Wasm.Build.Tests/SatelliteAssembliesTests.cs
+++ b/src/mono/wasm/Wasm.Build.Tests/SatelliteAssembliesTests.cs
@ -57,7 +57,7 @@ namespace Wasm.Build.Tests
        [Theory]
        [MemberData(nameof(SatelliteAssemblyTestData), parameters: new object[] { /*aot*/ false, /*relinking*/ false })]
        [MemberData(nameof(SatelliteAssemblyTestData), parameters: new object[] { /*aot*/ false, /*relinking*/ true })]
-        [MemberData(nameof(SatelliteAssemblyTestData), parameters: new object[] { /*aot*/ true,  /*relinking*/ false })]
+        [MemberData(nameof(SatelliteAssemblyTestData), parameters: new object[] { /*aot*/ true,  /*relinking*/ true })]
        public async void ResourcesFromProjectReference(Configuration config, bool aot, bool nativeRelink, string? argCulture)
        {
            string prefix = $"SatelliteAssemblyFromProjectRef";
--- a/src/mono/wasm/Wasm.Build.Tests/WasmNativeDefaultsTests.cs
+++ b/src/mono/wasm/Wasm.Build.Tests/WasmNativeDefaultsTests.cs
@ -28,6 +28,7 @@ namespace Wasm.Build.Tests
                ("InvariantTimezone", false),
                ("InvariantGlobalization", false),
                // ("WasmNativeStrip", true) -- tested separately because it has special handling in targets
+                // ("RunAOTCompilation", false) -- tested separately as it changes build behavior significantly
            };

            TheoryData<Configuration, string, bool, bool, bool> data = new();