Add claude docs

2026-06-16 10:15:59 -05:00
parent 8131bcd4d4
commit ed5c60ac30
32 changed files with 3781 additions and 13 deletions
@@ -0,0 +1,85 @@
+# Build System
+
+Dusk uses CMake exclusively. Every source subdirectory owns its own
+`CMakeLists.txt`; the root file only wires them together.
+
+## Golden rule
+
+**Never add source files to the root `CMakeLists.txt` directly.**
+
+Every `.c` file is registered in the `CMakeLists.txt` that lives in
+the same directory (or a direct parent within the same module):
+
+```cmake
+target_sources(${DUSK_LIBRARY_TARGET_NAME}
+  PUBLIC
+    myfile.c
+)
+```
+
+## Configuration variables
+
+| Variable               | Purpose                                      |
+|------------------------|----------------------------------------------|
+| `DUSK_TARGET_SYSTEM`   | Selects the platform (see `.claude/platforms.md`) |
+| `DUSK_BUILD_TESTS`     | Enables the test suite (`ON` / `OFF`)        |
+| `CMAKE_TOOLCHAIN_FILE` | Cross-compiler toolchain for console targets |
+| `CMAKE_BUILD_TYPE`     | `Debug` / `Release` / `RelWithDebInfo`       |
+
+## Typical configure + build
+
+```sh
+# Linux debug build
+cmake -B build -DDUSK_TARGET_SYSTEM=linux -DCMAKE_BUILD_TYPE=Debug
+cmake --build build
+
+# Linux with tests
+cmake -B build \
+      -DDUSK_TARGET_SYSTEM=linux \
+      -DDUSK_BUILD_TESTS=ON \
+      -DCMAKE_BUILD_TYPE=Debug
+cmake --build build
+ctest --test-dir build
+```
+
+## Module layout convention
+
+Each logical module under `src/` gets its own directory:
+
+```
+src/dusk/              Platform-agnostic core
+src/dusk<platform>/    Platform-specific impl (one dir per target)
+```
+
+Within a module, subdirectories mirror subsystem boundaries
+(`asset/`, `entity/`, `script/`, etc.). Each subdirectory has its own
+`CMakeLists.txt` that is `add_subdirectory()`-included by its parent.
+
+## Adding a new source file
+
+1. Create `src/.../myfile.c` (and `myfile.h` if needed).
+2. Open the `CMakeLists.txt` in the same directory.
+3. Add `myfile.c` to the `target_sources(...)` block.
+4. Do **not** touch any parent or root `CMakeLists.txt`.
+
+## Platform-conditional sources
+
+Wrap platform-only files in a generator expression or `if()` block:
+
+```cmake
+if(DUSK_TARGET_SYSTEM STREQUAL "psp")
+  target_sources(${DUSK_LIBRARY_TARGET_NAME}
+    PUBLIC
+      mypspfile.c
+  )
+endif()
+```
+
+## Tests
+
+- Test files live in `test/` mirroring the `src/dusk/` structure.
+- Enable with `-DDUSK_BUILD_TESTS=ON`.
+- Uses cmocka; include `dusktest.h` in every test file.
+- Every test must assert `memoryGetAllocatedCount() == 0` at teardown
+  to catch allocator leaks.
+- Test function signature: `static void test_something(void **state)`