# 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)`