AGENTS.md in elastic/ml-cpp runs 1,537 words across 23 headings.
Machine learning C++ code
C++Covers
8 of the 20 section tags
In the order a file is read inHeadings
23 headings, in the order the file writes them
01Elasticsearch Machine Learning C++
02Toolchain
03Build & Run Commands
04Project Structure
05CMake Helper Functions
06Adding a Shared Library
07Adding an Executable
08Adding a Test Executable
09Registering Tests with the Build
10Platform-Specific Sources
11Testing
12Running Tests
13Precommit (format + test)
14Writing Tests
15Formatting & Style
16Naming Conventions
17Code Conventions
18File Layout
19Documentation
20License Headers
21CI
22Pull Requests
23Best Practices for Automation Agents
Commands
17 commands this file writes down
Extracted from the file, verbatimcmake -B cmake-build-relwithdebinfo
cmake --build cmake-build-relwithdebinfo -j$(nproc)
./gradlew :compile
cmake/
cmake --build cmake-build-relwithdebinfo -t test
cmake --build cmake-build-relwithdebinfo -t test_core
cmake --build cmake-build-relwithdebinfo -t test_model
cmake --build cmake-build-relwithdebinfo -j8 -t test_individually
cmake --build cmake-build-relwithdebinfo -j8 -t test_api_individually
cmake --build cmake-build-relwithdebinfo -t test_all_parallel
cmake --build cmake-build-relwithdebinfo -j8 -t precommit
cmake --build cmake-build-relwithdebinfo -t format
./gradlew
cmake/<os>-<arch>.cmake
cmake/functions.cmake
./gradlew precommit
./gradlew format
The file
AGENTS.md
First 160 of 292 lines1# Elasticsearch Machine Learning C++
2
3## Toolchain
4- **Language**: C++20 (`CMAKE_CXX_STANDARD 20`).
5- **Build system**: CMake (primary) or Gradle wrapper (`./gradlew`).
6- **Compilers**: GCC 13.3.0 on Linux (built from source, installed to `/usr/local/gcc133/`), Xcode Clang on macOS (Xcode 15.2+ for Ventura/Sonoma), Visual Studio 2022 Professional (MSVC) on Windows.
7- **Key dependencies**: Boost 1.86.0 (dynamic linking, includes Boost.Json for JSON handling), PyTorch 2.7.1 (libtorch), libxml2.
8- **Header-only libraries**: Eigen and valijson are header-only and managed by the `3rd_party/` CMake system (pulled automatically during configuration).
9- **Platforms**: Linux x86_64/aarch64, macOS aarch64, Windows x86_64.
10- **Toolchain files**: Auto-selected from `cmake/<os>-<arch>.cmake` or set via `CMAKE_TOOLCHAIN_FILE`.
11
12## Build & Run Commands
13
14Configure and build (default `RelWithDebInfo`):
15```
16cmake -B cmake-build-relwithdebinfo
17cmake --build cmake-build-relwithdebinfo -j$(nproc)
18```
19
20Or via Gradle:
21```
22./gradlew :compile
23```
24
25Set `ML_DEBUG=1` to switch to a Debug build. Compiler caching (sccache/ccache) is auto-detected.
26
27Refer to `CONTRIBUTING.md` and the `build-setup/` directory for full platform-specific setup instructions.
28
29## Project Structure
30
31```
32bin/ # Application executables
33 autodetect/ # Anomaly detection
34 categorize/ # Log categorization
35 controller/ # Process lifecycle controller
36 data_frame_analyzer/ # Data frame analytics (classification, regression)
37 normalize/ # Anomaly score normalization
38 pytorch_inference/ # PyTorch model inference
39lib/ # Shared libraries
40 api/ # JSON/REST API layer
41 core/ # Platform abstractions, I/O, logging, compression
42 maths/ # Mathematical and statistical algorithms
43 analytics/ # Boosted tree, data frame analytics
44 common/ # Bayesian optimisation, distributions, time series
45 time_series/ # Time series decomposition, forecasting
46 model/ # Anomaly detection models
47 seccomp/ # Seccomp/sandbox filters
48 test/ # Shared test utilities (CBoostTestXmlOutput, etc.)
49 ver/ # Version information
50include/ # Public headers (mirrors lib/ structure)
513rd_party/ # Header-only third-party libraries (Eigen, valijson), licenses
52cmake/ # CMake toolchain files, helper functions, test runners
53build-setup/ # Platform-specific build environment instructions
54.buildkite/ # CI pipeline definitions (Buildkite)
55.ci/ # Packer scripts for building Orka macOS CI VMs
56.github/workflows/ # GitHub Actions (automatic backport)
57dev-tools/ # Developer scripts (clang-format, benchmarks)
58```
59
60Libraries must not have circular dependencies. The dependency order is roughly:
61`core` -> `maths` -> `model` -> `api` -> `bin/*`.
62
63## CMake Helper Functions
64
65The build uses custom CMake functions defined in `cmake/functions.cmake`. Use these instead of raw `add_library`/`add_executable` — they handle platform-specific sources, linking, installation, and Windows resource generation automatically.
66
67### Adding a Shared Library
68
69Set `ML_LINK_LIBRARIES` then call `ml_add_library`:
70
71```cmake
72project("ML MyLib")
73
74set(ML_LINK_LIBRARIES
75 ${Boost_LIBRARIES}
76 MlCore
77 )
78
79ml_add_library(MlMyLib SHARED
80 CMyClass.cc
81 CMyOtherClass.cc
82 )
83```
84
85Libraries are named with the `Ml` prefix (e.g. `MlCore`, `MlModel`). The function handles shared library versioning, RPATH, and installation. Use `SHARED` for distributed libraries or `STATIC` for internal-only ones.
86
87For libraries that should not be installed/distributed (e.g. internal helpers), use `ml_add_non_distributed_library` instead.
88
89### Adding an Executable
90
91Set `ML_LINK_LIBRARIES` then call `ml_add_executable`. A `Main.cc` file is included automatically — do not list it in the sources:
92
93```cmake
94project("ML MyApp")
95
96set(ML_LINK_LIBRARIES
97 ${Boost_LIBRARIES}
98 MlCore
99 MlApi
100 MlVer
101 )
102
103ml_add_executable(myapp
104 CCmdLineParser.cc
105 )
106```
107
108The function creates a companion OBJECT library (`MlMyApp`) from the listed sources, which test executables can link against. The executable itself always builds from `Main.cc` plus those objects.
109
110For executables not intended for distribution (dev tools, benchmarks), use `ml_add_non_distributed_executable`.
111
112### Adding a Test Executable
113
114Test executables live in `unittest/` subdirectories. Set `ML_LINK_LIBRARIES` (including `${Boost_LIBRARIES_WITH_UNIT_TEST}` and `MlTest`), then call `ml_add_test_executable`:
115
116```cmake
117project("ML MyLib unit tests")
118
119set(SRCS
120 CMyClassTest.cc
121 CMyOtherClassTest.cc
122 Main.cc
123 )
124
125set(ML_LINK_LIBRARIES
126 ${Boost_LIBRARIES_WITH_UNIT_TEST}
127 MlCore
128 MlMyLib
129 MlTest
130 )
131
132ml_add_test_executable(mylib ${SRCS})
133```
134
135The `_target` argument (e.g. `mylib`) is used to derive the test executable name (`ml_test_mylib`) and the CMake targets `test_mylib` and `test_mylib_individually`.
136
137### Registering Tests with the Build
138
139After creating the test executable, register it in `test/CMakeLists.txt` by adding an `ml_add_test` call alongside the existing entries:
140
141```cmake
142ml_add_test(lib/core/unittest core)
143ml_add_test(lib/maths/common/unittest maths_common)
144ml_add_test(lib/maths/time_series/unittest maths_time_series)
145ml_add_test(lib/maths/analytics/unittest maths_analytics)
146ml_add_test(lib/model/unittest model)
147ml_add_test(lib/api/unittest api)
148ml_add_test(lib/ver/unittest ver)
149ml_add_test(lib/seccomp/unittest seccomp)
150ml_add_test(bin/controller/unittest controller)
151ml_add_test(bin/pytorch_inference/unittest pytorch_inference)
152ml_add_test(lib/mylib/unittest mylib) # <-- new entry
153```
154
155The first argument is the relative path to the unittest directory; the second is the target name matching `ml_add_test_executable`. Note how nested libraries use underscores in the target name (e.g. `lib/maths/common/unittest` -> `maths_common`).
156
157### Platform-Specific Sources
158
159If a source file has a platform-specific variant (e.g. `CMyClass_Linux.cc`, `CMyClass_Darwin.cc`), the `ml_generate_platform_sources` function (called internally by all `ml_add_*` functions) will automatically substitute the platform-specific file at build time. Just list the base filename (`CMyClass.cc`) in your sources.
160
132 more lines are in the file. Read the raw file.
The rest of the repository
elastic/ml-cpp ships 5 other instruction files
CLAUDE.md.cursor/rules/ml-cpp-build-system.mdc.cursor/rules/ml-cpp-coding-conventions.mdc.cursor/rules/ml-cpp-buildkite-ci.mdc.cursor/rules/ml-cpp-ci-analytics.mdc
A row that is not a link is a file this repository ships that this app did not freeze a sheet for. It is listed because the corpus knows it exists, and it is not linked because there is nothing here to open.
This listing
Whoever runs elastic/ml-cpp can claim it
This is yours? Claim this config and we will write to you when the measurement moves. The check is one token placed where only you can place it, and there is no account and no password.