Debian Codegraph @

site/content/languages/zig.md

raw
1 +++
2 title = "Zig"
3 +++
4
5 ## Introduction
6
7 Beginning with 0.4.0 [Zig][1] can generate `%.wasm` files instead of
8 architecture-specific binaries through three targets:
9
10 * `wasm32-emscripten`: mostly for browser (JavaScript) use.
11 * `wasm32-freestanding`: for standalone use in or outside the browser.
12 * `wasm32-wasi`: for use outside the browser.
13
14 This document is maintained by wazero, which is a WebAssembly runtime that
15 embeds in Go applications. Hence, our notes focus on targets used outside the
16 browser, tested by wazero: `wasm32-freestanding` and `wasm32-wasi`.
17
18 ## Overview
19
20 When Zig compiles a `%.zig` file with a `wasm32-*` target, the output `%.wasm`
21 depends on a subset of features in the [WebAssembly 2.0
22 Core specification]({{< ref "/specs#core" >}}) and [WASI]({{< ref "/specs#wasi" >}}) host
23 functions.
24
25 Unlike some compilers, Zig also supports importing custom host functions and
26 exporting functions back to the host.
27
28 Here's a basic example of source in Zig:
29
30 ```zig
31 export fn add(a: i32, b: i32) i32 {
32 return a + b;
33 }
34 ```
35
36 The following is the minimal command to build a Wasm file.
37
38 ```bash
39 zig build-lib -dynamic -target wasm32-freestanding main.zig
40 ```
41
42 The resulting Wasm `export`s the `add` function so that the embedding host can
43 call it, regardless of if the host is written in Zig or not.
44
45 Notice we are using `zig build-lib -dynamic`: this
46 compiles the source as a library, i.e. without a `main` function.
47
48 ## Disclaimer
49
50 This document includes notes contributed by the wazero community for Zig 0.10.1.
51 While wazero includes Zig examples, and maintainers contribute to Zig, this
52 isn't a Zig official document. For more help, consider the [WebAssembly Documentation][4]
53 or joining the [#programming-discussion channel on
54 Zig's Discord][5].
55
56 Meanwhile, please help us [maintain][6] this document and [star our GitHub
57 repository][7], if it is helpful. Together, we can make WebAssembly easier on
58 the next person.
59
60 ## Constraints
61
62 Please read our overview of WebAssembly and
63 [constraints]({{< ref "_index.md#constraints" >}}). In short, expect
64 limitations in both language features and library choices when developing your
65 software.
66
67 ## Memory
68
69 The Zig language performs no memory management on behalf of the programmer.
70 However, Zig has no default allocator. Instead, functions which need to allocate
71 accept an `Allocator` parameter.
72
73 ### Host Allocations
74
75 Sometimes a host function needs to allocate memory directly. For example, to write JSON
76 of a given length before invoking an exported function to parse it.
77
78 ```zig
79 pub export fn configure(ptr: [*]const u8, size: u32) void {
80 _configure(message[0..size]) catch |err| @panic(switch (err) {
81 error.OutOfMemory => "out of memory",
82 });
83 }
84 ```
85
86 The general flow is that the host allocates memory by calling an allocation
87 function with the size needed. Then, it writes data, in this case JSON, to the
88 memory offset (`ptr`). At that point, it can call a host function, ex
89 `configure`, passing the `ptr` and `size` allocated. The guest Wasm (compiled
90 from Zig) will be able to read the data. To ensure no memory leaks, the host
91 calls a free function, with the same `ptr`, afterwards and unconditionally.
92
93 Note: wazero includes an [example project][9] that shows this.
94
95 The [zig example][9] does a few things of interest:
96 * Uses `@ptrToInt` to change a Zig pointer to a numeric type
97 * Uses `[*]u8` as an argument to take a pointer and slices it to build back a
98 string
99 * It also shows how to import a host function using the `extern` directive
100
101 To allow the host to allocate memory, you need to define your own `malloc` and
102 `free` functions:
103 ```webassembly
104 (func (export "malloc") (param $size i32) (result (;$ptr;) i32))
105 (func (export "free") (param $ptr i32) (param $size i32))
106 ```
107
108 Because Zig easily allows end-users to [plug their own allocators][12], it relatively easy to
109 export custom `malloc`/`free` pairs to the host.
110
111 For instance, the following code exports `malloc`, `free` from Zig's `page_allocator`:
112
113 ```zig
114 const allocator = std.heap.page_allocator;
115
116 pub export fn malloc(length: usize) ?[*]u8 {
117 const buff = allocator.alloc(u8, length) catch return null;
118 return buff.ptr;
119 }
120
121 pub export fn free(buf: [*]u8, length: usize) void {
122 allocator.free(buf[0..length]);
123 }
124 ```
125
126 ## System Calls
127
128 Please read our overview of WebAssembly and
129 [System Calls]({{< ref "_index.md#system-calls" >}}). In short, WebAssembly is
130 a stack-based virtual machine specification, so operates at a lower level than
131 an operating system.
132
133 For functionality the operating system would otherwise provide, you must use
134 the `wasm32-wasi` target. This imports host functions in
135 [WASI]({{< ref "/specs#wasi" >}}).
136
137 Zig's standard library support for WASI is under active development.
138 In general, you should favor use of the standard library when compiling against
139 wasm32-wasi target (e.g. `std.io`).
140
141 Note: wazero includes an [example WASI project][10] including [source code][11]
142 that implements `cat` without any WebAssembly-specific code.
143
144 ## Concurrency
145
146 Please read our overview of WebAssembly and
147 [concurrency]({{< ref "_index.md#concurrency" >}}). In short, the current
148 WebAssembly specification does not support parallel processing.
149
150 ## Optimizations
151
152 Below are some commonly used configurations that allow optimizing for size or
153 performance vs defaults. Note that sometimes one sacrifices the other.
154
155 ### Binary size
156
157 Those with `%.wasm` binary size constraints can change their source,
158 e.g. picking a [different allocator][9b] or set `zig` flags to reduce it.
159
160 [`zig` flags][13]:
161 Zig provides several flags to control binary size, speed of execution,
162 safety checks. For instance you may use
163 * `-ODebug`: Fast build, enabled safety checks, slower runtime performance,
164 larger binary size
165 * `-OReleaseSafe`: Medium runtime performance, enabled safety checks,
166 slower compilation speed, larger binary size
167 * `-OReleaseSmall`: Medium runtime performance, disabled safety checks,
168 slower compilation speed, smaller binary size
169
170 ### Performance
171
172 Those with runtime performance constraints can change their source or set
173 `zig` flags to improve it.
174
175 [`zig` flags][13]:
176 * `-OReleaseFast`: Enable additional optimizations, possibly at the cost of
177 increased binary size.
178
179 ## Frequently Asked Questions
180
181 ### Why is my `%.wasm` binary so big?
182 Zig defaults can be overridden for those who can sacrifice features or
183 performance for a [smaller binary](#binary-size). After that, tuning your
184 source code may reduce binary size further.
185
186 [1]: https://ziglang.org/download/0.4.0/release-notes.html
187 [2]: https://ziglang.org/documentation/0.10.1/#WASI
188 [4]: https://ziglang.org/documentation/0.10.1/#WebAssembly
189 [5]: https://discord.gg/gxsFFjE
190 [6]: https://github.com/tetratelabs/wazero/tree/main/site/content/languages/zig.md
191 [7]: https://github.com/tetratelabs/wazero/stargazers
192 [9]: https://github.com/tetratelabs/wazero/tree/main/examples/allocation/zig
193 [9b]: https://ziglang.org/documentation/0.10.1/#Memory
194 [10]: https://github.com/tetratelabs/wazero/tree/main/imports/wasi_snapshot_preview1/example/testdata/zig
195 [11]: https://github.com/tetratelabs/wazero/blob/main/imports/wasi_snapshot_preview1/example/testdata/zig/cat.zig
196 [13]: https://ziglang.org/documentation/0.10.1/#Build-Mode