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 @@
33A general-purpose programming language and toolchain for maintaining
44**robust**, **optimal**, and **reusable** software.
55
6<https://ziglang.org/>
6https://ziglang.org/
77
88## Documentation
99
......@@ -232,9 +232,11 @@ You now have the `zig.exe` binary at `bin\zig.exe` and you can run the tests:
232232bin\zig.exe build test
233233```
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
239241## 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`.
745747
746748## 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
752757### 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```console
763```
757764$ 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
758765$ cmake --build build --target lldb --target lldb-server
759766```
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
763772Once built, you can run `./build/bin/lldb` and so on.
764773
765774### 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
769782Put this line in `~/.lldbinit`:
770783
......@@ -772,13 +785,17 @@ Put this line in `~/.lldbinit`:
772785command script import /path/to/zig/tools/lldb_pretty_printers.py
773786```
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
777791```
778792type category enable zig.lang
779793type category enable zig.std
780794```
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
782799```
783800type category enable zig.stage2
784801```