authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-11-22 16:01:02-08:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-11-22 16:01:02-08:00
log9473011052792b6ab6f2aa635d11e16eb63d512c
tree361f5f60bf44f67f75ce2c6b793ea1e467ad606b
parent3f2cf1c002a8eb46fa9beb9854c43174b5816e67

README: add some content from the wiki

also update the issue templates

2 files changed, 667 insertions(+), 25 deletions(-)

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