[wasm] Add missing properties to PropertiesThatTriggerRelinking for WASM and WASI (#117983)

* Add missing properties to PropertiesThatTriggerRelinking for WASM and WASI

* Add WasmEnableThreads property to relink triggering tests

* Add documentation for properties that trigger relinking in WASM and WASI builds

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: ilonatommy <[email protected]>

Author: Copilot

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:

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)" }
     ]
   }
 }

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.

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)" }
     ]
   }
 }

src/mono/wasm/Wasm.Build.Tests/Blazor/MiscTests.cs

@@ -66,14 +66,14 @@ public void DefaultTemplate_AOT_InProjectFile(Configuration config)
                                     : "<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]

src/mono/wasm/Wasm.Build.Tests/BuildPublishTests.cs

@@ -55,18 +55,18 @@ public async Task BuildThenPublishWithAOT(Configuration config, bool aot)
             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 =
                 GetFilesTable(info.ProjectName, aot, paths, unchanged: false);
 
             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 @@ public async Task BuildThenPublishWithAOT(Configuration config, bool aot)
             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 @@ public async Task BuildThenPublishWithAOT(Configuration config, bool aot)
 
             // 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);

src/mono/wasm/Wasm.Build.Tests/SatelliteAssembliesTests.cs

@@ -57,7 +57,7 @@ public async void ResourcesFromMainAssembly(Configuration config, bool aot, bool
         [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";

src/mono/wasm/Wasm.Build.Tests/WasmNativeDefaultsTests.cs

@@ -28,6 +28,7 @@ public static TheoryData<Configuration, string, bool, bool, bool> SettingDiffere
                 ("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();