CMake Integration

🚧 Roadmap — WIP. The find_package(codegen), codegen_rule(), and CODEGEN_OUTPUTS helpers below are the design target for the Team-tier cmake_integration feature and are not yet shipped. The supported path today is add_custom_command driving the codegen binary; if you have a Professional or Team licence, --use-workspace reads includes/defines from codexx.workspace.yaml (or compile_commands.json) automatically. This page documents both the current and the planned path; track progress in the codegen changelog.

Today: add_custom_command

Until the package ships, drive codegen from a regular add_custom_command / add_custom_target:

CMakeLists.txt

set(CODEGEN_INPUT  ${CMAKE_SOURCE_DIR}/include/color.hpp)
set(CODEGEN_OUTPUT ${CMAKE_SOURCE_DIR}/include/color.g.cpp)

add_custom_command(
    OUTPUT  ${CODEGEN_OUTPUT}
    COMMAND codegen
        -i ${CODEGEN_INPUT}
        -r ${CMAKE_SOURCE_DIR}/.codegen/rules
        -a ToString
    DEPENDS ${CODEGEN_INPUT}
    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
    COMMENT "codegen: ToString -> ${CODEGEN_OUTPUT}"
    VERBATIM
)

add_custom_target(codegen_color DEPENDS ${CODEGEN_OUTPUT})

target_sources(mylib PRIVATE ${CODEGEN_OUTPUT})
add_dependencies(mylib codegen_color)

By default the engine writes outputs next to the input header, so the OUTPUT path is predictable: <input_stem>.g.cpp for cpp rules, <input_stem>.<ruleName><ext> for other languages. Override with outputDirectory and outputNameTemplate in the rule’s config.

If you use --use-workspace (Professional/Team tiers only), run codegen from the project root so the build-system config is found. Pass --workspace-dir to point at a different directory.

Planned: find_package(codegen) + codegen_rule()

The Team-tier package will install a CMake config module (codegenConfig.cmake) and a codegen_rule() helper that wraps the underlying add_custom_command and exposes the generated files for target_sources:

CMakeLists.txt (planned)

find_package(codegen REQUIRED)

codegen_rule(
    RULE       ToString
    RULES_DIR  ${CMAKE_SOURCE_DIR}/.codegen/rules
    INPUT      ${CMAKE_SOURCE_DIR}/include
    OUTPUT_VAR CODEGEN_TOSTRING_OUTPUTS
)

target_sources(mylib PRIVATE ${CODEGEN_TOSTRING_OUTPUTS})

The helper will parse the rule config, derive OUTPUT paths from outputDirectory / outputNameTemplate, depend on the input headers, and chain the generated files into the target’s source list — eliminating the “forgot to regenerate” CI failure class.

This page will be updated when the package ships.

Key Takeaways

• The find_package(codegen) / codegen_rule() flow is not yet implemented.
• Today, drive codegen with add_custom_command calling the binary directly.
• Default output paths are predictable from the rule config (<stem>.g.cpp for cpp, <stem>.<ruleName><ext> otherwise).
• The packaged helper is a Team-tier feature on the roadmap; this page tracks the target.