wasi-assembler 0.0.4

Modern assembler for WASM and WASI (wit-component) - strongly typed, object-oriented, zero-dependency core
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

# WASI Assembler

A comprehensive toolchain for WebAssembly (Wasm) and the WebAssembly System Interface (WASI), supporting both binary `.wasm` and text `.wat` formats.

## 🏛️ Architecture

```mermaid
graph TB
    subgraph "Wasm/WASI Toolchain"
        A[Wasm/WAT Source] --> B[WASI Program Model]
        B --> C[Section Builder]
        C --> D[Instruction Encoder]
        D --> E[Wasm Binary (.wasm)]
        
        subgraph "Section Types"
            F[Type / Import / Function]
            G[Memory / Global / Export]
            H[Code / Data / Custom]
        end
        
        C --> F
        C --> G
        C --> H
    end
```

## 🚀 Features

### Core Capabilities
- **Dual Format Support**: Full support for reading and writing both binary `.wasm` files and text-based `.wat` representations.
- **Component Model**: (🚧) Experimental support for the Wasm Component Model, including `component`, `core module`, and `alias` definitions.
- **Instruction Set**: Comprehensive coverage of standard WebAssembly instructions, including numeric, control flow, and memory operations.

### Advanced Features
- **WASI Integration**: Built-in support for defining WASI-specific imports and exports (e.g., `wasi_snapshot_preview1`).
- **Section Management**: Automatic layout and encoding of all standard Wasm sections, plus support for custom sections (e.g., for debugging).
- **Validation**: Includes a basic validator to ensure generated modules adhere to the WebAssembly specification.

## 💻 Usage

### Assembling WAT to WASM
The following example demonstrates how to parse a WAT string and compile it into a WASM binary.

```rust
use wasi_assembler::WasiAssembler;
use std::fs;

fn main() {
    let wat_source = r#"
        (module
            (func $add (param $lhs i32) (param $rhs i32) (result i32)
                local.get $lhs
                local.get $rhs
                i32.add)
            (export "add" (func $add))
        )
    "#;

    let assembler = WasiAssembler::new();
    let binary = assembler.assemble_from_str(wat_source).expect("Failed to assemble WAT");

    fs::write("add.wasm", binary).unwrap();
    println!("Generated add.wasm");
}
```

## 🛠️ Support Status

| Feature | Support Level | Specification |
| :--- | :---: | :--- |
| Core Wasm (MVP) | ✅ Full | Wasm 1.0 |
| WAT Text Format | ✅ Full | Wasm 1.0 |
| WASI Preview 1 | ✅ Full | Snapshot Preview 1 |
| Component Model | 🚧 Partial | Phase 4 (Draft) |
| SIMD / Atomics | 🚧 Partial | Post-MVP |

*Legend: ✅ Supported, 🚧 In Progress, ❌ Not Supported*

## 🔗 Relations

- **[gaia-types](file:///e:/普遍优化/project-gaia/projects/gaia-types/readme.md)**: Uses `BinaryWriter` and LEB128 encoding utilities for compact Wasm binary generation.
- **[gaia-assembler](file:///e:/普遍优化/project-gaia/projects/gaia-assembler/readme.md)**: Acts as the primary WebAssembly backend for the Gaia project, enabling execution in browsers and WASI runtimes.