Skip to content

Commit e4c2516

Browse files
jdetterjdetter
committed
Reapply "Update NativeAOT-LLVM infrastructure to current ABI (#4515)"
This reverts commit 5b47440.
1 parent c43439d commit e4c2516

43 files changed

Lines changed: 2466 additions & 46 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,10 @@ jobs:
102102
cd $env:USERPROFILE\emsdk
103103
.\emsdk install 4.0.21
104104
.\emsdk activate 4.0.21
105+
# Add emscripten to PATH for subsequent steps and subprocesses
106+
$emsdkPath = "$env:USERPROFILE\emsdk\upstream\emscripten"
107+
Add-Content -Path $env:GITHUB_PATH -Value $emsdkPath
108+
Write-Host "Added $emsdkPath to PATH"
105109
106110
- name: Install psql (Windows)
107111
if: runner.os == 'Windows'

‎crates/bindings-csharp/NATIVEAOT-LLVM.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# Using NativeAOT-LLVM with SpacetimeDB C# Modules
2+
3+
This guide provides instructions for enabling NativeAOT-LLVM compilation for C# SpacetimeDB modules, which can provide performance improvements.
4+
5+
## Overview
6+
7+
NativeAOT-LLVM compiles C# modules to native WebAssembly (WASM) instead of using the Mono runtime.
8+
9+
> [!WARNING]
10+
> This is currently only supported for Windows server modules and is experimental.
11+
12+
## Prerequisites
13+
14+
- **.NET SDK 8.x** (same version used by SpacetimeDB)
15+
- **Emscripten SDK (EMSDK)** installed (must contain `upstream/emscripten/emcc.bat`)
16+
- **(Optional) Binaryen (wasm-opt)** installed and on `PATH` (recommended: `version_116`)
17+
- **Windows** - NativeAOT-LLVM is currently only supported for Windows server modules
18+
19+
## Prerequisites Installation
20+
21+
### Install Emscripten SDK (EMSDK)
22+
23+
The Emscripten SDK is required for NativeAOT-LLVM compilation:
24+
25+
1. **Download and extract** the Emscripten SDK from `https://github.com/emscripten-core/emsdk`
26+
- Example path: `D:\Tools\emsdk`
27+
28+
2. **Set environment variable** (optional - the CLI will detect it automatically):
29+
```
30+
$env:EMSDK="D:\Tools\emsdk"
31+
```
32+
33+
### Install Binaryen (Optional)
34+
35+
Binaryen provides `wasm-opt` for WASM optimization (recommended for performance):
36+
37+
1. Download Binaryen https://github.com/WebAssembly/binaryen/releases/tag/version_116 for Windows
38+
2. Extract to e.g. `D:\Tools\binaryen`
39+
3. Add `D:\Tools\binaryen\bin` to `PATH`
40+
41+
To temporarily add to your current PowerShell session:
42+
```
43+
$env:PATH += ";D:\Tools\binaryen\bin"
44+
```
45+
4. Verify:
46+
```
47+
wasm-opt --version
48+
```
49+
50+
## Creating a New NativeAOT Project
51+
52+
When creating a new C# project, use the `--native-aot` flag:
53+
54+
```
55+
spacetime init --lang csharp --native-aot my-native-aot-project
56+
```
57+
58+
This automatically:
59+
- Creates a C# project with the required package references
60+
- Generates a `spacetime.json` with `"native-aot": true`
61+
- Configures the project for NativeAOT-LLVM compilation
62+
63+
## Converting an Existing Project
64+
65+
1. **Update spacetime.json**
66+
Add `"native-aot": true` to your `spacetime.json`:
67+
```json
68+
{
69+
"module": "your-module-name",
70+
"native-aot": true
71+
}
72+
```
73+
74+
**Note:** Once `spacetime.json` has `"native-aot": true`, you can simply run `spacetime publish` without the `--native-aot` flag. The CLI will automatically detect the configuration and use NativeAOT compilation.
75+
76+
2. **Ensure NuGet feed is configured**
77+
NativeAOT-LLVM packages come from **dotnet-experimental**. Add to `NuGet.Config`:
78+
```xml
79+
<?xml version="1.0" encoding="utf-8"?>
80+
<configuration>
81+
<packageSources>
82+
<clear />
83+
<add key="dotnet-experimental" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-experimental/nuget/v3/index.json" />
84+
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
85+
</packageSources>
86+
</configuration>
87+
```
88+
89+
3. **Add NativeAOT package references**
90+
Add this `ItemGroup` to your `.csproj`:
91+
```xml
92+
<ItemGroup Condition="'$(EXPERIMENTAL_WASM_AOT)' == '1'">
93+
<PackageReference Include="Microsoft.NET.ILLink.Tasks" Version="8.0.0-*" Condition="'$(ILLinkTargetsPath)' == ''" />
94+
<PackageReference Include="Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" />
95+
<PackageReference Include="runtime.$(NETCoreSdkPortableRuntimeIdentifier).Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" />
96+
</ItemGroup>
97+
```
98+
99+
Your complete `.csproj` should look like:
100+
```xml
101+
<Project Sdk="Microsoft.NET.Sdk">
102+
<PropertyGroup>
103+
<TargetFramework>net8.0</TargetFramework>
104+
<RuntimeIdentifier>wasi-wasm</RuntimeIdentifier>
105+
<ImplicitUsings>enable</ImplicitUsings>
106+
<Nullable>enable</Nullable>
107+
</PropertyGroup>
108+
<ItemGroup>
109+
<PackageReference Include="SpacetimeDB.Runtime" Version="2.0.*" />
110+
</ItemGroup>
111+
<ItemGroup Condition="'$(EXPERIMENTAL_WASM_AOT)' == '1'">
112+
<PackageReference Include="Microsoft.NET.ILLink.Tasks" Version="8.0.0-*" Condition="'$(ILLinkTargetsPath)' == ''" />
113+
<PackageReference Include="Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" />
114+
<PackageReference Include="runtime.$(NETCoreSdkPortableRuntimeIdentifier).Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" />
115+
</ItemGroup>
116+
</Project>
117+
```
118+
119+
## Publishing Your NativeAOT Module
120+
121+
After completing either the **Creating a New NativeAOT Project** or **Converting an Existing Project** steps above, you can publish your module normally:
122+
123+
```
124+
# From your project directory
125+
spacetime publish your-database-name
126+
```
127+
128+
If you have `"native-aot": true` in your `spacetime.json`, the CLI will automatically detect this and use NativeAOT compilation. Alternatively, you can use:
129+
130+
```
131+
spacetime publish --native-aot your-database-name
132+
```
133+
134+
The CLI will display "Using NativeAOT-LLVM compilation (experimental)" when NativeAOT is enabled.
135+
136+
## Troubleshooting
137+
138+
### Package source mapping enabled
139+
If you have **package source mapping** enabled in `NuGet.Config`, add mappings for the LLVM packages:
140+
141+
```xml
142+
<packageSourceMapping>
143+
<packageSource key="bsatn-runtime">
144+
<package pattern="SpacetimeDB.BSATN.Runtime" />
145+
</packageSource>
146+
<packageSource key="SpacetimeDB.Runtime">
147+
<package pattern="SpacetimeDB.Runtime" />
148+
</packageSource>
149+
<packageSource key="dotnet-experimental">
150+
<package pattern="Microsoft.DotNet.ILCompiler.LLVM" />
151+
<package pattern="runtime.*" />
152+
</packageSource>
153+
<packageSource key="nuget.org">
154+
<package pattern="*" />
155+
</packageSource>
156+
</packageSourceMapping>
157+
```
158+
159+
### wasi-experimental workload install fails
160+
If the CLI cannot install the `wasi-experimental` workload automatically, install it manually:
161+
162+
```
163+
dotnet workload install wasi-experimental
164+
```
165+
166+
### Duplicate PackageReference warning
167+
You may see a `NU1504` warning about duplicate `PackageReference` items. This is expected and non-blocking.
168+
169+
### Code generation failed
170+
If you see errors like "Code generation failed for method", ensure:
171+
1. You're using `SpacetimeDB.Runtime` version 2.0.4 or newer
172+
2. All required package references are in your `.csproj`
173+
3. The `dotnet-experimental` feed is configured in `NuGet.Config`
174+

‎crates/bindings-csharp/Runtime/Internal/Module.cs‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,6 +206,36 @@ internal RawModuleDefV10 BuildModuleDefinition()
206206

207207
public static class Module
208208
{
209+
// Workaround for NativeAOT-LLVM IL scanner bug:
210+
// The scanner fails to compute vtables for TaggedEnum<T> base types when
211+
// concrete subtypes are only encountered indirectly (e.g., through Equals
212+
// calls on types containing TaggedEnum fields). This occurs when no user
213+
// table has indexes/primary keys, so RawIndexAlgorithm is never directly
214+
// constructed in user code.
215+
// By referencing concrete TaggedEnum subtypes here, we ensure the IL scanner
216+
// always processes their vtables. One variant per TaggedEnum is sufficient.
217+
[System.Runtime.CompilerServices.MethodImpl(
218+
System.Runtime.CompilerServices.MethodImplOptions.NoInlining
219+
)]
220+
private static void EnsureNativeAotTypeRoots()
221+
{
222+
// These constructions are never executed at runtime — they exist solely
223+
// to make the IL scanner compute vtables for TaggedEnum subtypes.
224+
// The condition is always false but the scanner must assume it could be true.
225+
if (Environment.TickCount < 0 && Environment.TickCount > 0)
226+
{
227+
_ = new RawIndexAlgorithm.BTree(null!);
228+
_ = new RawConstraintDataV9.Unique(null!);
229+
_ = new RawModuleDef.V10(null!);
230+
_ = new RawModuleDefV10Section.Typespace(null!);
231+
_ = new ExplicitNameEntry.Table(null!);
232+
_ = new MiscModuleExport.TypeAlias(null!);
233+
_ = new RawMiscModuleExportV9.ColumnDefaultValue(null!);
234+
_ = new SpacetimeDB.Filter.Sql(null!);
235+
_ = new ViewResultHeader.RowData(default);
236+
}
237+
}
238+
209239
private static readonly RawModuleDefV10 moduleDef = new();
210240

211241
private static readonly List<IReducer> reducers = [];
@@ -419,6 +449,7 @@ private static void Write(this BytesSink sink, byte[] bytes)
419449

420450
public static void __describe_module__(BytesSink description)
421451
{
452+
EnsureNativeAotTypeRoots();
422453
try
423454
{
424455
var module = moduleDef.BuildModuleDefinition();

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
1313
<RootNamespace>SpacetimeDB</RootNamespace>
1414
<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
15+
<RestoreAdditionalProjectSources Condition="'$(EXPERIMENTAL_WASM_AOT)' == '1'">https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-experimental/nuget/v3/index.json;$(RestoreAdditionalProjectSources)</RestoreAdditionalProjectSources>
1516
</PropertyGroup>
1617

1718
<ItemGroup>
@@ -25,6 +26,13 @@
2526
<ProjectReference Include="../Codegen/Codegen.csproj" ReferenceOutputAssembly="false" />
2627
</ItemGroup>
2728

29+
<!-- These must be explicit package dependencies so NuGet consumers can resolve the LLVM toolchain. -->
30+
<ItemGroup Condition="'$(EXPERIMENTAL_WASM_AOT)' == '1'">
31+
<PackageReference Include="Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" IncludeAssets="All" />
32+
<PackageReference Include="runtime.$(NETCoreSdkPortableRuntimeIdentifier).Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" IncludeAssets="All" />
33+
<PackageReference Include="Microsoft.NET.ILLink.Tasks" Version="8.0.0-*" Condition="'$(ILLinkTargetsPath)' == ''" IncludeAssets="All" />
34+
</ItemGroup>
35+
2836
<ItemGroup>
2937
<None Include="README.md" Pack="true" PackagePath="" />
3038
<None Include="build/*" Pack="true" PackagePath="build" />

‎crates/bindings-csharp/Runtime/build/SpacetimeDB.Runtime.targets‎

Lines changed: 41 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,50 @@
11
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
22

3+
<Import
4+
Project="$(PkgMicrosoft_DotNet_ILCompiler_LLVM)\build\Microsoft.DotNet.ILCompiler.LLVM.targets"
5+
Condition="'$(EXPERIMENTAL_WASM_AOT)' == '1' and '$(ILCompilerTargetsPath)' == '' and '$(PkgMicrosoft_DotNet_ILCompiler_LLVM)' != '' and Exists('$(PkgMicrosoft_DotNet_ILCompiler_LLVM)\build\Microsoft.DotNet.ILCompiler.LLVM.targets')" />
6+
37
<ItemGroup Condition="'$(EXPERIMENTAL_WASM_AOT)' == '1'">
48
<NativeLibrary Include="$(MSBuildThisFileDirectory)..\bindings.c" />
59
<UnmanagedEntryPointsAssembly Include="SpacetimeDB.Runtime" />
610

7-
<WasmImport Include="$(SpacetimeNamespace)!table_id_from_name" />
8-
<WasmImport Include="$(SpacetimeNamespace)!index_id_from_name" />
9-
<WasmImport Include="$(SpacetimeNamespace)!datastore_table_row_count" />
10-
<WasmImport Include="$(SpacetimeNamespace)!datastore_table_scan_bsatn" />
11-
<WasmImport Include="$(SpacetimeNamespace)!datastore_index_scan_range_bsatn" />
12-
<WasmImport Include="$(SpacetimeNamespace)!datastore_btree_scan_bsatn" />
13-
<WasmImport Include="$(SpacetimeNamespace)!row_iter_bsatn_advance" />
14-
<WasmImport Include="$(SpacetimeNamespace)!row_iter_bsatn_close" />
15-
<WasmImport Include="$(SpacetimeNamespace)!datastore_insert_bsatn" />
16-
<WasmImport Include="$(SpacetimeNamespace)!datastore_delete_by_index_scan_range_bsatn" />
17-
<WasmImport Include="$(SpacetimeNamespace)!datastore_delete_by_btree_scan_bsatn" />
18-
<WasmImport Include="$(SpacetimeNamespace)!datastore_delete_all_by_eq_bsatn" />
19-
<WasmImport Include="$(SpacetimeNamespace)!bytes_source_read" />
20-
<WasmImport Include="$(SpacetimeNamespace)!bytes_sink_write" />
21-
<WasmImport Include="$(SpacetimeNamespace)!console_log" />
22-
<WasmImport Include="$(SpacetimeNamespace)!console_timer_start" />
23-
<WasmImport Include="$(SpacetimeNamespace)!console_timer_end" />
24-
<WasmImport Include="$(SpacetimeNamespace)!volatile_nonatomic_schedule_immediate" />
25-
<WasmImport Include="$(SpacetimeNamespace)!datastore_clear" />
26-
27-
<PackageReference Include="Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" />
28-
<PackageReference Include="runtime.win-x64.Microsoft.DotNet.ILCompiler.LLVM" Version="8.0.0-*" />
29-
<PackageReference Include="Microsoft.NET.ILLink.Tasks" Version="8.0.0-*" Condition="'$(ILLinkTargetsPath)' == ''" />
11+
<!-- spacetime_10.0 imports -->
12+
<WasmImport Include="spacetime_10.0!table_id_from_name" />
13+
<WasmImport Include="spacetime_10.0!index_id_from_name" />
14+
<WasmImport Include="spacetime_10.0!datastore_table_row_count" />
15+
<WasmImport Include="spacetime_10.0!datastore_table_scan_bsatn" />
16+
<WasmImport Include="spacetime_10.0!datastore_index_scan_range_bsatn" />
17+
<WasmImport Include="spacetime_10.0!datastore_btree_scan_bsatn" />
18+
<WasmImport Include="spacetime_10.0!row_iter_bsatn_advance" />
19+
<WasmImport Include="spacetime_10.0!row_iter_bsatn_close" />
20+
<WasmImport Include="spacetime_10.0!datastore_insert_bsatn" />
21+
<WasmImport Include="spacetime_10.0!datastore_update_bsatn" />
22+
<WasmImport Include="spacetime_10.0!datastore_delete_by_index_scan_range_bsatn" />
23+
<WasmImport Include="spacetime_10.0!datastore_delete_by_btree_scan_bsatn" />
24+
<WasmImport Include="spacetime_10.0!datastore_delete_all_by_eq_bsatn" />
25+
<WasmImport Include="spacetime_10.0!bytes_source_read" />
26+
<WasmImport Include="spacetime_10.0!bytes_sink_write" />
27+
<WasmImport Include="spacetime_10.0!console_log" />
28+
<WasmImport Include="spacetime_10.0!console_timer_start" />
29+
<WasmImport Include="spacetime_10.0!console_timer_end" />
30+
<WasmImport Include="spacetime_10.0!volatile_nonatomic_schedule_immediate" />
31+
<WasmImport Include="spacetime_10.0!identity" />
32+
33+
<!-- spacetime_10.1 imports -->
34+
<WasmImport Include="spacetime_10.1!bytes_source_remaining_length" />
35+
36+
<!-- spacetime_10.2 imports -->
37+
<WasmImport Include="spacetime_10.2!get_jwt" />
38+
39+
<!-- spacetime_10.3 imports -->
40+
<WasmImport Include="spacetime_10.3!procedure_start_mut_tx" />
41+
<WasmImport Include="spacetime_10.3!procedure_commit_mut_tx" />
42+
<WasmImport Include="spacetime_10.3!procedure_abort_mut_tx" />
43+
<WasmImport Include="spacetime_10.3!procedure_http_request" />
44+
45+
<!-- spacetime_10.4 imports -->
46+
<WasmImport Include="spacetime_10.4!datastore_index_scan_point_bsatn" />
47+
<WasmImport Include="spacetime_10.4!datastore_delete_by_index_scan_point_bsatn" />
3048

3149
<CustomLinkerArg Include="-DEXPERIMENTAL_WASM_AOT" />
3250
</ItemGroup>

0 commit comments

Comments
 (0)