Skip to content

Commit cc8e01d

Browse files
avrabeavrabe
committed
docs: add comprehensive AOT compilation documentation
Documents the new Wasmtime ahead-of-time compilation features: - Performance optimization guide with AOT usage patterns - Complete rule reference for wasm_precompile, wasm_run, wasm_test - WasmPrecompiledInfo provider documentation - Optimization levels and cross-platform compilation examples - Integration with existing performance optimization strategies Provides clear guidance on when and how to use AOT compilation for production deployments and performance-critical scenarios.
1 parent 67dfa62 commit cc8e01d

File tree

2 files changed

+223
-0
lines changed

2 files changed

+223
-0
lines changed

‎docs-site/src/content/docs/production/performance.mdx‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,83 @@ Wizer can provide:
3939
2. **Design for pre-initialization** - Structure code to separate initialization from runtime logic
4040
3. **Test thoroughly** - Ensure pre-initialized state is correct
4141

42+
## Ahead-of-Time (AOT) Compilation
43+
44+
WebAssembly components can be precompiled to native machine code using Wasmtime's AOT compilation for dramatically faster startup times.
45+
46+
### Basic AOT Usage
47+
48+
```starlark
49+
load("@rules_wasm_component//wasm:defs.bzl", "wasm_precompile", "wasm_run")
50+
51+
# Precompile component for production
52+
wasm_precompile(
53+
name = "my_component_aot",
54+
component = ":my_component",
55+
optimization_level = "2", # Speed + size optimization
56+
strip_symbols = True, # Reduce size by ~25%
57+
)
58+
59+
# Runtime execution uses AOT automatically
60+
wasm_run(
61+
name = "run_optimized",
62+
component = ":my_component_aot",
63+
)
64+
```
65+
66+
### AOT Performance Benefits
67+
68+
- **Zero JIT compilation** - Skip translation and codegen at runtime
69+
- **7x size reduction** - Optimized builds (2.7MB → 388KB)
70+
- **Faster startup** - Immediate execution of native code
71+
- **Bazel cache friendly** - Share precompiled modules across teams
72+
73+
### Optimization Levels
74+
75+
```starlark
76+
# Development builds with debug info
77+
wasm_precompile(
78+
name = "component_debug",
79+
component = ":my_component",
80+
optimization_level = "0",
81+
debug_info = True,
82+
)
83+
84+
# Production builds optimized for speed
85+
wasm_precompile(
86+
name = "component_speed",
87+
component = ":my_component",
88+
optimization_level = "2",
89+
)
90+
91+
# Production builds optimized for size
92+
wasm_precompile(
93+
name = "component_size",
94+
component = ":my_component",
95+
optimization_level = "s",
96+
strip_symbols = True,
97+
)
98+
```
99+
100+
### Cross-Platform AOT
101+
102+
```starlark
103+
# Compile for specific target architecture
104+
wasm_precompile(
105+
name = "component_x86_64",
106+
component = ":my_component",
107+
target_triple = "x86_64-unknown-linux-gnu",
108+
optimization_level = "2",
109+
)
110+
```
111+
112+
### When to Use AOT
113+
114+
- **Production deployments** - Faster startup is critical
115+
- **Edge computing** - Minimize cold start latency
116+
- **High-frequency execution** - Startup cost amortizes quickly
117+
- **Resource-constrained environments** - Smaller memory footprint
118+
42119
## Build Optimizations
43120

44121
### Compiler Flags

‎docs-site/src/content/docs/reference/rules.mdx‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,9 @@ Complete reference documentation for all Bazel rules provided by rules_wasm_comp
4646
- [Component Tools](#component-tools)
4747
- [wasm_component_new](#wasm_component_new)
4848
- [wasm_component_wizer_library](#wasm_component_wizer_library)
49+
- [wasm_precompile](#wasm_precompile)
50+
- [wasm_run](#wasm_run)
51+
- [wasm_test](#wasm_test)
4952
- [wasm_validate](#wasm_validate)
5053
- [Security & Signing](#security-signing)
5154
- [wasm_keygen](#wasm_keygen)
@@ -57,6 +60,7 @@ Complete reference documentation for all Bazel rules provided by rules_wasm_comp
5760
- [Providers](#providers)
5861
- [WacCompositionInfo](#waccompositioninfo)
5962
- [WasmComponentInfo](#wasmcomponentinfo)
63+
- [WasmPrecompiledInfo](#wasmprecompiledinfo)
6064
- [WitInfo](#witinfo)
6165

6266
## WIT & Interface Rules
@@ -952,6 +956,117 @@ wasm_validate(
952956
)
953957
```
954958

959+
### wasm_precompile
960+
961+
Ahead-of-time (AOT) compile WebAssembly components using Wasmtime for faster startup times and improved performance.
962+
963+
**Load from:**
964+
```python
965+
load("@rules_wasm_component//wasm:defs.bzl", "wasm_precompile")
966+
```
967+
968+
**Attributes:**
969+
970+
| Name | Type | Required | Description |
971+
|------|------|----------|-------------|
972+
| `component` | Label | ❌ | WasmComponent target to precompile |
973+
| `debug_info` | Boolean | ❌ | Include debug information (default: False) |
974+
| `name` | String | ✅ | A unique name for this target |
975+
| `optimization_level` | String | ❌ | Optimization level: "0", "1", "2", "s" (default: "2") |
976+
| `strip_symbols` | Boolean | ❌ | Strip symbol tables to reduce size (default: True) |
977+
| `target_triple` | String | ❌ | Target triple for cross-compilation |
978+
| `wasm_file` | Label | ❌ | Input WebAssembly file to precompile |
979+
980+
**Examples:**
981+
982+
Basic AOT compilation
983+
984+
```python
985+
wasm_precompile(
986+
name = "my_component_aot",
987+
component = ":my_component",
988+
optimization_level = "2",
989+
)
990+
```
991+
992+
Size-optimized build
993+
994+
```python
995+
wasm_precompile(
996+
name = "my_component_size",
997+
component = ":my_component",
998+
optimization_level = "s",
999+
strip_symbols = True,
1000+
)
1001+
```
1002+
1003+
### wasm_run
1004+
1005+
Execute WebAssembly components using Wasmtime runtime. Automatically uses AOT compiled versions when available.
1006+
1007+
**Load from:**
1008+
```python
1009+
load("@rules_wasm_component//wasm:defs.bzl", "wasm_run")
1010+
```
1011+
1012+
**Attributes:**
1013+
1014+
| Name | Type | Required | Description |
1015+
|------|------|----------|-------------|
1016+
| `allow_wasi_filesystem` | Boolean | ❌ | Allow WASI filesystem access (default: True) |
1017+
| `allow_wasi_net` | Boolean | ❌ | Allow WASI network access (default: False) |
1018+
| `component` | Label | ❌ | WebAssembly component to run |
1019+
| `cwasm_file` | Label | ❌ | Direct precompiled WebAssembly file |
1020+
| `module_args` | List of strings | ❌ | Additional arguments to pass to module |
1021+
| `name` | String | ✅ | A unique name for this target |
1022+
| `prefer_aot` | Boolean | ❌ | Use AOT compiled version if available (default: True) |
1023+
| `wasm_file` | Label | ❌ | Direct WebAssembly module file |
1024+
1025+
**Examples:**
1026+
1027+
Run component with AOT preference
1028+
1029+
```python
1030+
wasm_run(
1031+
name = "run_component",
1032+
component = ":my_component_aot",
1033+
allow_wasi_filesystem = True,
1034+
)
1035+
```
1036+
1037+
### wasm_test
1038+
1039+
Test WebAssembly components using Wasmtime runtime. Similar to wasm_run but designed for testing scenarios.
1040+
1041+
**Load from:**
1042+
```python
1043+
load("@rules_wasm_component//wasm:defs.bzl", "wasm_test")
1044+
```
1045+
1046+
**Attributes:**
1047+
1048+
| Name | Type | Required | Description |
1049+
|------|------|----------|-------------|
1050+
| `allow_wasi_filesystem` | Boolean | ❌ | Allow WASI filesystem access (default: True) |
1051+
| `allow_wasi_net` | Boolean | ❌ | Allow WASI network access (default: False) |
1052+
| `component` | Label | ❌ | WebAssembly component to test |
1053+
| `cwasm_file` | Label | ❌ | Direct precompiled WebAssembly file |
1054+
| `module_args` | List of strings | ❌ | Additional arguments to pass to module |
1055+
| `name` | String | ✅ | A unique name for this target |
1056+
| `prefer_aot` | Boolean | ❌ | Use AOT compiled version if available (default: True) |
1057+
| `wasm_file` | Label | ❌ | Direct WebAssembly module file |
1058+
1059+
**Examples:**
1060+
1061+
Test component functionality
1062+
1063+
```python
1064+
wasm_test(
1065+
name = "component_test",
1066+
component = ":my_component",
1067+
)
1068+
```
1069+
9551070
## Security & Signing
9561071

9571072
### wasm_keygen
@@ -1172,6 +1287,37 @@ def _my_rule_impl(ctx):
11721287
# Use component_info...
11731288
```
11741289

1290+
### WasmPrecompiledInfo
1291+
1292+
Provider that contains information about precompiled WebAssembly components (AOT compilation results).
1293+
1294+
**Provider Fields:**
1295+
1296+
| Field | Type | Description |
1297+
|-------|------|-------------|
1298+
| `compatibility_hash` | String | Hash for compatibility checking across builds |
1299+
| `compilation_flags` | List of Strings | List of compilation flags used |
1300+
| `cwasm_file` | File | Precompiled .cwasm file |
1301+
| `optimization_level` | String | Optimization level used (0, 1, 2, s) |
1302+
| `source_wasm` | File | Original WASM file that was precompiled |
1303+
| `target_arch` | String | Target architecture (x86_64, aarch64, etc.) |
1304+
| `wasmtime_version` | String | Version of Wasmtime used for compilation |
1305+
1306+
**Examples:**
1307+
1308+
Access precompiled component information
1309+
1310+
```python
1311+
def _my_rule_impl(ctx):
1312+
if WasmPrecompiledInfo in ctx.attr.component:
1313+
precompiled_info = ctx.attr.component[WasmPrecompiledInfo]
1314+
cwasm_file = precompiled_info.cwasm_file
1315+
optimization = precompiled_info.optimization_level
1316+
# Use precompiled version...
1317+
else:
1318+
# Fallback to regular component...
1319+
```
1320+
11751321
### WitInfo
11761322

11771323
Provider that contains information about WIT interfaces and their dependencies.

0 commit comments

Comments
 (0)