Cursor rule

1---
2description: ml-cpp build system knowledge — CMake, Gradle, Docker, CI
3globs: CMakeLists.txt, cmake/**, build.gradle, dev-tools/**, .buildkite/**
4---
5 
6# ml-cpp Build System
7 
8## CMake Structure
9 
10- Top-level `CMakeLists.txt` configures the project, includes `CTest`, detects compiler cache
11- `cmake/functions.cmake` defines `ml_add_library`, `ml_add_test_executable`, `ml_add_test`, `ml_install`
12- `cmake/variables.cmake` defines compiler flags per platform
13- Toolchain files: `cmake/{darwin-aarch64,linux-x86_64,linux-aarch64,windows-x86_64}.cmake`
14- `test/CMakeLists.txt` defines test targets: `ml_test`, `test_individually`, `build_tests`, `run_tests`
15 
16## Important: CTest and Target Names
17 
18- `include(CTest)` reserves the `test` target name — custom targets must not use it
19- Our monolithic test target is named `ml_test` (not `test`)
20- `test_individually` runs tests via CTest with parallel execution
21 
22## Build Acceleration
23 
24### Unity Builds (`-DCMAKE_UNITY_BUILD=ON`)
25- Combines multiple source files into single translation units
26- Effective on x86_64 (~41% faster), minimal on aarch64
27- Conflicts from anonymous-namespace symbols need `SKIP_UNITY_BUILD_INCLUSION`
28- Disabled entirely for: `MlMathsTimeSeries`, `MlMathsAnalytics`, `MlApi`, `ml_test_maths_common`, `ml_test_api`
29 
30### Precompiled Headers (`-DML_PCH=ON`)
31- Custom option, applied in `cmake/functions.cmake` via `target_precompile_headers()`
32- STL headers + `<boost/test/unit_test.hpp>` for test targets
33- Do NOT include `<boost/unordered_map.hpp>` — conflicts with `boost/json.hpp` on GCC
34 
35### sccache (GCS Backend)
36- `dev-tools/setup_sccache.sh` / `setup_sccache.ps1` — downloads, configures, starts
37- GCS bucket: `gs://elastic-ml-cpp-sccache`, per-platform prefix (`linux-x86_64/`, etc.)
38- Vault: `secret/ci/elastic-ml-cpp/sccache/gcs_service_account`
39- Requires `-DCMAKE_CXX_COMPILER_LAUNCHER=sccache` — top-level CMakeLists.txt respects existing launcher
40 
41### Compiler Launcher Precedence
42If `CMAKE_CXX_COMPILER_LAUNCHER` is already set (e.g. sccache), the ccache auto-detection in `CMakeLists.txt` is skipped.
43 
44### MSVC `/Z7` vs `/Zi`
45- `/Zi`: Debug info via shared PDB (`mspdbsrv.exe`) — serializes parallel compilation
46- `/Z7`: Debug info embedded in `.obj` — fully parallel, sccache-compatible
47- We use `/Z7` for all Windows configurations; `/FS` flag removed as unnecessary
48 
49## Gradle Integration
50 
51- `build.gradle` invokes CMake for macOS and Windows builds
52- `task test` calls `cmake --build ... -t ml_test`
53- `task check` depends on `test`
54- `testParallel` formula: `numCpus <= 4 ? 2 : Math.ceil(numCpus / 2.0)` (Unix), `2` (Windows)
55- Environment `CMAKE_FLAGS` are appended to Gradle's internal cmake flags (stripping duplicate toolchain)
56 
57## Docker Builds (Linux)
58 
59- `dev-tools/docker/docker_entrypoint.sh` — main build/test script inside containers
60- `dev-tools/docker_build.sh` / `docker_test.sh` — host orchestration
61- Linux aarch64 builds run in Docker; x86_64 runs `docker_entrypoint.sh` directly
62- cgroup-aware CPU detection: check `/sys/fs/cgroup/cpu.max` (cgroups v2) or `/sys/fs/cgroup/cpu/cpu.cfs_{quota,period}_us` (v1)
63- `ZIP_COMPRESSION_LEVEL`: 1 for PR/debug builds, 9 for release branches
64 
65## Test Parallelism
66 
67- Test parallelism formula: `numCpus <= 4 ? 2 : ceil(numCpus / 2)`
68- CKMostCorrelatedTest/testScale is CPU-time-sensitive — keep parallelism conservative on low-core machines
69- Each test suite internally uses `ctest --parallel <cpus>` for individual test case parallelism
70