Skip to content

Commit 966c617

Browse files
avrabeavrabe
committed
feat: enhance AOT compilation with multi-architecture support and 87% size reduction
Add comprehensive multi-target AOT compilation capabilities and production optimizations that achieve 87% size reduction through debug info control. Major enhancements: - Add wasm_precompile_multi rule for parallel cross-platform compilation - Implement debug info control (default: exclude DWARF for 87% size reduction) - Add cross-compilation support for x86_64, aarch64, and Pulley targets - Enhanced optimization levels and symbol stripping capabilities Performance improvements: - Production builds: 2.8MB → 343KB (87% reduction) by excluding debug info - Cross-platform AOT compilation without QEMU emulation - Parallel multi-architecture builds for efficient deployment - Improved Bazel caching and deterministic builds Updated examples and documentation: - examples/aot_example: Multi-arch compilation demonstrations - examples/aot_test: Cross-compilation test coverage - docs: Updated performance metrics and best practices - wkg: Improved package name handling and file operations The enhanced AOT system enables efficient WebAssembly deployment across multiple architectures with significant performance and size improvements.
1 parent 3f45df4 commit 966c617

File tree

8 files changed

+713
-123
lines changed

8 files changed

+713
-123
lines changed

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

Lines changed: 75 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -49,12 +49,11 @@ WebAssembly components can be precompiled to native machine code using Wasmtime'
4949
```starlark
5050
load("@rules_wasm_component//wasm:defs.bzl", "wasm_precompile", "wasm_run")
5151

52-
# Precompile component for production
52+
# Precompile component for production (default: no debug info)
5353
wasm_precompile(
5454
name = "my_component_aot",
5555
component = ":my_component",
5656
optimization_level = "2", # Speed + size optimization
57-
strip_symbols = True, # Reduce size by ~25%
5857
)
5958

6059
# Runtime execution uses AOT automatically
@@ -67,34 +66,34 @@ wasm_run(
6766
### AOT Performance Benefits
6867

6968
- **Zero JIT compilation** - Skip translation and codegen at runtime
70-
- **7x size reduction** - Optimized builds (2.7MB → 388KB)
69+
- **87% size reduction** - Production builds exclude debug info (2.8MB → 343KB)
7170
- **Faster startup** - Immediate execution of native code
71+
- **Cross-platform compilation** - Build for any architecture without QEMU
7272
- **Bazel cache friendly** - Share precompiled modules across teams
7373

74-
### Optimization Levels
74+
### Debug Info vs Production Builds
7575

7676
```starlark
77-
# Development builds with debug info
77+
# Development builds with debug info (~8x larger but debuggable)
7878
wasm_precompile(
7979
name = "component_debug",
8080
component = ":my_component",
8181
optimization_level = "0",
82-
debug_info = True,
82+
debug_info = True, # Include DWARF debug information
8383
)
8484

85-
# Production builds optimized for speed
85+
# Production builds (default: no debug info, 87% smaller)
8686
wasm_precompile(
87-
name = "component_speed",
87+
name = "component_production",
8888
component = ":my_component",
89-
optimization_level = "2",
89+
optimization_level = "2", # debug_info = False by default
9090
)
9191

9292
# Production builds optimized for size
9393
wasm_precompile(
9494
name = "component_size",
9595
component = ":my_component",
96-
optimization_level = "s",
97-
strip_symbols = True,
96+
optimization_level = "s", # Size-optimized + no debug info
9897
)
9998
```
10099

@@ -117,6 +116,71 @@ wasm_precompile(
117116
- **High-frequency execution** - Startup cost amortizes quickly
118117
- **Resource-constrained environments** - Smaller memory footprint
119118

119+
## AOT Embedding for Multi-Architecture Deployment
120+
121+
**Embed multiple AOT artifacts as custom sections** within a single WebAssembly component for universal deployment. This enables signing and distributing one component that contains optimized native code for multiple architectures.
122+
123+
### Basic AOT Embedding
124+
125+
```starlark
126+
load("@rules_wasm_component//wasm:defs.bzl",
127+
"wasm_precompile", "wasm_embed_aot", "wasm_extract_aot")
128+
129+
# Create AOT artifacts for different architectures
130+
wasm_precompile(
131+
name = "component_x64",
132+
component = ":my_component",
133+
target_triple = "x86_64-unknown-linux-gnu",
134+
optimization_level = "2",
135+
)
136+
137+
wasm_precompile(
138+
name = "component_arm64",
139+
component = ":my_component",
140+
target_triple = "aarch64-unknown-linux-gnu",
141+
optimization_level = "2",
142+
)
143+
144+
wasm_precompile(
145+
name = "component_portable",
146+
component = ":my_component",
147+
target_triple = "pulley64", # Architecture-independent
148+
optimization_level = "2",
149+
)
150+
151+
# Embed all AOT artifacts into single component
152+
wasm_embed_aot(
153+
name = "universal_component",
154+
component = ":my_component",
155+
aot_artifacts = {
156+
"linux_x64": ":component_x64",
157+
"linux_arm64": ":component_arm64",
158+
"portable": ":component_portable",
159+
},
160+
)
161+
```
162+
163+
### Runtime Extraction
164+
165+
```starlark
166+
# Extract specific architecture at runtime
167+
wasm_extract_aot(
168+
name = "extracted_x64",
169+
component = ":universal_component",
170+
target_name = "linux_x64",
171+
)
172+
```
173+
174+
### AOT Embedding Benefits
175+
176+
- **Single artifact distribution** - One component works everywhere
177+
- **Signature compatibility** - Maintains WebAssembly format for signing
178+
- **Architecture-specific optimization** - Each platform gets optimal native code
179+
- **Fallback support** - Include portable bytecode for unknown architectures
180+
- **87% size reduction** - Production builds exclude debug symbols
181+
182+
> **📋 Rule Reference:** For complete details on AOT embedding rules, see [`wasm_embed_aot`](/reference/rules/#wasm_embed_aot) and [`wasm_extract_aot`](/reference/rules/#wasm_extract_aot).
183+
120184
## Build Optimizations
121185

122186
### Compiler Flags

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

Lines changed: 129 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ 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_embed_aot](#wasm_embed_aot)
50+
- [wasm_extract_aot](#wasm_extract_aot)
4951
- [wasm_precompile](#wasm_precompile)
5052
- [wasm_run](#wasm_run)
5153
- [wasm_test](#wasm_test)
@@ -987,6 +989,116 @@ wasm_validate(
987989
)
988990
```
989991

992+
### wasm_embed_aot
993+
994+
Embed AOT-compiled WebAssembly artifacts as custom sections in a component. This rule takes a WebAssembly component and embeds multiple AOT-compiled versions (.cwasm files) as custom sections, enabling universal deployment with architecture-specific optimization.
995+
996+
**Load from:**
997+
998+
```python
999+
load("@rules_wasm_component//wasm:defs.bzl", "wasm_embed_aot")
1000+
```
1001+
1002+
**Attributes:**
1003+
1004+
| Name | Type | Required | Description |
1005+
| --------------- | ----------------------- | -------- | ----------------------------------------------------- |
1006+
| `aot_artifacts` | String-keyed label dict | ✅ | Dictionary mapping target names to precompiled AOT artifacts |
1007+
| `component` | Label | ✅ | Base WebAssembly component to embed AOT artifacts into |
1008+
| `name` | String | ✅ | A unique name for this target |
1009+
1010+
**Examples:**
1011+
1012+
Multi-architecture AOT embedding
1013+
1014+
```python
1015+
wasm_embed_aot(
1016+
name = "universal_component",
1017+
component = ":my_component",
1018+
aot_artifacts = {
1019+
"linux_x64": ":component_x64_aot",
1020+
"linux_arm64": ":component_arm64_aot",
1021+
"portable": ":component_portable_aot",
1022+
},
1023+
)
1024+
```
1025+
1026+
Production deployment with embedded optimizations
1027+
1028+
```python
1029+
# Create AOT artifacts for different platforms
1030+
wasm_precompile(
1031+
name = "production_x64",
1032+
component = ":service",
1033+
target_triple = "x86_64-unknown-linux-gnu",
1034+
optimization_level = "2",
1035+
)
1036+
1037+
wasm_precompile(
1038+
name = "production_arm64",
1039+
component = ":service",
1040+
target_triple = "aarch64-unknown-linux-gnu",
1041+
optimization_level = "2",
1042+
)
1043+
1044+
# Embed for universal deployment
1045+
wasm_embed_aot(
1046+
name = "production_service",
1047+
component = ":service",
1048+
aot_artifacts = {
1049+
"prod_x64": ":production_x64",
1050+
"prod_arm64": ":production_arm64",
1051+
},
1052+
)
1053+
```
1054+
1055+
### wasm_extract_aot
1056+
1057+
Extract an AOT-compiled artifact from a WebAssembly component. This rule extracts a specific AOT artifact that was previously embedded as a custom section, allowing runtime code to access the appropriate compiled version for the current architecture.
1058+
1059+
**Load from:**
1060+
1061+
```python
1062+
load("@rules_wasm_component//wasm:defs.bzl", "wasm_extract_aot")
1063+
```
1064+
1065+
**Attributes:**
1066+
1067+
| Name | Type | Required | Description |
1068+
| ------------- | ------ | -------- | ----------------------------------------------------- |
1069+
| `component` | Label | ✅ | WebAssembly component with embedded AOT artifacts |
1070+
| `name` | String | ✅ | A unique name for this target |
1071+
| `target_name` | String | ✅ | Target architecture name to extract (e.g., "linux_x64") |
1072+
1073+
**Examples:**
1074+
1075+
Extract specific architecture
1076+
1077+
```python
1078+
wasm_extract_aot(
1079+
name = "extracted_x64_optimized",
1080+
component = ":universal_component",
1081+
target_name = "linux_x64",
1082+
)
1083+
```
1084+
1085+
Runtime architecture selection
1086+
1087+
```python
1088+
# Extract different architectures as needed
1089+
wasm_extract_aot(
1090+
name = "runtime_x64",
1091+
component = ":production_service",
1092+
target_name = "prod_x64",
1093+
)
1094+
1095+
wasm_extract_aot(
1096+
name = "runtime_arm64",
1097+
component = ":production_service",
1098+
target_name = "prod_arm64",
1099+
)
1100+
```
1101+
9901102
### wasm_precompile
9911103

9921104
Ahead-of-time (AOT) compile WebAssembly components using Wasmtime for faster startup times and improved performance.
@@ -1002,16 +1114,15 @@ load("@rules_wasm_component//wasm:defs.bzl", "wasm_precompile")
10021114
| Name | Type | Required | Description |
10031115
| -------------------- | ------- | -------- | ----------------------------------------------------- |
10041116
| `component` | Label | ❌ | WasmComponent target to precompile |
1005-
| `debug_info` | Boolean | ❌ | Include debug information (default: False) |
1117+
| `debug_info` | Boolean | ❌ | Include DWARF debug information (increases size ~8x) |
10061118
| `name` | String | ✅ | A unique name for this target |
10071119
| `optimization_level` | String | ❌ | Optimization level: "0", "1", "2", "s" (default: "2") |
1008-
| `strip_symbols` | Boolean | ❌ | Strip symbol tables to reduce size (default: True) |
10091120
| `target_triple` | String | ❌ | Target triple for cross-compilation |
10101121
| `wasm_file` | Label | ❌ | Input WebAssembly file to precompile |
10111122

10121123
**Examples:**
10131124

1014-
Basic AOT compilation
1125+
Production build (default: no debug info, 87% smaller)
10151126

10161127
```python
10171128
wasm_precompile(
@@ -1021,14 +1132,25 @@ wasm_precompile(
10211132
)
10221133
```
10231134

1024-
Size-optimized build
1135+
Debug build with DWARF debug information
10251136

10261137
```python
10271138
wasm_precompile(
1028-
name = "my_component_size",
1139+
name = "my_component_debug",
10291140
component = ":my_component",
1030-
optimization_level = "s",
1031-
strip_symbols = True,
1141+
optimization_level = "0",
1142+
debug_info = True,
1143+
)
1144+
```
1145+
1146+
Cross-compilation for specific architecture
1147+
1148+
```python
1149+
wasm_precompile(
1150+
name = "my_component_x64",
1151+
component = ":my_component",
1152+
target_triple = "x86_64-unknown-linux-gnu",
1153+
optimization_level = "2",
10321154
)
10331155
```
10341156

0 commit comments

Comments
 (0)