From 78f28e5f44aa95fdf410e229996a19b63ae4ae18 Mon Sep 17 00:00:00 2001
From: Donald Filimon <cbkshadow@icloud.com>
Date: Sun, 6 Jul 2025 10:36:16 -0400
Subject: [PATCH] docs: switch build instructions to Zig

---
 README.md            | 21 ++++++++++++++++-----
 docs/build_system.md | 12 ++++--------
 docs/testing.md      | 18 ++++++++----------
 tools/fuzz/README.md |  8 +++-----
 4 files changed, 31 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index c2a3691..41be1ca 100644
--- a/README.md
+++ b/README.md
@@ -16,11 +16,17 @@ Then run the REPL:
 ./ouro_lang
 ```
 
-A Zig build script is also included (`build.zig`) for environments with the Zig compiler installed.  It now compiles the C portions of the project using the C23 standard and links against LLVM in addition to `libc`. The script mirrors the basic CMake configuration and exposes tasks for running the module example and its unit tests.
+A Zig build script is also included (`build.zig`) for environments with the Zig compiler installed.  It compiles the C/C++ sources using modern standards and links against LLVM.  Use it to build the entire project with:
+
+```bash
+zig build
+```
+
+The script also exposes tasks for running the module example and its unit tests.
 
 ## Repository Structure
 
-The project now includes a CMake-based build system, tests, container setup, and documentation. Run `cmake` in a `build` directory to configure and build the modules in `src/`.
+The project includes a Zig-based build system, tests, container setup, and documentation. Invoke `zig build` to compile all targets.
 
 ## Zig Build with Modules
 
@@ -45,9 +51,14 @@ contributions are welcome—see `docs/contrib.md` for guidelines.
 
 ## Fuzzing Tools
 
-Experimental AFL++ harnesses live in `tools/fuzz`.  They can be
-built with CMake using `-DENABLE_FUZZ=ON` and run against the sample
-corpus in `fuzz/corpus` to discover crashes in the lexer and parser.
+Experimental AFL++ harnesses live in `tools/fuzz`.  You can build the
+lexer fuzzer with Zig and run it against the sample corpus in
+`fuzz/corpus` to discover crashes in the lexer and parser:
+
+```bash
+zig build fuzz-lexer
+./zig-out/bin/fuzz_lexer -i fuzz/corpus -o findings
+```
 
 
 ## Legacy Ouroboros Sources
diff --git a/docs/build_system.md b/docs/build_system.md
index 9389714..db8d54f 100644
--- a/docs/build_system.md
+++ b/docs/build_system.md
@@ -1,17 +1,13 @@
 # Build System
 
-The repository can be built using vanilla CMake or the Zig build
-script.  Typical CMake usage:
+The repository is built using Zig.  Compile all artifacts with:
 
 ```bash
-mkdir build && cd build
-cmake ..
-cmake --build . -- -j$(nproc)
-ctest --output-on-failure
+zig build
 ```
 
-The Zig file `build.zig` mirrors the above configuration and also
-exposes custom steps for running the module demo:
+The `build.zig` file also exposes custom steps for running the module
+demo and its unit tests:
 
 ```bash
 zig build mod-run
diff --git a/docs/testing.md b/docs/testing.md
index b39056c..2c931d7 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -5,19 +5,17 @@ fuzzing harness.
 
 ### Unit tests
 
-```
-mkdir build && cd build
-cmake ..
-cmake --build .
-ctest --output-on-failure
+Run the module test suite with:
+
+```bash
+zig build mod-test
 ```
 
 ### Fuzzing
 
-If AFL++ is installed you can build the lexer fuzzer:
+If AFL++ is installed you can build the lexer fuzzer using Zig:
 
-```
-cmake -DENABLE_FUZZ=ON ..
-make fuzz_lexer
-./fuzz_lexer -i ../fuzz/corpus -o ./findings
+```bash
+zig build fuzz-lexer
+./zig-out/bin/fuzz_lexer -i fuzz/corpus -o findings
 ```
diff --git a/tools/fuzz/README.md b/tools/fuzz/README.md
index 597e0c2..3c7e04b 100644
--- a/tools/fuzz/README.md
+++ b/tools/fuzz/README.md
@@ -1,17 +1,15 @@
 # Fuzzing Harness
 
-This directory contains the AFL++ based lexer fuzzer. Building it requires CMake with `-DENABLE_FUZZ=ON`:
+This directory contains the AFL++ based lexer fuzzer. Build it using Zig:
 
 ```bash
-mkdir build && cd build
-cmake -DENABLE_FUZZ=ON ..
-make fuzz_lexer
+zig build fuzz-lexer
 ```
 
 Provide a seed corpus in `fuzz/corpus` and run the fuzzer:
 
 ```bash
-./fuzz_lexer -i ../fuzz/corpus -o ./findings
+./zig-out/bin/fuzz_lexer -i fuzz/corpus -o findings
 ```
 
 Crashes will be written to the `findings` directory for investigation.