authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-11-26 09:55:00-08:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2025-11-26 09:55:00-08:00
logfc8a51ece3fe0bf4b9662b3ce072f8f82238457d
treef91c48d53eb3caec3b1ec3a2676ae3354407d685
parent2e328beaa5f3edb445e79c6679c8e3508b149a9c

README: enhance plain text readability

this file is first and foremost plain text, and rendered markdown second.

1 files changed, 28 insertions(+), 11 deletions(-)

README.md+28-11
...@@ -3,7 +3,7 @@...@@ -3,7 +3,7 @@
3A general-purpose programming language and toolchain for maintaining3A general-purpose programming language and toolchain for maintaining
4**robust**, **optimal**, and **reusable** software.4**robust**, **optimal**, and **reusable** software.
55
6<https://ziglang.org/>6https://ziglang.org/
77
8## Documentation8## Documentation
99
...@@ -232,9 +232,11 @@ You now have the `zig.exe` binary at `bin\zig.exe` and you can run the tests:...@@ -232,9 +232,11 @@ You now have the `zig.exe` binary at `bin\zig.exe` and you can run the tests:
232bin\zig.exe build test232bin\zig.exe build test
233```233```
234234
235This can take a long time. For tips & tricks on using the test suite, see [Editing Source Code](#editing-source-code).235This can take a long time.
236236
237Note: 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. 237Note: In case you get the error "llvm-config not found" (or similar), make sure
238that you have **no** trailing slash (`/` or `\`) at the end of the
239`-DCMAKE_PREFIX_PATH` value.
238240
239## Building LLVM, LLD, and Clang from Source241## Building LLVM, LLD, and Clang from Source
240242
...@@ -745,26 +747,37 @@ provided by the `zig std` HTTP server as well as produced by `-femit-docs`....@@ -745,26 +747,37 @@ provided by the `zig std` HTTP server as well as produced by `-femit-docs`.
745747
746## Testing Zig Code With LLDB748## Testing Zig Code With LLDB
747749
748[@jacobly0](https://github.com/jacobly0) maintains a fork of LLDB with Zig support: <https://github.com/jacobly0/llvm-project/tree/lldb-zig>750[@jacobly0](https://github.com/jacobly0) maintains a fork of LLDB with Zig support:
749751
750This fork only contains changes for debugging programs compiled by Zig's self-hosted backends, i.e. `zig build-exe -fno-llvm ...`.752https://github.com/jacobly0/llvm-project/tree/lldb-zig
753
754This fork only contains changes for debugging programs compiled by Zig's
755self-hosted backends, i.e. `zig build-exe -fno-llvm ...`.
751756
752### Building757### Building
753758
754To build the LLDB fork, make sure you have [prerequisites](https://lldb.llvm.org/resources/build.html#preliminaries) installed, and then do something like:759To build the LLDB fork, make sure you have
760[prerequisites](https://lldb.llvm.org/resources/build.html#preliminaries)
761installed, and then do something like:
755762
756```console763```
757$ 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=ON764$ 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
758$ cmake --build build --target lldb --target lldb-server765$ cmake --build build --target lldb --target lldb-server
759```766```
760767
761(You may need to manually [configure dependencies](https://lldb.llvm.org/resources/build.html#optional-dependencies) if CMake can't find them.)768(You may need to manually [configure
769dependencies](https://lldb.llvm.org/resources/build.html#optional-dependencies)
770if CMake can't find them.)
762771
763Once built, you can run `./build/bin/lldb` and so on.772Once built, you can run `./build/bin/lldb` and so on.
764773
765### Pretty Printers774### Pretty Printers
766775
767If 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).776If you will be debugging the Zig compiler itself, or if you will be debugging
777any project compiled with Zig's LLVM backend (not recommended with the LLDB
778fork, prefer vanilla LLDB with a version that matches the version of LLVM that
779Zig is using), you can get a better debugging experience by using
780[`lldb_pretty_printers.py`](https://github.com/ziglang/zig/blob/master/tools/lldb_pretty_printers.py).
768781
769Put this line in `~/.lldbinit`:782Put this line in `~/.lldbinit`:
770783
...@@ -772,13 +785,17 @@ Put this line in `~/.lldbinit`:...@@ -772,13 +785,17 @@ Put this line in `~/.lldbinit`:
772command script import /path/to/zig/tools/lldb_pretty_printers.py785command script import /path/to/zig/tools/lldb_pretty_printers.py
773```786```
774787
775If you will be using Zig's LLVM backend (again, not recommended with the LLDB fork), you will also want these lines:788If you will be using Zig's LLVM backend (again, not recommended with the LLDB
789fork), you will also want these lines:
776790
777```791```
778type category enable zig.lang792type category enable zig.lang
779type category enable zig.std793type category enable zig.std
780```794```
781If 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:795
796If you will be debugging a Zig compiler built using Zig's LLVM backend (again,
797not recommended with the LLDB fork), you will also want this line:
798
782```799```
783type category enable zig.stage2800type category enable zig.stage2
784```801```