1![ZIG](https://ziglang.org/img/zig-logo-dynamic.svg)
2
3A general-purpose programming language and toolchain for maintaining
4**robust**, **optimal**, and **reusable** software.
5
6https://ziglang.org/
7
8## Documentation
9
10If you are looking at this README file in a source tree, please refer to the
11**Release Notes**, **Language Reference**, or **Standard Library
12Documentation** corresponding to the version of Zig that you are using by
13following the appropriate link on the
14[download page](https://ziglang.org/download).
15
16Otherwise, you're looking at a release of Zig, so you can find the language
17reference at `doc/langref.html`, and the standard library documentation by
18running `zig std`, which will open a browser tab.
19
20## Installation
21
22 * [download a pre-built binary](https://ziglang.org/download/)
23 * [install from a package manager](https://ziglang.org/learn/getting-started/#managers)
24 * [bootstrap zig for any target](https://codeberg.org/ziglang/zig-bootstrap)
25
26A Zig installation is composed of two things:
27
281. The Zig executable
292. The lib/ directory
30
31At runtime, the executable searches up the file system for the lib/ directory,
32relative to itself:
33
34* lib/
35* lib/zig/
36* ../lib/
37* ../lib/zig/
38* (and so on)
39
40In other words, you can **unpack a release of Zig anywhere**, and then begin
41using it immediately. There is no need to install it globally, although this
42mechanism supports that use case too (i.e. `/usr/bin/zig` and `/usr/lib/zig/`).
43
44## Building from Source
45
46Ensure you have the required dependencies:
47
48 * CMake >= 3.15
49 * System C/C++ Toolchain
50 * LLVM, Clang, LLD development libraries, version 22.x, compiled with the
51 same system C/C++ toolchain.
52 - If the system package manager lacks these libraries, or has them misconfigured,
53 see below for how to build them from source.
54
55Then it is the standard CMake build process:
56
57```sh
58mkdir build
59cd build
60cmake ..
61make install
62```
63
64Use `CMAKE_PREFIX_PATH` if needed to help CMake find LLVM.
65
66This produces `stage3/bin/zig` which is the Zig compiler built by itself.
67
68## Building from Source without LLVM
69
70In this case, the only system dependency is a C compiler.
71
72```sh
73cc -o bootstrap bootstrap.c
74./bootstrap
75```
76
77This produces a `zig2` executable in the current working directory. This is a
78"stage2" build of the compiler,
79[without LLVM extensions](https://github.com/ziglang/zig/issues/16270), and is
80therefore lacking these features:
81- Release mode optimizations
82- [Some ELF linking features](https://github.com/ziglang/zig/issues/17749)
83- [Some COFF/PE linking features](https://github.com/ziglang/zig/issues/17751)
84- [Some WebAssembly linking features](https://github.com/ziglang/zig/issues/17750)
85- [Ability to create static archives from object files](https://github.com/ziglang/zig/issues/9828)
86- [Ability to compile assembly files](https://github.com/ziglang/zig/issues/21169)
87- Ability to compile C, C++, Objective-C, and Objective-C++ files
88
89Even when built this way, Zig provides an LLVM backend that produces bitcode
90files, which may be optimized and compiled into object files via separately
91installed Clang. Similarly, Zig provides a C backend that produces C source
92code, which may be optimized and compiled into object files via a separately
93installed C compiler toolchain.
94
95From here you can tinker with `zig2` or you can proceed to installation using
96the build system as usual:
97
98```sh
99./zig2 build
100```
101
102However, due to the above listed caveats, it is recommended to not proceed to
103this step until this issue is resolved:
104
105[completely eliminate dependency on LLVM library API calls](https://github.com/ziglang/zig/issues/25492)
106
107## Building from Source Using Prebuilt Zig
108
109Dependencies:
110
111 * A recent prior build of Zig. The exact version required depends on how
112 recently breaking changes occurred. If the language or std lib changed too
113 much since this version, then this method of building from source will fail.
114 * LLVM, Clang, and LLD libraries built using Zig.
115
116The easiest way to obtain both of these artifacts is to use
117[zig-bootstrap](https://codeberg.org/ziglang/zig-bootstrap), which creates the
118directory `out/zig-$target-$cpu` and `out/$target-$cpu`, to be used as
119`$ZIG_PREFIX` and `$LLVM_PREFIX`, respectively, in the following command:
120
121```sh
122"$ZIG_PREFIX/zig" build \
123 -p stage3 \
124 --search-prefix "$LLVM_PREFIX" \
125 --zig-lib-dir "lib" \
126 -Dstatic-llvm
127```
128
129Where `$LLVM_PREFIX` is the path that contains, for example,
130`include/llvm/Pass.h` and `lib/libLLVMCore.a`.
131
132This produces `stage3/bin/zig`. See `zig build -h` to learn about the options
133that can be passed such as `-Drelease`.
134
135## Building from Source on Windows
136
137### Option 1: Use the Windows Zig Compiler Dev Kit
138
139This one has the benefit that LLVM, LLD, and Clang are built in Release mode,
140while your Zig build has the option to be a Debug build. It also works
141completely independently from MSVC so you don't need it to be installed.
142
143Determine the URL by
144[looking at the CI script](https://codeberg.org/ziglang/zig/src/branch/master/ci/x86_64-windows-debug.ps1#L1-L4).
145It will look something like this (replace `$VERSION` with the one you see by
146following the above link):
147
148```
149https://ziglang.org/deps/zig+llvm+lld+clang-x86_64-windows-gnu-$VERSION.zip
150```
151
152This zip file contains:
153
154 * An older Zig installation.
155 * LLVM, LLD, and Clang libraries (.lib and .h files), version 16.0.1, built in Release mode.
156 * zlib (.lib and .h files), v1.2.13, built in Release mode
157 * zstd (.lib and .h files), v1.5.2, built in Release mode
158
159#### Option 1a: CMake + [Ninja](https://ninja-build.org/)
160
161Unzip the dev kit and then in cmd.exe in your Zig source checkout:
162
163```bat
164mkdir build
165cd build
166set DEVKIT=$DEVKIT
167```
168
169Replace `$DEVKIT` with the path to the folder that you unzipped after
170downloading it from the link above. Make sure to use forward slashes (`/`) for
171all path separators (otherwise CMake will try to interpret backslashes as
172escapes and fail).
173
174Then run:
175
176```bat
177cmake .. -GNinja -DCMAKE_PREFIX_PATH="%DEVKIT%" -DCMAKE_C_COMPILER="%DEVKIT%/bin/zig.exe;cc" -DCMAKE_CXX_COMPILER="%DEVKIT%/bin/zig.exe;c++" -DCMAKE_AR="%DEVKIT%/bin/zig.exe" -DZIG_AR_WORKAROUND=ON -DZIG_STATIC=ON -DZIG_USE_LLVM_CONFIG=OFF
178```
179
180 * Append `-DCMAKE_BUILD_TYPE=Release` for a Release build.
181 * Append `-DZIG_NO_LIB=ON` to avoid having multiple copies of the lib/ folder.
182
183Finally, run:
184
185```bat
186ninja install
187```
188
189You now have the `zig.exe` binary at `stage3\bin\zig.exe`.
190
191#### Option 1b: zig build
192
193Unzip the dev kit and then in cmd.exe in your Zig source checkout:
194
195```bat
196$DEVKIT\bin\zig.exe build -p stage3 --search-prefix $DEVKIT --zig-lib-dir lib -Dstatic-llvm -Duse-zig-libcxx -Dtarget=x86_64-windows-gnu
197```
198
199Replace `$DEVKIT` with the path to the folder that you unzipped after
200downloading it from the link above.
201
202Append `-Doptimize=ReleaseSafe` for a Release build.
203
204**If you get an error building at this step**, it is most likely that the Zig
205installation inside the dev kit is too old, and the dev kit needs to be
206updated. In this case one more step is required:
207
208 1. [Download the latest master branch zip file](https://ziglang.org/download/#release-master).
209 2. Unzip, and try the above command again, replacing the path to zig.exe with
210 the path to the zig.exe you just extracted, and also replace the lib\zig
211 folder with the new contents.
212
213You now have the `zig.exe` binary at `stage3\bin\zig.exe`.
214
215### Option 2: Using CMake and Microsoft Visual Studio
216
217This one has the benefit that changes to the language or build system won't
218break your dev kit. This option can be used to upgrade a dev kit.
219
220First, build LLVM, LLD, and Clang from source using CMake and Microsoft Visual
221Studio (see below for detailed instructions).
222
223Install [Build Tools for Visual Studio
2242019](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019).
225Be sure to select "Desktop development with C++" when prompted.
226 * You must additionally check the optional component labeled **C++ ATL for
227 v142 build tools**.
228
229Install [CMake](http://cmake.org).
230
231Use [git](https://git-scm.com/) to clone the zig repository to a path with no spaces, e.g. `C:\Users\Andy\zig`.
232
233Using the start menu, run **x64 Native Tools Command Prompt for VS 2019** and execute these commands, replacing `C:\Users\Andy` with the correct value.
234
235```bat
236mkdir C:\Users\Andy\zig\build-release
237cd C:\Users\Andy\zig\build-release
238"c:\Program Files\CMake\bin\cmake.exe" .. -Thost=x64 -G "Visual Studio 16 2019" -A x64 -DCMAKE_PREFIX_PATH=C:\Users\Andy\llvm+clang+lld-20.0.0-x86_64-windows-msvc-release-mt -DCMAKE_BUILD_TYPE=Release
239msbuild -p:Configuration=Release INSTALL.vcxproj
240```
241
242You now have the `zig.exe` binary at `bin\zig.exe` and you can run the tests:
243
244```bat
245bin\zig.exe build test
246```
247
248This can take a long time.
249
250Note: In case you get the error "llvm-config not found" (or similar), make sure
251that you have **no** trailing slash (`/` or `\`) at the end of the
252`-DCMAKE_PREFIX_PATH` value.
253
254## Building LLVM, LLD, and Clang from Source
255
256### Windows
257
258Install [CMake](https://cmake.org/), version 3.20.0 or newer.
259
260[Download LLVM, Clang, and LLD sources](https://releases.llvm.org/download.html#22.0.0)
261The downloads from llvm lead to the github release pages, where the source's
262will be listed as : `llvm-22.X.X.src.tar.xz`, `clang-22.X.X.src.tar.xz`,
263`lld-22.X.X.src.tar.xz`. Unzip each to their own directory. Ensure no
264directories have spaces in them. For example:
265
266 * `C:\Users\Andy\llvm-22.0.0.src`
267 * `C:\Users\Andy\clang-22.0.0.src`
268 * `C:\Users\Andy\lld-22.0.0.src`
269
270Install [Build Tools for Visual Studio
2712019](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019).
272Be sure to select "C++ build tools" when prompted.
273 * You **must** additionally check the optional component labeled **C++ ATL for
274 v142 build tools**. As this won't be supplied by a default installation of
275 Visual Studio.
276 * Full list of supported MSVC versions:
277 - 2017 (version 15.8) (unverified)
278 - 2019 (version 16.7)
279
280Install [Python 3.9.4](https://www.python.org). Tick the box to add python to
281your PATH environment variable.
282
283#### LLVM
284
285Using the start menu, run **x64 Native Tools Command Prompt for VS 2019** and execute these commands, replacing `C:\Users\Andy` with the correct value. Here is listed a brief explanation of each of the CMake parameters we pass when configuring the build
286
287- `-Thost=x64` : Sets the windows toolset to use 64 bit mode.
288- `-A x64` : Make the build target 64 bit .
289- `-G "Visual Studio 16 2019"` : Specifies to generate a 2019 Visual Studio project, the best supported version.
290- `-DCMAKE_INSTALL_PREFIX=""` : Path that llvm components will being installed into by the install project.
291- `-DCMAKE_PREFIX_PATH=""` : Path that CMake will look into first when trying to locate dependencies, should be the same place as the install prefix. This will ensure that clang and lld will use your newly built llvm libraries.
292- `-DLLVM_ENABLE_ZLIB=OFF` : Don't build llvm with ZLib support as it's not required and will disrupt the target dependencies for components linking against llvm. This only has to be passed when building llvm, as this option will be saved into the config headers.
293- `-DCMAKE_BUILD_TYPE=Release` : Build llvm and components in release mode.
294- `-DCMAKE_BUILD_TYPE=Debug` : Build llvm and components in debug mode.
295- `-DLLVM_USE_CRT_RELEASE=MT` : Which C runtime should llvm use during release builds.
296- `-DLLVM_USE_CRT_DEBUG=MTd` : Make llvm use the debug version of the runtime in debug builds.
297
298##### Release Mode
299
300```bat
301mkdir C:\Users\Andy\llvm-22.0.0.src\build-release
302cd C:\Users\Andy\llvm-22.0.0.src\build-release
303"c:\Program Files\CMake\bin\cmake.exe" .. -Thost=x64 -G "Visual Studio 16 2019" -A x64 -DCMAKE_INSTALL_PREFIX=C:\Users\Andy\llvm+clang+lld-22.0.0-x86_64-windows-msvc-release-mt -DCMAKE_PREFIX_PATH=C:\Users\Andy\llvm+clang+lld-22.0.0-x86_64-windows-msvc-release-mt -
304DLLVM_ENABLE_ZLIB=OFF -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_LIBXML2=OFF -DLLVM_USE_CRT_RELEASE=MT
305msbuild /m -p:Configuration=Release INSTALL.vcxproj
306```
307
308##### Debug Mode
309
310```bat
311mkdir C:\Users\Andy\llvm-22.0.0.src\build-debug
312cd C:\Users\Andy\llvm-22.0.0.src\build-debug
313"c:\Program Files\CMake\bin\cmake.exe" .. -Thost=x64 -G "Visual Studio 16 2019" -A x64 -DCMAKE_INSTALL_PREFIX=C:\Users\andy\llvm+clang+lld-22.0.0-x86_64-windows-msvc-debug -
314DLLVM_ENABLE_ZLIB=OFF -DCMAKE_PREFIX_PATH=C:\Users\andy\llvm+clang+lld-22.0.0-x86_64-windows-msvc-debug -DCMAKE_BUILD_TYPE=Debug -DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD="AVR" -DLLVM_ENABLE_LIBXML2=OFF -DLLVM_USE_CRT_DEBUG=MTd
315msbuild /m INSTALL.vcxproj
316```
317
318#### LLD
319
320Using the start menu, run **x64 Native Tools Command Prompt for VS 2019** and execute these commands, replacing `C:\Users\Andy` with the correct value.
321
322##### Release Mode
323
324```bat
325mkdir C:\Users\Andy\lld-22.0.0.src\build-release
326cd C:\Users\Andy\lld-22.0.0.src\build-release
327"c:\Program Files\CMake\bin\cmake.exe" .. -Thost=x64 -G "Visual Studio 16 2019" -A x64 -DCMAKE_INSTALL_PREFIX=C:\Users\Andy\llvm+clang+lld-14.0.6-x86_64-windows-msvc-release-mt -DCMAKE_PREFIX_PATH=C:\Users\Andy\llvm+clang+lld-22.0.0-x86_64-windows-msvc-release-mt -DCMAKE_BUILD_TYPE=Release -DLLVM_USE_CRT_RELEASE=MT
328msbuild /m -p:Configuration=Release INSTALL.vcxproj
329```
330
331##### Debug Mode
332
333```bat
334mkdir C:\Users\Andy\lld-22.0.0.src\build-debug
335cd C:\Users\Andy\lld-22.0.0.src\build-debug
336"c:\Program Files\CMake\bin\cmake.exe" .. -Thost=x64 -G "Visual Studio 16 2019" -A x64 -DCMAKE_INSTALL_PREFIX=C:\Users\andy\llvm+clang+lld-22.0.0-x86_64-windows-msvc-debug -DCMAKE_PREFIX_PATH=C:\Users\andy\llvm+clang+lld-22.0.0-x86_64-windows-msvc-debug -DCMAKE_BUILD_TYPE=Debug -DLLVM_USE_CRT_DEBUG=MTd
337msbuild /m INSTALL.vcxproj
338```
339
340#### Clang
341
342Using the start menu, run **x64 Native Tools Command Prompt for VS 2019** and execute these commands, replacing `C:\Users\Andy` with the correct value.
343
344##### Release Mode
345
346```bat
347mkdir C:\Users\Andy\clang-22.0.0.src\build-release
348cd C:\Users\Andy\clang-22.0.0.src\build-release
349"c:\Program Files\CMake\bin\cmake.exe" .. -Thost=x64 -G "Visual Studio 16 2019" -A x64 -DCMAKE_INSTALL_PREFIX=C:\Users\Andy\llvm+clang+lld-22.0.0-x86_64-windows-msvc-release-mt -DCMAKE_PREFIX_PATH=C:\Users\Andy\llvm+clang+lld-22.0.0-x86_64-windows-msvc-release-mt -DCMAKE_BUILD_TYPE=Release -DLLVM_USE_CRT_RELEASE=MT
350msbuild /m -p:Configuration=Release INSTALL.vcxproj
351```
352
353##### Debug Mode
354
355```bat
356mkdir C:\Users\Andy\clang-22.0.0.src\build-debug
357cd C:\Users\Andy\clang-22.0.0.src\build-debug
358"c:\Program Files\CMake\bin\cmake.exe" .. -Thost=x64 -G "Visual Studio 16 2019" -A x64 -DCMAKE_INSTALL_PREFIX=C:\Users\andy\llvm+clang+lld-22.0.0-x86_64-windows-msvc-debug -DCMAKE_PREFIX_PATH=C:\Users\andy\llvm+clang+lld-22.0.0-x86_64-windows-msvc-debug -DCMAKE_BUILD_TYPE=Debug -DLLVM_USE_CRT_DEBUG=MTd
359msbuild /m INSTALL.vcxproj
360```
361
362### POSIX Systems
363
364This guide will get you both a Debug build of LLVM, and/or a Release build of LLVM.
365It intentionally does not require privileged access, using a prefix inside your home
366directory instead of a global installation.
367
368#### Release
369
370This is the generally recommended approach.
371
372```sh
373cd ~/Downloads
374git clone --depth 1 --branch release/22.x https://github.com/llvm/llvm-project llvm-project-22
375cd llvm-project-22
376git checkout release/22.x
377
378mkdir build-release
379cd build-release
380cmake ../llvm \
381 -DCMAKE_INSTALL_PREFIX=$HOME/local/llvm22-assert \
382 -DCMAKE_BUILD_TYPE=Release \
383 -DLLVM_ENABLE_PROJECTS="lld;clang" \
384 -DLLVM_ENABLE_LIBXML2=OFF \
385 -DLLVM_ENABLE_TERMINFO=OFF \
386 -DLLVM_ENABLE_LIBEDIT=OFF \
387 -DLLVM_ENABLE_ASSERTIONS=ON \
388 -DLLVM_PARALLEL_LINK_JOBS=1 \
389 -G Ninja
390ninja install
391```
392
393#### Debug
394
395This is occasionally needed when debugging Zig's LLVM backend. Here we build
396the three projects separately so that LLVM can be in Debug mode while the
397others are in Release mode.
398
399```sh
400cd ~/Downloads
401git clone --depth 1 --branch release/22.x https://github.com/llvm/llvm-project llvm-project-22
402cd llvm-project-22
403git checkout release/22.x
404
405# LLVM
406mkdir llvm/build-debug
407cd llvm/build-debug
408cmake .. \
409 -DCMAKE_INSTALL_PREFIX=$HOME/local/llvm22-debug \
410 -DCMAKE_PREFIX_PATH=$HOME/local/llvm22-debug \
411 -DCMAKE_BUILD_TYPE=Debug \
412 -DLLVM_ENABLE_LIBXML2=OFF \
413 -DLLVM_ENABLE_TERMINFO=OFF \
414 -DLLVM_ENABLE_LIBEDIT=OFF \
415 -DLLVM_PARALLEL_LINK_JOBS=1 \
416 -G Ninja
417ninja install
418cd ../..
419
420# LLD
421mkdir lld/build-debug
422cd lld/build-debug
423cmake .. \
424 -DCMAKE_INSTALL_PREFIX=$HOME/local/llvm22-debug \
425 -DCMAKE_PREFIX_PATH=$HOME/local/llvm22-debug \
426 -DCMAKE_BUILD_TYPE=Release \
427 -DLLVM_PARALLEL_LINK_JOBS=1 \
428 -DCMAKE_CXX_STANDARD=17 \
429 -G Ninja
430ninja install
431cd ../..
432
433# Clang
434mkdir clang/build-debug
435cd clang/build-debug
436cmake .. \
437 -DCMAKE_INSTALL_PREFIX=$HOME/local/llvm22-debug \
438 -DCMAKE_PREFIX_PATH=$HOME/local/llvm22-debug \
439 -DCMAKE_BUILD_TYPE=Release \
440 -DLLVM_PARALLEL_LINK_JOBS=1 \
441 -DLLVM_INCLUDE_TESTS=OFF \
442 -G Ninja
443ninja install
444cd ../..
445```
446
447Then add to your Zig CMake line that you got from the README.md:
448`-DCMAKE_PREFIX_PATH=$HOME/local/llvm22-debug` or
449`-DCMAKE_PREFIX_PATH=$HOME/local/llvm22-assert` depending on whether you want
450Debug or Release LLVM.
451
452
453## Contributing
454
455[Donate monthly](https://ziglang.org/zsf/).
456
457[Join a community](https://ziglang.org/community/).
458
459Zig is Free and Open Source Software. We welcome bug reports and patches from
460everyone. However, keep in mind that Zig governance is BDFN (Benevolent
461Dictator For Now) which means that Andrew Kelley has final say on the design
462and implementation of everything.
463
464### Make Software With Zig
465
466One of the best ways you can contribute to Zig is to start using it for an
467open-source personal project.
468
469This leads to discovering bugs and helps flesh out use cases, which lead to
470further design iterations of Zig. Importantly, each issue found this way comes
471with real world motivations, making it straightforward to explain the reasoning
472behind proposals and feature requests.
473
474Ideally, such a project will help you to learn new skills and add something
475to your personal portfolio at the same time.
476
477### Talk About Zig
478
479Another way to contribute is to write about Zig, speak about Zig at a
480conference, or do either of those things for your project which uses Zig.
481
482Programming languages live and die based on the pulse of their ecosystems. The
483more people involved, the more we can build great things upon each other's
484abstractions.
485
486### Strict No LLM / No AI Policy
487
488No LLMs for issues.
489
490No LLMs for patches / pull requests.
491
492No LLMs for comments on the bug tracker, including translation.
493
494English is encouraged, but not required. You are welcome to post in your native
495language and rely on others to have their own translation tools of choice to
496interpret your words.
497
498### Find a Contributor Friendly Issue
499
500The issue label
501[Contributor Friendly](https://codeberg.org/ziglang/zig/issues?labels=741726&state=open)
502exists to help you find issues that are **limited in scope and/or
503knowledge of Zig internals.**
504
505Please note that issues labeled
506[Proposal: Proposed](https://codeberg.org/ziglang/zig/issues?labels=746937&state=open)
507are still under consideration, and efforts to implement such a proposal have
508a high risk of being wasted. If you are interested in a proposal which is
509still under consideration, please express your interest in the issue tracker,
510providing extra insights and considerations that others have not yet expressed.
511The most highly regarded argument in such a discussion is a real world use case.
512
513Language proposals are not accepted. Please do not open an issue proposing to
514change the Zig language or syntax.
515
516### Editing Source Code
517
518For a smooth workflow, when building from source, it is recommended to use
519CMake with the following settings:
520
521 * `-DCMAKE_BUILD_TYPE=Release` - to recompile zig faster.
522 * `-GNinja` - Ninja is faster and simpler to use than Make.
523 * `-DZIG_NO_LIB=ON` - Prevents the build system from copying the lib/
524 directory to the installation prefix, causing zig use lib/ directly from the
525 source tree instead. Effectively, this makes it so that changes to lib/ do
526 not require re-running the install command to become active.
527
528After configuration, there are two scenarios:
529
530 1. Pulling upstream changes and rebuilding.
531 - In this case use `git pull` and then `ninja install`. Expected wait:
532 about 10 minutes.
533 2. Building from source after making local changes.
534 - In this case use `stage3/bin/zig build -p stage4 -Denable-llvm -Dno-lib`.
535 Expected wait: about 20 seconds.
536
537This leaves you with two builds of Zig:
538
539 * `stage3/bin/zig` - an optimized master branch build. Useful for
540 miscellaneous activities such as `zig fmt`, as well as for building the
541 compiler itself after changing the source code.
542 * `stage4/bin/zig` - a debug build that includes your local changes; useful
543 for testing and eliminating bugs before submitting a patch.
544
545To reduce time spent waiting for the compiler to build, try these techniques:
546
547 * Omit `-Denable-llvm` if you don't need the LLVM backend.
548 * Use `-Ddev=foo` to build with a reduced feature set for development of
549 specific features. See `zig build -h` for a list of options.
550 * Use `--watch -fincremental` to enable incremental compilation. This offers
551 **near instant rebuilds**.
552
553### Testing
554
555```sh
556stage4/bin/zig build test
557```
558
559This command runs the whole test suite, which does a lot of extra testing that
560you likely won't always need, and can take upwards of 1 hour. This is what the
561CI server runs when you make a pull request.
562
563To save time, you can add the `--help` option to the `zig build` command and
564see what options are available. One of the most helpful ones is
565`-Dskip-release`. Adding this option to the command above, along with
566`-Dskip-non-native`, will take the time down from around 2 hours to about 30
567minutes, and this is a good enough amount of testing before making a pull
568request.
569
570Another example is choosing a different set of things to test. For example,
571`test-std` instead of `test` will only run the standard library tests, and
572not the other ones. Combining this suggestion with the previous one, you could
573do this:
574
575```sh
576stage4/bin/zig build test-std -Dskip-release
577```
578
579This will run only the standard library tests in debug mode for all targets.
580It will cross-compile the tests for non-native targets but not run them.
581
582When making changes to the compiler source code, the most helpful test step to
583run is `test-behavior`. When editing documentation it is `docs`. You can find
584this information and more in the `zig build --help` menu.
585
586#### Directly Testing the Standard Library with `zig test`
587
588This command will run the standard library tests with only the native target
589configuration and is estimated to complete in 3 minutes:
590
591```sh
592zig build test-std -Dno-matrix
593```
594
595However, one may also use `zig test` directly. From inside the `ziglang/zig` repo root:
596
597```sh
598zig test lib/std/std.zig --zig-lib-dir lib
599```
600
601You can add `--test-filter "some test name"` to run a specific test or a subset of tests.
602(Running exactly 1 test is not reliably possible, because the test filter does not
603exclude anonymous test blocks, but that shouldn't interfere with whatever
604you're trying to test in practice.)
605
606Note that `--test-filter` filters on fully qualified names, so e.g. it's possible to run only the `std.json` tests with:
607
608```sh
609zig test lib/std/std.zig --zig-lib-dir lib --test-filter "json."
610```
611
612If you used `-Dno-lib` and you are in a `build/` subdirectory, you can omit the
613`--zig-lib-dir` argument:
614
615```sh
616stage3/bin/zig test ../lib/std/std.zig
617```
618
619#### Testing Non-Native Architectures with QEMU
620
621The Linux CI server additionally has qemu installed and sets `-fqemu`.
622This provides test coverage for, e.g. aarch64 even on x86_64 machines. It's
623recommended for Linux users to install qemu and enable this testing option
624when editing the standard library or anything related to a non-native
625architecture.
626
627QEMU packages provided by some system package managers (such as Debian) may be
628a few releases old, or may be missing newer targets such as aarch64 and RISC-V.
629[ziglang/qemu-static](https://codeberg.org/ziglang/qemu-static) offers static
630binaries of the latest QEMU version.
631
632##### Testing Non-Native libc Targets
633
634Testing foreign architectures with dynamically linked libc is one step trickier.
635This requires enabling `--libc-runtimes /path/to/libcs`. This path is obtained
636by building glibc and musl for multiple architectures. This process for me took
637an entire day to complete and takes up 65 GiB on my hard drive.
638
639[Instructions for producing this path.](https://codeberg.org/ziglang/infra/src/branch/master/building-libcs.md)
640
641It is understood that most contributors will not have these tests enabled. The
642CI machines provide coverage for these.
643
644#### Testing Windows from a Linux Machine with Wine
645
646When developing on Linux, another option is available to you: `-fwine`.
647This will enable running behavior tests and std lib tests with Wine. It's
648recommended for Linux users to install Wine and enable this testing option
649when editing the standard library or anything Windows-related.
650
651#### Testing WebAssembly using wasmtime
652
653If you have [wasmtime](https://wasmtime.dev/) installed, take advantage of the
654`-fwasmtime` flag which will enable running WASI behavior tests and std
655lib tests. It's recommended for all users to install wasmtime and enable this
656testing option when editing the standard library and especially anything
657WebAssembly-related.
658
659### Improving Translate-C
660
661`translate-c` is a feature provided by Zig that converts C source code into Zig
662source code. It powers the `zig translate-c` command, allowing Zig code to not
663only take advantage of function prototypes defined in C header files, but also
664`static inline` functions written in C, and even some macros.
665
666This feature used to work by using libclang API to parse and semantically
667analyze C/C++ files, and then based on the provided AST and type information,
668generating Zig AST, and finally using the mechanisms of `zig fmt` to render the
669Zig AST to a file.
670
671However, it is now based on [arocc](https://github.com/Vexu/arocc/), a
672third-party C compiler written in Zig. Test coverage, bug reports, and official
673implementation live in this repository: [ziglang/translate-c](https://codeberg.org/ziglang/translate-c/)
674
675This package is currently vendored into the Zig source tree. The TranslateC
676build step takes advantage of this to provide the ability to setup C
677translation in one's build.zig script.
678
679Please see the readme of the translate-c project for how to contribute. Once an
680issue is resolved (and test coverage added) there, the changes can be
681immediately backported to the zig compiler.
682
683However, in the future, this build step will be removed in favor of explicit
684dependency on the translate-c package via build system / package manager. At
685that point, Zig will stop vendoring arocc.
686
687### Autodoc
688
689Autodoc is an interactive, searchable, single-page web application for browsing
690Zig codebases.
691
692An autodoc deployment looks like this:
693
694```
695index.html
696main.js
697main.wasm
698sources.tar
699```
700
701* `main.js` and `index.html` are static files which live in a Zig installation
702 at `lib/docs/`.
703* `main.wasm` is compiled from the Zig files inside `lib/docs/wasm/`.
704* `sources.tar` is all the zig source files of the project.
705
706These artifacts are produced by the compiler when `-femit-docs` is passed.
707
708#### Making Changes
709
710The command `zig std` spawns an HTTP server that provides all the assets
711mentioned above specifically for the standard library.
712
713The server creates the requested files on the fly, including rebuilding
714`main.wasm` if any of its source files changed, and constructing `sources.tar`,
715meaning that any source changes to the documented files, or to the autodoc
716system itself are immediately reflected when viewing docs.
717
718This means you can test changes to Zig standard library documentation, as well
719as autodocs functionality, by pressing refresh in the browser.
720
721Prefixing the URL with `/debug` results in a debug build of `main.wasm`.
722
723#### Debugging the Zig Code
724
725While Firefox and Safari support are obviously required, I recommend Chromium
726for development for one reason in particular:
727
728[C/C++ DevTools Support (DWARF)](https://chromewebstore.google.com/detail/cc++-devtools-support-dwa/pdcpmagijalfljmkmjngeonclgbbannb)
729
730This makes debugging Zig WebAssembly code a breeze.
731
732#### The Sources Tarball
733
734The system expects the top level of `sources.tar` to be the set of modules
735documented. So for the Zig standard library you would do this:
736`tar cf std.tar std/`. Don't compress it; the idea is to rely on HTTP
737compression.
738
739Any files that are not `.zig` source files will be ignored by `main.wasm`,
740however, those files will take up wasted space in the tar file. For the
741standard library, use the set of files that zig installs to when running `zig
742build`, which is the same as the set of files that are provided on
743ziglang.org/download.
744
745If the system doesn't find a file named "foo/root.zig" or "foo/foo.zig", it
746will use the first file in the tar as the module root.
747
748You don't typically need to create `sources.tar` yourself, since it is lazily
749provided by the `zig std` HTTP server as well as produced by `-femit-docs`.
750
751
752## Testing Zig Code With LLDB
753
754[@jacobly0](https://github.com/jacobly0) maintains a fork of LLDB with Zig support:
755
756https://github.com/jacobly0/llvm-project/tree/lldb-zig
757
758This fork only contains changes for debugging programs compiled by Zig's
759self-hosted backends, i.e. `zig build-exe -fno-llvm ...`.
760
761### Building
762
763To build the LLDB fork, make sure you have
764[prerequisites](https://lldb.llvm.org/resources/build.html#preliminaries)
765installed, and then do something like:
766
767```sh
768$ cmake llvm -G Ninja -B build -DLLVM_ENABLE_PROJECTS="clang;lldb" -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_ASSERTIONS=ON -DLLDB_ENABLE_LIBEDIT=ON -DLLDB_ENABLE_PYTHON=ON
769$ cmake --build build --target lldb --target lldb-server
770```
771
772(You may need to manually [configure
773dependencies](https://lldb.llvm.org/resources/build.html#optional-dependencies)
774if CMake can't find them.)
775
776Once built, you can run `./build/bin/lldb` and so on.
777
778### Pretty Printers
779
780If you will be debugging the Zig compiler itself, or if you will be debugging
781any project compiled with Zig's LLVM backend (not recommended with the LLDB
782fork, prefer vanilla LLDB with a version that matches the version of LLVM that
783Zig is using), you can get a better debugging experience by using
784[`lldb_pretty_printers.py`](https://codeberg.org/ziglang/zig/src/branch/master/tools/lldb_pretty_printers.py).
785
786Put this line in `~/.lldbinit`:
787
788```
789command script import /path/to/zig/tools/lldb_pretty_printers.py
790```
791
792If you will be using Zig's LLVM backend (again, not recommended with the LLDB
793fork), you will also want these lines:
794
795```
796type category enable zig.lang
797type category enable zig.std
798```
799
800If you will be debugging a Zig compiler built using Zig's LLVM backend (again,
801not recommended with the LLDB fork), you will also want this line:
802
803```
804type category enable zig.stage2
805```
806