From 1a72bdb9b0b27cc2d48c65e0c69d1c3ae0d351e9 Mon Sep 17 00:00:00 2001 From: Thomas Falk <276396176+thomas-falk-research@users.noreply.github.com> Date: Thu, 7 May 2026 11:41:53 +0200 Subject: [PATCH] docs: document CMake build path and macOS case-insensitive-FS collision MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a "Building with CMake" subsection to README.md §"Build Instructions" documenting the cmake build path (CMakeLists.txt ships in the repo but was previously undocumented), and explicitly calls out a deterministic build failure on case-insensitive filesystems — APFS (macOS default) and NTFS (Windows default) — caused by the existing Bazel BUILD file colliding with cmake's conventional build/ binary directory. Workaround documented: use a non-conflicting binary directory name (cmake-build, _build, or out) via `cmake -B cmake-build` instead of `cmake -B build`. No code changes; documentation only. ~22 lines added to README.md, zero lines removed. --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 77bf73e..1b6269e 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,18 @@ Tesseract uses [Bazel](https://bazel.build/) as its build system. To build the d bazel build src:all ``` +#### Building with CMake + +Tesseract also ships a `CMakeLists.txt` that vendors all C++ dependencies (Stim, HiGHS, argparse, nlohmann/json, Boost) via `FetchContent` for a single self-contained build: + +```bash +cmake -S . -B cmake-build -DCMAKE_BUILD_TYPE=Release +cmake --build cmake-build -j +# Binary: cmake-build/tesseract +``` + +> **Note for macOS / Windows users.** The conventional CMake binary directory name is `build`, but the Bazel build descriptor at the repository root is named `BUILD` (uppercase). On case-insensitive filesystems — APFS (macOS default) and NTFS (Windows default) — `cmake -B build` fails with `Error: /BUILD is not a directory` because CMake cannot create a directory whose name collides with the existing `BUILD` regular file. Use a non-conflicting name (for example `cmake-build`, `_build`, or `out`) as shown above. On case-sensitive filesystems (typical Linux ext4 / xfs) `cmake -B build` works without modification. + ## Running Tests Unit tests are executed with Bazel. Run the quick test suite using: