Add .NET 10 support via NativeAOT-LLVM along side .NET 8 support (#4915)

# Description of changes

Builds on #4741 to clean up and refine the NativeAOT-LLVM integration.
The major changes:

- **Standardized the repo on .NET 10 SDK** (`global.json` → `10.0.100`).
The team is migrating to .NET 10 ahead of .NET 8 EOL. End users are
unaffected as their SDK version is controlled by their own `global.json`
emitted by `spacetime init`.

- **Multi-target NuGet packages** instead of conditional single-target:
  - `SpacetimeDB.Runtime` now unconditionally targets `net8.0;net10.0`
- `SpacetimeDB.BSATN.Runtime` now unconditionally targets
`netstandard2.1;net8.0;net10.0`
- NuGet packages ship both TFMs in a single `.nupkg`. No
`EXPERIMENTAL_WASM_AOT` env var needed at pack time
- `EXPERIMENTAL_WASM_AOT` define constant is set automatically when
`TargetFramework == net10.0`
- `ILCompiler.LLVM` package references conditioned on `TargetFramework
== net10.0` (not env var)

- **Centralized NativeAOT-LLVM build logic** in
`SpacetimeDB.Runtime.props` and `SpacetimeDB.Runtime.targets`:
- Moved `PublishTrimmed`, `SelfContained`, `WasmEnableThreads` into
`.props` (previously duplicated across 4+ `.csproj` files)
- Moved the `.wit`-stripping `UseWasiRuntimeOverlayWithoutComponentWit`
target into `.targets` (was duplicated in every server `.csproj`)
- Added `IlcLlvmTarget=wasm32-unknown-wasip1` override after
ILCompiler.LLVM.targets import (previously passed as `/p:` arg)
- Added `_InitializeWasiSdk` to `ObtainWasiSdk` BeforeTargets for .NET
10 compatibility
  - Consumer `.csproj` files no longer need any AOT boilerplate

- **Refactored `csharp.rs` build logic** to support three build paths
via `CsharpBuildPath` enum:
- `Net8Jit` : stable .NET 8 path using `wasi-experimental` workload
(Mono WASM)
- `Net8Aot` : .NET 8 NativeAOT-LLVM (opt-in via `--native-aot` or
`EXPERIMENTAL_WASM_AOT=1`)
- `Net10Aot` : .NET 10 NativeAOT-LLVM (auto-detected when .NET 10 SDK is
active)
- Auto-detects .NET SDK version from `dotnet --version` (respects
`global.json`)
- Automatically sets `EXPERIMENTAL_WASM_AOT=1` for AOT paths so MSBuild
conditionals activate
- Unified `dotnet publish` command for all paths. Build-specific config
handled by props/targets
- Removed redundant `/p:IlcLlvmTarget` and `/p:WasmEnableThreads` CLI
args (now in `.targets`)

- **Refactored `init.rs`** for .NET version-aware scaffolding:
  - Added `--dotnet-version` CLI arg to explicitly select .NET 8 or 10
- Added `resolve_dotnet_major()` which auto-detects or prompts
interactively when multiple SDKs are installed
  - .NET 10 auto-enables NativeAOT-LLVM (`--native-aot` not required)
- .NET 10 template emits `<TargetFramework>net10.0</TargetFramework>`
directly (no conditional)
- .NET 8 AOT template adds `ILCompiler.LLVM 8.0.0-*` package refs gated
on `EXPERIMENTAL_WASM_AOT=1`
- Emits correct `global.json` per SDK version (`8.0.100` or `10.0.100`)

- **Added `_initialize` call in `wasmtime_module.rs`**: NativeAOT-LLVM
modules are WASI reactors that export `_initialize` to bootstrap the
native runtime. This is called before preinit functions. Traditional
.NET 8 WASI modules export `_start` instead and are unaffected.

- **Updated `FFI.cs` `WasmImportLinkageAttribute` guard** to `#if
EXPERIMENTAL_WASM_AOT && NET10_0_OR_GREATER`, ensuring the real
attribute is only used when both the AOT flag and .NET 10+ TFM are
active. The dummy shim is used for all other builds.

- **Updated `csharp_aot_module.rs` smoketest**:
  - Auto-detects .NET SDK version and adjusts TFM accordingly
- .NET 8 AOT: Windows-only (ILCompiler.LLVM 8.0.0-* not published for
Linux)
  - .NET 10 AOT: Windows and Linux
- Removed emscripten dependency (NativeAOT-LLVM uses WASI SDK, not
emscripten)

- **Updated CLI reference docs** to reflect `--native-aot` behavior
change (not needed for .NET 10) and new `--dotnet-version` arg.

This PR addresses several issues from #4741 review:

1. **NativeAOT-LLVM build logic was duplicated** in every server
`.csproj` (4+ files had identical `PropertyGroup` and `Target` blocks).
This is now centralized in the shipped `.props`/`.targets`.

2. **NuGet packages only shipped a single TFM**. The env var controlled
which TFM was built, meaning you needed `EXPERIMENTAL_WASM_AOT=1` at
pack time to get the `net10.0` DLL. Now both TFMs are always included.

3. **`spacetime init` emitted unnecessary conditional wrappers** in the
generated `.csproj` for .NET 10 projects. Since the project is
definitively targeting .NET 10, the TFM should be unconditional.

4. **`spacetime publish` passed MSBuild properties via `/p:` args** that
are now handled by centralized `.targets`, simplifying the CLI code.

# API and ABI breaking changes

- `global.json` now requires .NET 10 SDK for repo development. All
developers and CI agents need .NET SDK 10.0+ installed.
- End user module projects are **not affected**. They continue to use
whichever SDK their local `global.json` specifies.
- .NET 8 JIT and .NET 8 AOT paths remain functional for end users until
.NET 8 EOL.

# Expected complexity level and risk

2 - The core risk is the same as #4741: future changes in the upstream
NativeAOT-LLVM/WASI pipeline. Centralizing the build logic in
`.props`/`.targets` reduces the surface area for breaking changes (one
place to update vs. N consumer projects). The `.wit`-stripping
workaround remains necessary until
[dotnet/runtimelab#3144](dotnet/runtimelab#3144)
is resolved.

# Testing

- Ran C# module publish + client connection tests for all three build
paths:
  - .NET 8 JIT (`spacetime publish` without `--native-aot`)
- .NET 8 AOT (`spacetime publish` with `EXPERIMENTAL_WASM_AOT=1` and
.NET 8 SDK)
  - .NET 10 AOT (`spacetime publish` with .NET 10 SDK, auto-detected)
- Verified `spacetime init --lang csharp` generates correct project
structure for both .NET 8 and .NET 10
- Verified `spacetime init --lang csharp --dotnet-version 10` emits
`net10.0` TFM and `10.0.100` in `global.json`
- Verified C# regression tests complete successfully when ran under .NET
8 JIT, .NET 8 AOT, .NET 10 AOT
- This required making local customizations to the repo versions of the
regression tests, in order to conform to the configuration output by
`spacetime init`, but the tests themselves remained identical.
- Verified NuGet packages contain both `lib/net8.0/` and `lib/net10.0/`
DLLs
- Updated smoketest `test_build_csharp_module_aot` to work with both
.NET 8 and .NET 10 SDK

---------

Signed-off-by: Ryan <r.ekhoff@clockworklabs.io>
Co-authored-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>
Co-authored-by: Lisandro Crespo <lisandroct@gmail.com>
Co-authored-by: Zeke Foppa <196249+bfops@users.noreply.github.com>

Author: 5 people

.github/workflows/ci.yml

@@ -184,7 +184,13 @@ jobs:
           cd modules
           # the sdk-manifests on windows-latest are messed up, so we need to update them
           dotnet workload config --update-mode manifests
-          dotnet workload update
+          dotnet workload update --from-previous-sdk
+          # Explicitly install wasi-experimental for .NET 8 SDK (needed for test_build_csharp_module)
+          # Create temp global.json to target .NET 8 SDK for workload install
+          $sdk8Json = '{"sdk":{"version":"8.0.400","rollForward":"latestFeature"}}'
+          $sdk8Json | Out-File -FilePath global.json -Encoding utf8
+          dotnet workload install wasi-experimental
+          Remove-Item global.json
 
       - name: Override NuGet packages
         shell: bash
@@ -1075,6 +1081,16 @@ jobs:
         with:
           global-json-file: global.json
 
+      - name: Install .NET workloads
+        run: |
+          dotnet workload config --update-mode manifests
+          dotnet workload update --from-previous-sdk
+          # Explicitly install wasi-experimental for .NET 8 SDK (needed for test_build_csharp_module)
+          # Create temp global.json to target .NET 8 SDK for workload install
+          echo '{"sdk":{"version":"8.0.100","rollForward":"latestFeature"}}' > global.json
+          dotnet workload install wasi-experimental
+          rm global.json
+
       - name: Override NuGet packages
         run: |
           dotnet pack crates/bindings-csharp/BSATN.Runtime
@@ -1146,9 +1162,11 @@ jobs:
 
       - name: Check quickstart-chat bindings are up to date
         run: |
-          bash sdks/csharp/tools~/gen-quickstart.sh
+          for dotnet_version in 8 10; do
+            bash sdks/csharp/tools~/gen-quickstart.sh "$dotnet_version"
+          done
           tools/check-diff.sh templates/chat-console-cs/module_bindings || {
-              echo 'Error: quickstart-chat bindings have changed. Please run `sdks/csharp/tools~/gen-quickstart.sh`.'
+              echo 'Error: quickstart-chat bindings have changed. Please run `sdks/csharp/tools~/gen-quickstart.sh 10`.'
               exit 1
           }
 
@@ -1170,6 +1188,21 @@ jobs:
       - name: Run regression tests
         run: |
           bash sdks/csharp/tools~/run-regression-tests.sh
+          # Restore global.json symlinks (we replaced them with files to work around .NET 10 SDK bug)
+          # server is 5 levels deep from root, republishing dirs are 6 levels deep
+          if [ -f sdks/csharp/examples~/regression-tests/server/global.json ] && [ ! -L sdks/csharp/examples~/regression-tests/server/global.json ]; then
+            echo "Restoring symlink at server/global.json"
+            rm -f sdks/csharp/examples~/regression-tests/server/global.json
+            ln -s ../../../../../global.json sdks/csharp/examples~/regression-tests/server/global.json
+          fi
+          for dir in sdks/csharp/examples~/regression-tests/republishing/server-initial \
+                     sdks/csharp/examples~/regression-tests/republishing/server-republish; do
+            if [ -f "$dir/global.json" ] && [ ! -L "$dir/global.json" ]; then
+              echo "Restoring symlink at $dir/global.json"
+              rm -f "$dir/global.json"
+              ln -s ../../../../../../global.json "$dir/global.json"
+            fi
+          done
           tools/check-diff.sh sdks/csharp/examples~/regression-tests || {
               echo 'Error: Bindings are dirty. Please run `sdks/csharp/tools~/gen-regression-tests.sh`.'
               exit 1

crates/bindings-csharp/BSATN.Codegen/BSATN.Codegen.csproj

@@ -20,6 +20,7 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <!-- Keep the shipped analyzer loadable by the .NET 8 compiler host. -->
     <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.3.1" PrivateAssets="all" />
   </ItemGroup>
 

crates/bindings-csharp/BSATN.Codegen/Diag.cs

@@ -164,13 +164,16 @@ EnumDeclarationSyntax @enum
             @enum => @enum.Members[256]
         );
 
-    public static readonly ErrorDescriptor<INamedTypeSymbol> TaggedEnumInlineTuple =
+    public static readonly ErrorDescriptor<(
+        INamedTypeSymbol baseType,
+        SyntaxNode location
+    )> TaggedEnumInlineTuple =
         new(
             group,
             "Tagged enum variants must be declared with inline tuples",
-            baseType =>
-                $"{baseType} does not have the expected format SpacetimeDB.TaggedEnum<(TVariant1 v1, ..., TVariantN vN)>.",
-            baseType => baseType
+            ctx =>
+                $"{ctx.baseType} does not have the expected format SpacetimeDB.TaggedEnum<(TVariant1 v1, ..., TVariantN vN)>.",
+            ctx => ctx.location
         );
 
     public static readonly ErrorDescriptor<IFieldSymbol> TaggedEnumField =

crates/bindings-csharp/BSATN.Codegen/Type.cs

@@ -563,7 +563,13 @@ public BaseTypeDeclaration(GeneratorAttributeSyntaxContext context, DiagReporter
                 is not INamedTypeSymbol { IsTupleType: true, TupleElements: var taggedEnumVariants }
             )
             {
-                diag.Report(ErrorDescriptor.TaggedEnumInlineTuple, type.BaseType);
+                diag.Report(
+                    ErrorDescriptor.TaggedEnumInlineTuple,
+                    (
+                        type.BaseType,
+                        (SyntaxNode?)typeSyntax.BaseList?.Types.FirstOrDefault()?.Type ?? typeSyntax
+                    )
+                );
             }
 
             if (fields.FirstOrDefault() is { } field)

crates/bindings-csharp/BSATN.Runtime.Tests/BSATN.Runtime.Tests.csproj

@@ -5,7 +5,7 @@
   </PropertyGroup>
 
   <PropertyGroup>
-    <TargetFrameworks>net8.0</TargetFrameworks>
+    <TargetFrameworks>net8.0;net10.0</TargetFrameworks>
     <RootNamespace>SpacetimeDB</RootNamespace>
     <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
   </PropertyGroup>

crates/bindings-csharp/BSATN.Runtime/BSATN.Runtime.csproj

@@ -9,7 +9,7 @@
 
   <PropertyGroup>
     <!-- Note: the binary produced by this package is used in Unity too, which is limited to .NET Standard 2.1. -->
-    <TargetFrameworks>netstandard2.1;net8.0</TargetFrameworks>
+    <TargetFrameworks>netstandard2.1;net8.0;net10.0</TargetFrameworks>
     <RootNamespace>SpacetimeDB</RootNamespace>
     <!-- You can enable this when debugging codegen problems. Outputs in obj/debug/[version]/generated. -->
     <!-- <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles> -->

crates/bindings-csharp/Codegen.Tests/Codegen.Tests.csproj

@@ -6,7 +6,7 @@
   </PropertyGroup>
 
   <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFrameworks>net8.0;net10.0</TargetFrameworks>
     <RootNamespace>SpacetimeDB.Codegen.Tests</RootNamespace>
     <DefaultItemExcludes>$(DefaultItemExcludes);fixtures/**/*</DefaultItemExcludes>
   </PropertyGroup>
@@ -18,17 +18,29 @@
 
   <ItemGroup>
     <PackageReference Include="CSharpier.Core" Version="0.28.2" />
-    <PackageReference Include="Microsoft.CodeAnalysis.Common" Version="4.10.0" />
-    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.10.0" />
-    <PackageReference Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.10.0" />
-    <PackageReference Include="Microsoft.Extensions.Logging" Version="8.0.0" />
     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.6.0" />
     <PackageReference Include="Verify.SourceGenerators" Version="2.4.3" />
     <PackageReference Include="Verify.XUnit" Version="26.4.5" />
     <PackageReference Include="xunit" Version="2.9.0" />
     <PackageReference Include="xunit.runner.visualstudio" Version="2.8.1" PrivateAssets="all" />
   </ItemGroup>
 
+  <ItemGroup Condition="$(TargetFramework.StartsWith('net8.'))">
+    <PackageReference Include="Microsoft.CodeAnalysis.Common" Version="4.14.0" />
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.14.0" />
+    <PackageReference Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="4.14.0" />
+    <PackageReference Include="Microsoft.Build.Tasks.Core" Version="17.11.48" PrivateAssets="all" />
+    <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.0" />
+    <PackageReference Include="System.Security.Cryptography.Xml" Version="10.0.9" PrivateAssets="all" />
+  </ItemGroup>
+
+  <ItemGroup Condition="$(TargetFramework.StartsWith('net10.'))">
+    <PackageReference Include="Microsoft.CodeAnalysis.Common" Version="5.0.0" />
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="5.0.0" />
+    <PackageReference Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" Version="5.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.0" />
+  </ItemGroup>
+
   <ItemGroup>
     <ProjectReference Include="../Codegen/Codegen.csproj" />
   </ItemGroup>

crates/bindings-csharp/Codegen.Tests/Tests.cs

@@ -26,19 +26,19 @@ public static class GeneratorSnapshotTests
 
     record struct StepOutput(string Key, IncrementalStepRunReason Reason, object Value);
 
-    class Fixture
+    private class Fixture
     {
         private readonly string projectDir;
-        private readonly CSharpCompilation sampleCompilation;
+        public CSharpCompilation SampleCompilation { get; }
+        public CSharpParseOptions ParseOptions { get; }
 
         public Fixture(string projectDir, CSharpCompilation sampleCompilation)
         {
             this.projectDir = projectDir;
-            this.sampleCompilation = sampleCompilation;
+            SampleCompilation = sampleCompilation;
+            ParseOptions = (CSharpParseOptions)sampleCompilation.SyntaxTrees.First().Options;
         }
 
-        public CSharpCompilation SampleCompilation => sampleCompilation;
-
         public static async Task<Fixture> Compile(string name)
         {
             var projectDir = Path.Combine(GetProjectDir(), "fixtures", name);
@@ -53,7 +53,7 @@ public Task Verify(string fileName, object target) =>
 
         private static CSharpGeneratorDriver CreateDriver(
             IIncrementalGenerator generator,
-            LanguageVersion languageVersion
+            CSharpParseOptions parseOptions
         )
         {
             return CSharpGeneratorDriver.Create(
@@ -62,39 +62,39 @@ LanguageVersion languageVersion
                     disabledOutputs: IncrementalGeneratorOutputKind.None,
                     trackIncrementalGeneratorSteps: true
                 ),
-                // Make sure that generated files are parsed with the same language version.
-                parseOptions: new(languageVersion)
+                // Make sure generated files are parsed with the same language version and feature flags.
+                parseOptions: parseOptions
             );
         }
 
         private async Task<IEnumerable<SyntaxTree>> RunAndCheckGenerator(
             IIncrementalGenerator generator
         )
         {
-            var driver = CreateDriver(generator, sampleCompilation.LanguageVersion);
+            var driver = CreateDriver(generator, ParseOptions);
 
             // Store the new driver instance - it contains the results and the cache.
-            var driverAfterGen = driver.RunGenerators(sampleCompilation);
+            var driverAfterGen = driver.RunGenerators(SampleCompilation);
             var genResult = driverAfterGen.GetRunResult();
 
             // Verify the generated code against the snapshots.
             await Verify(generator.GetType().Name, genResult);
 
-            CheckCacheWorking(sampleCompilation, driverAfterGen);
+            CheckCacheWorking(SampleCompilation, driverAfterGen);
 
             return genResult.GeneratedTrees;
         }
 
         public GeneratorDriverRunResult RunGeneratorAndGetResult(IIncrementalGenerator generator)
         {
-            var driver = CreateDriver(generator, sampleCompilation.LanguageVersion);
-            return driver.RunGenerators(sampleCompilation).GetRunResult();
+            var driver = CreateDriver(generator, ParseOptions);
+            return driver.RunGenerators(SampleCompilation).GetRunResult();
         }
 
         public async Task<CSharpCompilation> RunAndCheckGenerators(
             params IIncrementalGenerator[] generators
         ) =>
-            sampleCompilation.AddSyntaxTrees(
+            SampleCompilation.AddSyntaxTrees(
                 (await Task.WhenAll(generators.Select(RunAndCheckGenerator))).SelectMany(output =>
                     output
                 )
@@ -241,10 +241,7 @@ public static async Task TypeAndModuleGeneratorsOnServer()
         // make sure a downstream "user" file that references SpacetimeDB.Local doesn't trigger CS0436.
         var userCode =
             "namespace User; public sealed class UseLocal { public SpacetimeDB.Local Db; }";
-        var userTree = CSharpSyntaxTree.ParseText(
-            userCode,
-            new CSharpParseOptions(compilationAfterGen.LanguageVersion)
-        );
+        var userTree = CSharpSyntaxTree.ParseText(userCode, fixture.ParseOptions);
         var compilationWithUserCode = compilationAfterGen.AddSyntaxTrees(userTree);
         AssertNoCs0436Diagnostics(compilationWithUserCode);
     }
@@ -332,8 +329,11 @@ public static void @params(ProcedureContext ctx)
             }
             """;
 
-        var parseOptions = new CSharpParseOptions(fixture.SampleCompilation.LanguageVersion);
-        var tree = CSharpSyntaxTree.ParseText(source, parseOptions, path: "KeywordNames.cs");
+        var tree = CSharpSyntaxTree.ParseText(
+            source,
+            fixture.ParseOptions,
+            path: "KeywordNames.cs"
+        );
         var compilation = fixture.SampleCompilation.AddSyntaxTrees(tree);
 
         var driver = CSharpGeneratorDriver.Create(
@@ -345,7 +345,7 @@ public static void @params(ProcedureContext ctx)
                 disabledOutputs: IncrementalGeneratorOutputKind.None,
                 trackIncrementalGeneratorSteps: true
             ),
-            parseOptions: parseOptions
+            parseOptions: fixture.ParseOptions
         );
 
         var runResult = driver.RunGenerators(compilation).GetRunResult();

crates/bindings-csharp/Codegen.Tests/fixtures/diag/diag.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFramework>net10.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
   </PropertyGroup>