CMake Build#

Xmera uses CMake presets to simplify configuration. The presets are defined in src/CMakePresets.json.

Prerequisites#

CMake 3.27+
Ninja build system
vcpkg with the VCPKG_ROOT environment variable set
Python 3 (with development headers)
SWIG

Presets#

Available Configure Presets#
Preset	Description
`base`	Default development build (Debug, Ninja). Builds all module groups.
`ci-test`	Inherits `base` with `CMAKE_BUILD_TYPE=Release`.
`fuzz-smoke-test`	Inherits `ci-test` with fuzz tests enabled.
`fuzz-test`	Inherits `fuzz-smoke-test` with full fuzzing mode.

Cache Variables#

The presets set sensible defaults for the following variables. You can override them with -D on the command line.

CMake Cache Variables#
Variable	Default	Description
`CMAKE_BUILD_TYPE`	`Debug`	Build type (`Debug`, `Release`, `RelWithDebInfo`)
`CMAKE_INSTALL_PREFIX`	`<repo>/dist`	Where `cmake --install` places the Python package
`XMERA_MODULE_ROOTS`	(all groups)	Semicolon-separated list of source directories containing modules
`XMERA_ENABLE_GROUPS`	`simulation;fswAlgorithms;moduleTemplates`	Semicolon-separated list of module group prefixes to build
`XMERA_ENABLE_INTERNAL`	`YES`	Build internal/private modules
`XMERA_ENABLE_FUZZTESTS`	`OFF`	Fetch and build fuzz targets with Google FuzzTest
`URL_SPICE_KERNEL`	(JPL URL)	URL from which to download the `de430.bsp` SPICE kernel

Custom User Presets#

You can create a src/CMakeUserPresets.json file to define your own presets without modifying the project-tracked CMakePresets.json. User presets inherit from project presets and are ignored by git (the file is .gitignore-d by convention).

The file must declare "version": 2 (or higher) and a "configurePresets" array. Each preset can use "inherits" to pull in defaults from a project preset and then override only what it needs.

Example — Release build:

{
  "version": 2,
  "configurePresets": [
    {
      "name": "release",
      "inherits": "base",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release"
      }
    }
  ]
}

cmake --preset release -S src
cmake --build build

Example — Build only simulation modules:

{
  "version": 2,
  "configurePresets": [
    {
      "name": "sim-only",
      "inherits": "base",
      "cacheVariables": {
        "XMERA_ENABLE_GROUPS": "simulation"
      }
    }
  ]
}

Example — Include external modules:

CMake requires all source directories to live under the project source tree. Symlink your external modules folder into src/ first (see Building Custom Modules for the full workflow), then reference the symlink:

{
  "version": 2,
  "configurePresets": [
    {
      "name": "with-external",
      "inherits": "base",
      "cacheVariables": {
        "XMERA_MODULE_ROOTS": "${sourceDir}/fswAlgorithms/;${sourceDir}/simulation/;${sourceDir}/moduleTemplates/;${sourceDir}/externalModules/"
      }
    }
  ]
}

You can list all available presets (project + user) with:

cmake --list-presets -S src

Configure, Build, Install#

All commands are run from the repository root.

Configure using a preset (runs vcpkg and generates build files):
```
cmake --preset base -S src
```
To override a variable, append -D:
```
cmake --preset base -S src -DCMAKE_BUILD_TYPE=Release
```
Build (compiles C++ libraries and generates Python bindings):
```
cmake --build build
```
To build a single target:
```
cmake --build build --target <target-name>
```
Install (copies the Python package into dist/):
```
cmake --install build
```

After installation the dist/xmera directory contains the importable Python package.

Note

If you use CMAKE_INSTALL_MODE=REL_SYMLINK_OR_COPY in your environment, unset it before configure/build steps — it can break vcpkg symlinks. Only set it for the final cmake --install step if you want symlinks for Xmera’s own files.