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_ENABLE_ZSTD=OFF \
389 -DLLVM_PARALLEL_LINK_JOBS=1 \
390 -G Ninja
391ninja install
392```
393
394#### Debug
395
396This is occasionally needed when debugging Zig's LLVM backend. Here we build
397the three projects separately so that LLVM can be in Debug mode while the
398others are in Release mode.
399
400```sh
401cd ~/Downloads
402git clone --depth 1 --branch release/22.x https://github.com/llvm/llvm-project llvm-project-22
403cd llvm-project-22
404git checkout release/22.x
405
406# LLVM
407mkdir llvm/build-debug
408cd llvm/build-debug
409cmake .. \
410 -DCMAKE_INSTALL_PREFIX=$HOME/local/llvm22-debug \
411 -DCMAKE_PREFIX_PATH=$HOME/local/llvm22-debug \
412 -DCMAKE_BUILD_TYPE=Debug \
413 -DLLVM_ENABLE_LIBXML2=OFF \
414 -DLLVM_ENABLE_TERMINFO=OFF \
415 -DLLVM_ENABLE_LIBEDIT=OFF \
416 -DLLVM_PARALLEL_LINK_JOBS=1 \
417 -G Ninja
418ninja install
419cd ../..
420
421# LLD
422mkdir lld/build-debug
423cd lld/build-debug
424cmake .. \
425 -DCMAKE_INSTALL_PREFIX=$HOME/local/llvm22-debug \
426 -DCMAKE_PREFIX_PATH=$HOME/local/llvm22-debug \
427 -DCMAKE_BUILD_TYPE=Release \
428 -DLLVM_PARALLEL_LINK_JOBS=1 \
429 -DCMAKE_CXX_STANDARD=17 \
430 -G Ninja
431ninja install
432cd ../..
433
434# Clang
435mkdir clang/build-debug
436cd clang/build-debug
437cmake .. \
438 -DCMAKE_INSTALL_PREFIX=$HOME/local/llvm22-debug \
439 -DCMAKE_PREFIX_PATH=$HOME/local/llvm22-debug \
440 -DCMAKE_BUILD_TYPE=Release \
441 -DLLVM_PARALLEL_LINK_JOBS=1 \
442 -DLLVM_INCLUDE_TESTS=OFF \
443 -G Ninja
444ninja install
445cd ../..
446```
447
448Then add to your Zig CMake line that you got from the README.md:
449`-DCMAKE_PREFIX_PATH=$HOME/local/llvm22-debug` or
450`-DCMAKE_PREFIX_PATH=$HOME/local/llvm22-assert` depending on whether you want
451Debug or Release LLVM.
452
453
454## Contributing
455
456[Donate monthly](https://ziglang.org/zsf/).
457
458[Join a community](https://ziglang.org/community/).
459
460Zig is Free and Open Source Software. We welcome bug reports and patches from
461everyone. However, keep in mind that Zig governance is BDFN (Benevolent
462Dictator For Now) which means that Andrew Kelley has final say on the design
463and implementation of everything.
464
465### Make Software With Zig
466
467One of the best ways you can contribute to Zig is to start using it for an
468open-source personal project.
469
470This leads to discovering bugs and helps flesh out use cases, which lead to
471further design iterations of Zig. Importantly, each issue found this way comes
472with real world motivations, making it straightforward to explain the reasoning
473behind proposals and feature requests.
474
475Ideally, such a project will help you to learn new skills and add something
476to your personal portfolio at the same time.
477
478### Talk About Zig
479
480Another way to contribute is to write about Zig, speak about Zig at a
481conference, or do either of those things for your project which uses Zig.
482
483Programming languages live and die based on the pulse of their ecosystems. The
484more people involved, the more we can build great things upon each other's
485abstractions.
486
487### Strict No LLM / No AI Policy
488
489No LLMs for issues.
490
491No LLMs for patches / pull requests.
492
493No LLMs for comments on the bug tracker, including translation.
494
495English is encouraged, but not required. You are welcome to post in your native
496language and rely on others to have their own translation tools of choice to
497interpret your words.
498
499### Find a Contributor Friendly Issue
500
501The issue label
502[Contributor Friendly](https://codeberg.org/ziglang/zig/issues?labels=741726&state=open)
503exists to help you find issues that are **limited in scope and/or
504knowledge of Zig internals.**
505
506Please note that issues labeled
507[Proposal: Proposed](https://codeberg.org/ziglang/zig/issues?labels=746937&state=open)
508are still under consideration, and efforts to implement such a proposal have
509a high risk of being wasted. If you are interested in a proposal which is
510still under consideration, please express your interest in the issue tracker,
511providing extra insights and considerations that others have not yet expressed.
512The most highly regarded argument in such a discussion is a real world use case.
513
514Language proposals are not accepted. Please do not open an issue proposing to
515change the Zig language or syntax.
516
517### Editing Source Code
518
519For a smooth workflow, when building from source, it is recommended to use
520CMake with the following settings:
521
522 * `-DCMAKE_BUILD_TYPE=Release` - to recompile zig faster.
523 * `-GNinja` - Ninja is faster and simpler to use than Make.
524 * `-DZIG_NO_LIB=ON` - Prevents the build system from copying the lib/
525 directory to the installation prefix, causing zig use lib/ directly from the
526 source tree instead. Effectively, this makes it so that changes to lib/ do
527 not require re-running the install command to become active.
528
529After configuration, there are two scenarios:
530
531 1. Pulling upstream changes and rebuilding.
532 - In this case use `git pull` and then `ninja install`. Expected wait:
533 about 10 minutes.
534 2. Building from source after making local changes.
535 - In this case use `stage3/bin/zig build -p stage4 -Denable-llvm -Dno-lib`.
536 Expected wait: about 20 seconds.
537
538This leaves you with two builds of Zig:
539
540 * `stage3/bin/zig` - an optimized master branch build. Useful for
541 miscellaneous activities such as `zig fmt`, as well as for building the
542 compiler itself after changing the source code.
543 * `stage4/bin/zig` - a debug build that includes your local changes; useful
544 for testing and eliminating bugs before submitting a patch.
545
546To reduce time spent waiting for the compiler to build, try these techniques:
547
548 * Omit `-Denable-llvm` if you don't need the LLVM backend.
549 * Use `-Ddev=foo` to build with a reduced feature set for development of
550 specific features. See `zig build -h` for a list of options.
551 * Use `--watch -fincremental` to enable incremental compilation. This offers
552 **near instant rebuilds**.
553
554### Testing
555
556```sh
557stage4/bin/zig build test
558```
559
560This command runs the whole test suite, which does a lot of extra testing that
561you likely won't always need, and can take upwards of 1 hour. This is what the
562CI server runs when you make a pull request.
563
564To save time, you can add the `--help` option to the `zig build` command and
565see what options are available. One of the most helpful ones is
566`-Dskip-release`. Adding this option to the command above, along with
567`-Dskip-non-native`, will take the time down from around 2 hours to about 30
568minutes, and this is a good enough amount of testing before making a pull
569request.
570
571Another example is choosing a different set of things to test. For example,
572`test-std` instead of `test` will only run the standard library tests, and
573not the other ones. Combining this suggestion with the previous one, you could
574do this:
575
576```sh
577stage4/bin/zig build test-std -Dskip-release
578```
579
580This will run only the standard library tests in debug mode for all targets.
581It will cross-compile the tests for non-native targets but not run them.
582
583When making changes to the compiler source code, the most helpful test step to
584run is `test-behavior`. When editing documentation it is `docs`. You can find
585this information and more in the `zig build --help` menu.
586
587#### Directly Testing the Standard Library with `zig test`
588
589This command will run the standard library tests with only the native target
590configuration and is estimated to complete in 3 minutes:
591
592```sh
593zig build test-std -Dno-matrix
594```
595
596However, one may also use `zig test` directly. From inside the `ziglang/zig` repo root:
597
598```sh
599zig test lib/std/std.zig --zig-lib-dir lib
600```
601
602You can add `--test-filter "some test name"` to run a specific test or a subset of tests.
603(Running exactly 1 test is not reliably possible, because the test filter does not
604exclude anonymous test blocks, but that shouldn't interfere with whatever
605you're trying to test in practice.)
606
607Note that `--test-filter` filters on fully qualified names, so e.g. it's possible to run only the `std.json` tests with:
608
609```sh
610zig test lib/std/std.zig --zig-lib-dir lib --test-filter "json."
611```
612
613If you used `-Dno-lib` and you are in a `build/` subdirectory, you can omit the
614`--zig-lib-dir` argument:
615
616```sh
617stage3/bin/zig test ../lib/std/std.zig
618```
619
620#### Testing Non-Native Architectures with QEMU
621
622The Linux CI server additionally has qemu installed and sets `-fqemu`.
623This provides test coverage for, e.g. aarch64 even on x86_64 machines. It's
624recommended for Linux users to install qemu and enable this testing option
625when editing the standard library or anything related to a non-native
626architecture.
627
628QEMU packages provided by some system package managers (such as Debian) may be
629a few releases old, or may be missing newer targets such as aarch64 and RISC-V.
630[ziglang/qemu-static](https://codeberg.org/ziglang/qemu-static) offers static
631binaries of the latest QEMU version.
632
633##### Testing Non-Native libc Targets
634
635Testing foreign architectures with dynamically linked libc is one step trickier.
636This requires enabling `--libc-runtimes /path/to/libcs`. This path is obtained
637by building glibc and musl for multiple architectures. This process for me took
638an entire day to complete and takes up 65 GiB on my hard drive.
639
640[Instructions for producing this path.](https://codeberg.org/ziglang/infra/src/branch/master/building-libcs.md)
641
642It is understood that most contributors will not have these tests enabled. The
643CI machines provide coverage for these.
644
645#### Testing Windows from a Linux Machine with Wine
646
647When developing on Linux, another option is available to you: `-fwine`.
648This will enable running behavior tests and std lib tests with Wine. It's
649recommended for Linux users to install Wine and enable this testing option
650when editing the standard library or anything Windows-related.
651
652#### Testing WebAssembly using wasmtime
653
654If you have [wasmtime](https://wasmtime.dev/) installed, take advantage of the
655`-fwasmtime` flag which will enable running WASI behavior tests and std
656lib tests. It's recommended for all users to install wasmtime and enable this
657testing option when editing the standard library and especially anything
658WebAssembly-related.
659
660### Improving Translate-C
661
662`translate-c` is a feature provided by Zig that converts C source code into Zig
663source code. It powers the `zig translate-c` command, allowing Zig code to not
664only take advantage of function prototypes defined in C header files, but also
665`static inline` functions written in C, and even some macros.
666
667This feature used to work by using libclang API to parse and semantically
668analyze C/C++ files, and then based on the provided AST and type information,
669generating Zig AST, and finally using the mechanisms of `zig fmt` to render the
670Zig AST to a file.
671
672However, it is now based on [arocc](https://github.com/Vexu/arocc/), a
673third-party C compiler written in Zig. Test coverage, bug reports, and official
674implementation live in this repository: [ziglang/translate-c](https://codeberg.org/ziglang/translate-c/)
675
676This package is currently vendored into the Zig source tree. The TranslateC
677build step takes advantage of this to provide the ability to setup C
678translation in one's build.zig script.
679
680Please see the readme of the translate-c project for how to contribute. Once an
681issue is resolved (and test coverage added) there, the changes can be
682immediately backported to the zig compiler.
683
684However, in the future, this build step will be removed in favor of explicit
685dependency on the translate-c package via build system / package manager. At
686that point, Zig will stop vendoring arocc.
687
688### Autodoc
689
690Autodoc is an interactive, searchable, single-page web application for browsing
691Zig codebases.
692
693An autodoc deployment looks like this:
694
695```
696index.html
697main.js
698main.wasm
699sources.tar
700```
701
702* `main.js` and `index.html` are static files which live in a Zig installation
703 at `lib/docs/`.
704* `main.wasm` is compiled from the Zig files inside `lib/docs/wasm/`.
705* `sources.tar` is all the zig source files of the project.
706
707These artifacts are produced by the compiler when `-femit-docs` is passed.
708
709#### Making Changes
710
711The command `zig std` spawns an HTTP server that provides all the assets
712mentioned above specifically for the standard library.
713
714The server creates the requested files on the fly, including rebuilding
715`main.wasm` if any of its source files changed, and constructing `sources.tar`,
716meaning that any source changes to the documented files, or to the autodoc
717system itself are immediately reflected when viewing docs.
718
719This means you can test changes to Zig standard library documentation, as well
720as autodocs functionality, by pressing refresh in the browser.
721
722Prefixing the URL with `/debug` results in a debug build of `main.wasm`.
723
724#### Debugging the Zig Code
725
726While Firefox and Safari support are obviously required, I recommend Chromium
727for development for one reason in particular:
728
729[C/C++ DevTools Support (DWARF)](https://chromewebstore.google.com/detail/cc++-devtools-support-dwa/pdcpmagijalfljmkmjngeonclgbbannb)
730
731This makes debugging Zig WebAssembly code a breeze.
732
733#### The Sources Tarball
734
735The system expects the top level of `sources.tar` to be the set of modules
736documented. So for the Zig standard library you would do this:
737`tar cf std.tar std/`. Don't compress it; the idea is to rely on HTTP
738compression.
739
740Any files that are not `.zig` source files will be ignored by `main.wasm`,
741however, those files will take up wasted space in the tar file. For the
742standard library, use the set of files that zig installs to when running `zig
743build`, which is the same as the set of files that are provided on
744ziglang.org/download.
745
746If the system doesn't find a file named "foo/root.zig" or "foo/foo.zig", it
747will use the first file in the tar as the module root.
748
749You don't typically need to create `sources.tar` yourself, since it is lazily
750provided by the `zig std` HTTP server as well as produced by `-femit-docs`.
751
752
753## Testing Zig Code With LLDB
754
755[@jacobly0](https://github.com/jacobly0) maintains a fork of LLDB with Zig support:
756
757https://github.com/jacobly0/llvm-project/tree/lldb-zig
758
759This fork only contains changes for debugging programs compiled by Zig's
760self-hosted backends, i.e. `zig build-exe -fno-llvm ...`.
761
762### Building
763
764To build the LLDB fork, make sure you have
765[prerequisites](https://lldb.llvm.org/resources/build.html#preliminaries)
766installed, and then do something like:
767
768```sh
769$ 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
770$ cmake --build build --target lldb --target lldb-server
771```
772
773(You may need to manually [configure
774dependencies](https://lldb.llvm.org/resources/build.html#optional-dependencies)
775if CMake can't find them.)
776
777Once built, you can run `./build/bin/lldb` and so on.
778
779### Pretty Printers
780
781If you will be debugging the Zig compiler itself, or if you will be debugging
782any project compiled with Zig's LLVM backend (not recommended with the LLDB
783fork, prefer vanilla LLDB with a version that matches the version of LLVM that
784Zig is using), you can get a better debugging experience by using
785[`lldb/pretty_printers.py`](https://codeberg.org/ziglang/zig/src/branch/master/lib/lldb/pretty_printers.py)
786which is included in Zig's installed lib dir.
787
788Put this line in `~/.lldbinit`:
789
790```
791command script import /path/to/zig/lib/lldb/pretty_printers.py
792```
793
794If you will be debugging a Zig compiler built using Zig's self-hosted backends,
795you will also want this line:
796
797```
798type category enable zig.compiler
799```
800
801If you will be using Zig's LLVM backend (again, not recommended with the LLDB
802fork), you will also want these lines:
803
804```
805type category enable zig.lang
806type category enable zig.std
807```
808
809If you will be debugging a Zig compiler built using Zig's LLVM backend without
810using the LLDB fork, you will also want this line:
811
812```
813type category enable zig
814```