Skip to content

Commit fafefce

Browse files
GordonSmithGordonSmith
committed
feat: add code generation
Wrap wit-bindgen in wasm Drop jco and replace with wit-parser Signed off by: Gordon Smith <GordonJSmith@gmail.com>
1 parent 55f1b46 commit fafefce

29 files changed

+3375
-1712
lines changed

‎.github/instructions/wit-bindgen.instructions.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
---
2+
applyTo: "**"
3+
---
4+
5+
# GitHub Copilot Instructions for wit-bindgen Projects
6+
7+
> **Note:** These instructions are in addition to the [general project instructions](.github/instructions/general.instructions.md) and [VS Code extension instructions](.github/instructions/vscode-extension.instructions.md). If there is any overlap, follow the general instructions and refer to this file for wit-bindgen–specific requirements.
8+
9+
## About wit-bindgen
10+
11+
`wit-bindgen` is a suite of bindings generators for languages compiled to WebAssembly that use the [Component Model](https://github.com/WebAssembly/component-model). It generates language-specific bindings from [WIT (WebAssembly Interface Types)](https://component-model.bytecodealliance.org/design/wit.html) files.
12+
13+
## Project Structure Requirements
14+
15+
- Store WIT files in a `wit/` directory adjacent to your main project file
16+
- Use the `.wit` file extension for WIT interface definitions
17+
- Organize WIT files by package and world definitions
18+
- Include component type objects (`.o` files) in builds when required
19+
20+
## WIT File Guidelines
21+
22+
### Basic Structure
23+
```wit
24+
package example:host;
25+
26+
world host {
27+
import print: func(msg: string);
28+
export run: func();
29+
}
30+
```
31+
32+
### Interface Definitions
33+
```wit
34+
package example:my-game;
35+
36+
interface my-plugin-api {
37+
record coord {
38+
x: u32,
39+
y: u32,
40+
}
41+
42+
get-position: func() -> coord;
43+
set-position: func(pos: coord);
44+
}
45+
46+
world my-game {
47+
import print: func(msg: string);
48+
import my-plugin-api;
49+
export run: func();
50+
}
51+
```
52+
53+
### WIT Best Practices
54+
- Use kebab-case for function and interface names
55+
- Use meaningful package names following the format `namespace:package`
56+
- Group related functionality into interfaces
57+
- Define clear import/export boundaries in worlds
58+
- Use appropriate WIT types (u32, string, list, record, etc.)
59+
60+
## Language-Specific Guidelines
61+
62+
### Rust Projects
63+
- Use `wit_bindgen::generate!()` macro with world specification
64+
- Implement the generated `Guest` trait for your component
65+
- Use `export!()` macro to define component exports
66+
- Build with `cargo build --target wasm32-wasip2`
67+
- Add `crate-type = ["cdylib"]` to `Cargo.toml` for dynamic libraries
68+
69+
### C/C++ Projects
70+
- Generate bindings with `wit-bindgen c ./wit`
71+
- Include generated header files in your source
72+
- Use WASI SDK for compilation to WebAssembly
73+
- Link component type objects during build
74+
- Compile with `-mexec-model=reactor` for non-main components
75+
76+
### C# Projects
77+
- Generate bindings with `wit-bindgen csharp -w command -r native-aot --generate-stub wit/`
78+
- Configure project for `wasi-wasm` runtime identifier
79+
- Use native AOT compilation for WebAssembly targets
80+
- Enable unsafe blocks when required
81+
82+
## Build Process
83+
84+
### Component Creation Workflow
85+
1. **Generate Bindings**: Use `wit-bindgen` to create language-specific bindings
86+
2. **Compile to Core WebAssembly**: Use native toolchain to produce `.wasm` module
87+
3. **Transform to Component**: Use `wasm-tools component new` to create component
88+
89+
### WASI Adapter Usage
90+
For projects using `wasi_snapshot_preview1`, use appropriate adapters:
91+
- `wasi_snapshot_preview1.command.wasm` - CLI applications
92+
- `wasi_snapshot_preview1.reactor.wasm` - Event-driven applications
93+
- `wasi_snapshot_preview1.proxy.wasm` - Proxy applications
94+
95+
Example transformation:
96+
```bash
97+
wasm-tools component new ./my-core.wasm \
98+
--adapt wasi_snapshot_preview1=wasi_snapshot_preview1.command.wasm \
99+
-o my-component.wasm
100+
```
101+
102+
## Testing and Validation
103+
104+
### Component Inspection
105+
- Use `wasm-tools component wit ./component.wasm` to inspect WIT interface
106+
- Validate component structure with `wasm-tools validate`
107+
- Test components in compatible runtimes (Wasmtime, jco, etc.)
108+
109+
### Debug Support
110+
- Use `WIT_BINDGEN_DEBUG=1` environment variable for debugging generated bindings
111+
- Use `cargo expand` to examine generated Rust code
112+
- Validate WIT syntax with `wasm-tools component wit-text`
113+
114+
## Integration with Host Runtimes
115+
116+
### Supported Runtimes
117+
- **Rust**: `wasmtime` crate with `bindgen!` macro
118+
- **JavaScript**: `jco` for web and Node.js execution
119+
- **Python**: `wasmtime-py` with bindgen support
120+
- **Ruby**: `wasmtime-rb` for component execution
121+
122+
### Component Composition
123+
- Use `wasm-tools compose` for linking multiple components
124+
- Ensure compatible WIT interfaces between components
125+
- Validate composed components before deployment
126+
127+
## Development Workflow
128+
129+
### CLI Installation
130+
```bash
131+
cargo install wit-bindgen-cli
132+
```
133+
134+
### Code Generation
135+
```bash
136+
# Generate language-specific bindings
137+
wit-bindgen <language> ./wit
138+
139+
# Examples:
140+
wit-bindgen rust ./wit
141+
wit-bindgen c ./wit
142+
wit-bindgen csharp -w command ./wit
143+
```
144+
145+
### Build and Test
146+
```bash
147+
# Build component (language-specific)
148+
cargo build --target wasm32-wasip2 # Rust
149+
clang -o core.wasm ... # C/C++
150+
151+
# Create component
152+
wasm-tools component new core.wasm -o component.wasm
153+
154+
# Validate and inspect
155+
wasm-tools validate component.wasm
156+
wasm-tools component wit component.wasm
157+
```
158+
159+
## Error Handling and Debugging
160+
161+
- Check for WIT syntax errors before code generation
162+
- Validate that all imports/exports are properly implemented
163+
- Ensure component type compatibility between host and guest
164+
- Use appropriate error handling patterns for each target language
165+
- Test components in isolation before integration
166+
167+
## Documentation Requirements
168+
169+
- Document WIT interfaces with clear comments
170+
- Provide usage examples for generated bindings
171+
- Document component capabilities and limitations
172+
- Include build instructions for target platforms
173+
- Maintain changelog for WIT interface changes
174+
175+
## Version Management
176+
177+
- Track `wit-bindgen` CLI version in project documentation
178+
- Pin specific versions for reproducible builds
179+
- Test compatibility when upgrading wit-bindgen versions
180+
- Document breaking changes in WIT interface evolution
181+
182+
## Resources
183+
184+
- [WIT Documentation](https://component-model.bytecodealliance.org/design/wit.html)
185+
- [Component Model Specification](https://github.com/WebAssembly/component-model)
186+
- [wit-bindgen Repository](https://github.com/bytecodealliance/wit-bindgen)
187+
- [wasm-tools Documentation](https://github.com/bytecodealliance/wasm-tools)
188+
- [Bytecode Alliance Zulip](https://bytecodealliance.zulipchat.com/#narrow/stream/327223-wit-bindgen)
189+
190+
---
191+
For wit-bindgen specific questions, reach out on [Zulip](https://bytecodealliance.zulipchat.com/#narrow/stream/327223-wit-bindgen) or check the [wit-bindgen repository](https://github.com/bytecodealliance/wit-bindgen).

0 commit comments

Comments
 (0)