`cmake_generate`

cmake_generate configures a CMake project with the managed CMake installation. Generation runs during xx run; pass the returned dependency to cmake_build or other tasks that need the generated build system.

Arguments

Argument	Required	Description
`root`	No	Project-relative directory containing `CMakeLists.txt`. Defaults to `"."`.
`build_dir`	No	Project-relative build directory. Defaults to `"build"`.
`generator`	No	Generator passed with `-G`, such as `"Ninja"`.
`platform`	No	Generator platform passed with `-A`, such as `"x64"` for Visual Studio.
`toolset`	No	Generator toolset passed with `-T`.
`toolchain`	No	Project-relative toolchain file assigned to `CMAKE_TOOLCHAIN_FILE`.
`build_type`	No	Value assigned to `CMAKE_BUILD_TYPE`, such as `"Release"`.
`definitions`	No	String cache variables passed as `-D<name>=<value>`. Defaults to `{}`.
`flags`	No	Additional generation-safe diagnostic or cache-maintenance flags. Defaults to `[]`.
`deps`	No	Dependencies activated before generation, in list order. Defaults to `[]`.

The managed CMake installation is automatic; do not add cmake to deps. The project root, build directory, and toolchain must remain inside the project after symbolic links are resolved. Missing build directories are created. A build directory cannot overlap another task's output.

xx hashes the generation options, selected CMake version, and activated virtual environment. Virtual-environment hashes exclude volatile TMPDIR, TEMP, and TMP values. Generation passes this digest to CMake as the internal XX_CMAKE_GENERATION_HASH cache entry and records successful requests in the build directory. A matching successful request skips explicit generation; the generated build system remains responsible for detecting changed CMake inputs and regenerating itself when built. Requests with flags always run so explicit diagnostics and cache maintenance preserve their per-invocation behavior.

build_type and toolchain are portable conveniences for their matching cache variables. Do not also set CMAKE_BUILD_TYPE or CMAKE_TOOLCHAIN_FILE in definitions when using those arguments.

flags accepts --fresh, -W..., -U..., logging, debug, tracing, and warning-control configure options that do not select another output file. Every item must be a self-contained argument, using --option=value when a value is needed. Mode-changing options and -D, -S, and -B are rejected; use the corresponding function arguments instead.

Example

load("@[email protected]", "cmake_build", "cmake_generate")
load("@[email protected]", "ninja")

configure = cmake_generate(
    generator="Ninja",
    build_type="Release",
    definitions={
        "BUILD_TESTING": "OFF",
    },
    deps=[ninja],
)
cmake_build(configure)

This is equivalent to running CMake with -S ., -B build, the selected generator, and the listed cache definitions.