Link Search Menu Expand Document
cmkr

Reference

This page is a reference for the options in the cmake.toml file. If you think anything is missing or unclear, please edit this page or open an issue.

This is a reference page. Check out the examples and the cmkr topic as well.

CMake configuration 

[cmake]
version = "3.15"
cmkr-include = "cmkr.cmake"

Project configuration 

[project]
name = "myproject"
version = "1.0.0"
description = "Description of the project"
languages = ["C", "CXX"]
msvc-runtime = "" # dynamic (implicit default), static
cmake-before = """
message(STATUS "CMake injected before the project() call")
"""
cmake-after = """
message(STATUS "CMake injected after the project() call")
"""
include-before = ["cmake/before-project.cmake"]
include-after = ["cmake/after-project.cmake"]

Languages

Supported languages are (see enable_language for more information):

After a language is enabled, adding sources files with the corresponding extension to your target will automatically use the appropriate compiler/assembler for it.

Note: It is generally discouraged to disable the C language, unless you are absolutely sure it is not used. Sometimes projects added with fetch-content implicitly require it and the error messages can be extremely confusing.

Conditions

You can specify your own named conditions and use them in any condition field:

[conditions]
ptr64 = "CMAKE_SIZEOF_VOID_P EQUAL 8"
ptr32 = "CMAKE_SIZEOF_VOID_P EQUAL 4"

This will make the ptr64 and ptr32 conditions available with their respective CMake expressions.

Note: condition names can only contain lower-case alphanumeric characters ([0-9a-z]) and dashes (-).

You can also prefix most keys with condition. to represent a conditional:

[target]
type = "executable"
sources = ["src/main.cpp"]
ptr64.sources = ["src/ptr64_only.cpp"]

Instead of a named condition you can also specify a CMake expression in quotes. Instances of $<name> are replaced with the corresponding condition. For example: "CONDITIONS_BUILD_TESTS AND $<linux>" becomes CONDITIONS_BUILD_TESTS AND (CMAKE_SYSTEM_NAME MATCHES "Linux") in the final CMakeLists.txt file.

Predefined conditions

The following conditions are predefined (you can override them if you desire):

[conditions]
windows = "WIN32"
macos = "CMAKE_SYSTEM_NAME MATCHES \"Darwin\""
unix = "UNIX"
bsd = "CMAKE_SYSTEM_NAME MATCHES \"BSD\""
linux = "CMAKE_SYSTEM_NAME MATCHES \"Linux\""
gcc = "CMAKE_CXX_COMPILER_ID STREQUAL \"GNU\" OR CMAKE_C_COMPILER_ID STREQUAL \"GNU\""
msvc = "MSVC"
clang = "(CMAKE_CXX_COMPILER_ID MATCHES \"Clang\" AND NOT CMAKE_CXX_COMPILER_FRONTEND_VARIANT MATCHES \"^MSVC$\") OR (CMAKE_C_COMPILER_ID MATCHES \"Clang\" AND NOT CMAKE_C_COMPILER_FRONTEND_VARIANT MATCHES \"^MSVC$\")"
clang-cl = "(CMAKE_CXX_COMPILER_ID MATCHES \"Clang\" AND CMAKE_CXX_COMPILER_FRONTEND_VARIANT MATCHES \"^MSVC$\") OR (CMAKE_C_COMPILER_ID MATCHES \"Clang\" AND CMAKE_C_COMPILER_FRONTEND_VARIANT MATCHES \"^MSVC$\")"
clang-any = "CMAKE_CXX_COMPILER_ID MATCHES \"Clang\" OR CMAKE_C_COMPILER_ID MATCHES \"Clang\""
root = "CMKR_ROOT_PROJECT"
x64 = "CMAKE_SIZEOF_VOID_P EQUAL 8"
x32 = "CMAKE_SIZEOF_VOID_P EQUAL 4"
android = "ANDROID"
apple = "APPLE"
bsd = "BSD"
cygwin = "CYGWIN"
ios = "IOS"
xcode = "XCODE"
wince = "WINCE"

Subdirectories 

[subdir.mysubdir]
condition = "mycondition"
cmake-before = """
message(STATUS "CMake injected before the add_subdirectory() call"
"""
cmake-after = """
message(STATUS "CMake injected after the add_subdirectory() call")
"""
include-before = ["cmake/before-subdir.cmake"]
include-after = ["cmake/after-subdir.cmake"]

Options 

[options]
MYPROJECT_BUILD_TESTS = false
MYPROJECT_SPECIAL_OPTION = { value = true, help = "Docstring for this option." }
MYPROJECT_BUILD_EXAMPLES = "root"

Options correspond to CMake cache variables that can be used to customize your project at configure-time. You can configure with cmake -DMYPROJECT_BUILD_TESTS=ON to enable the option. Every option automatically gets a corresponding condition. Additionally, a normalized condition is created based on the [project].name (i.e. MYPROJECT_BUILD_TESTS becomes build-tests).

The special value root can be used to set the option to true if the project is compiled as the root project (it will be false if someone is including your project via [fetch-content] or [subdir]).

Variables 

[variables]
MYBOOL = true
MYSTRING = "hello"

Variables emit a set and can be used to configure subprojects and packages.

Vcpkg 

[vcpkg]
version = "2024.11.16"
url = "https://github.com/microsoft/vcpkg/archive/refs/tags/2024.11.16.tar.gz"
packages = ["fmt", "zlib"]
overlay-ports = ["my-ports"]
overlay-triplets = ["my-triplets"]

The vcpkg version will automatically generate the url from the official repository. For a custom registry you can specify your own url (and omit the version). You can browse available packages on vcpkg.io or vcpkg.link.

To specify package features you can use the following syntax: imgui[docking-experimental,freetype,sdl2-binding,opengl3-binding]. To disable the default features you can do: cpp-httplib[core,openssl]

The overlay-ports feature allows you to embed vcpkg ports inside your project, without having to fork the main vcpkg registry or creating a custom registry. You can find more information in the relevant documentation. The overlay-triplets feature allows you to customize triplets and change the default behavior (for example always preferring static libraries on Windows). To specify both in one go you can do [vcpkg].overlay = "vcpkg-overlay".

For a concrete example of all the features, take a look at the vcpkg_template repository.

Packages 

[find-package.mypackage]
condition = "mycondition"
version = "1.0"
required = true
config = true
components = ["mycomponent"]

FetchContent

Note: The [fetch-content] feature is unpolished and will likely change in a future release.

# Include CMake project from git
[fetch-content.gitcontent]
condition = "mycondition"
git = "https://github.com/myuser/gitcontent"
tag = "v0.1"
shallow = false # shallow clone (--depth 1)
system = false
subdir = "" # folder containing CMakeLists.txt
# Set cache variables before FetchContent_MakeAvailable
options = { BUILD_TESTS = false, BUILD_EXAMPLES = false }

# Include a CMake project from a URL
[fetch-content.urlcontent]
condition = "mycondition"
url = "https://content-host.com/urlcontent.zip"
# Other supported algorithms:
# md5, sha1, sha224, sha256, sha384, sha512, sha3_224, sha3_256, sha3_384, sha3_512
hash = "SHA1 502a4e25b8b209889c99c7fa0732102682c2e4ff"
sha1 = "502a4e25b8b209889c99c7fa0732102682c2e4ff"

[fetch-content.svncontent]
condition = "mycondition"
svn = "https://svn-host.com/url"
rev = "svn_rev"

# For many options, you can also use a separate table:
# [fetch-content.bigproject.options]
# BUILD_TESTS = false
# BUILD_EXAMPLES = false
# SOME_STRING_OPTION = "value"
# SOME_LIST_OPTION = ["item1", "item2"]  # becomes "item1;item2"

Table keys that match CMake variable names ([A-Z_]+) will be passed to the FetchContent_Declare command.

The options field allows setting CACHE variables before FetchContent_MakeAvailable is called. This is useful for configuring options on the fetched dependency (e.g., disabling tests). Boolean values become ON/OFF, arrays become semicolon-separated strings.

Targets 

[target.mytarget]
condition = "mycondition"
alias = "mytarget::mytarget"
type = "static" # executable, library, shared (DLL), static, interface, object, custom
headers = ["src/mytarget.h"]
sources = ["src/mytarget.cpp"]
msvc-runtime = "" # dynamic (implicit default), static

# The keys below match the target_xxx CMake commands
# Keys prefixed with private- will get PRIVATE visibility
compile-definitions = [""] # preprocessor define (-DFOO)
private-compile-definitions = [""]
compile-features = [""] # C++ standard version (cxx_std_20)
private-compile-features = [""]
compile-options = [""] # compiler flags
private-compile-options = [""]
include-directories = [""] # include paths/directories
private-include-directories = [""]
link-directories = [""] # library directories
private-link-directories = [""]
link-libraries = [""] # dependencies
private-link-libraries = [""]
link-options = [""] # linker flags
private-link-options = [""]
precompile-headers = [""] # precompiled headers
private-precompile-headers = [""]
dependencies = [""] # add_dependencies(target ...)

# Keys below are for type = "custom" (add_custom_target)
all = false
command = ["${CMAKE_COMMAND}", "-E", "echo", "Hello"] # one command line
commands = [ # multiple command lines
    ["${CMAKE_COMMAND}", "-E", "echo", "First"],
    ["${CMAKE_COMMAND}", "-E", "echo", "Second"],
]
depends = ["generated.txt"] # add_custom_target(... DEPENDS ...)
byproducts = ["generated.txt"]
working-directory = "${CMAKE_CURRENT_BINARY_DIR}"
comment = "Run custom target"
job-pool = "pool"
job-server-aware = true
verbatim = true
uses-terminal = false # incompatible with job-pool when true
command-expand-lists = true

cmake-before = """
message(STATUS "CMake injected before the target")
"""
cmake-after = """
message(STATUS "CMake injected after the target")
"""
include-before = "cmake/target-before.cmake"
include-after = "cmake/target-after.cmake"

# See https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html#properties-on-targets for a list of target properties
[target.mytarget.properties]
CXX_STANDARD = 17
CXX_STANDARD_REQUIRED = true
FOLDER = "MyFolder"

Custom commands

Use [[target.<name>.custom-command]] to map directly to add_custom_command. A custom command can use either the OUTPUT form or the TARGET form:

# OUTPUT form (add_custom_command(OUTPUT ...))
[[target.mytarget.custom-command]]
condition = "mycondition"
outputs = ["generated.cpp"] # relative paths are interpreted from ${CMAKE_CURRENT_BINARY_DIR}
command = [
    "${CMAKE_COMMAND}",
    "-DOUTPUT=${CMAKE_CURRENT_BINARY_DIR}/generated.cpp",
    "-P",
    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/generate.cmake",
]
depends = ["cmake/generate.cmake"]
byproducts = ["generated.hpp"]
main-dependency = "cmake/generate.cmake"
implicit-depends = [["CXX", "src/input.idl"]]
working-directory = "${CMAKE_CURRENT_BINARY_DIR}"
comment = "Generate source"
depfile = "${CMAKE_CURRENT_BINARY_DIR}/generated.d"
job-pool = "pool" # incompatible with uses-terminal when uses-terminal = true
job-server-aware = true
verbatim = true
append = false
uses-terminal = false
codegen = false
command-expand-lists = false
depends-explicit-only = false

# TARGET form (add_custom_command(TARGET ...))
[[target.mytarget.custom-command]]
build-event = "post-build" # pre-build, pre-link, post-build
command = ["${CMAKE_COMMAND}", "-E", "touch", "${CMAKE_CURRENT_BINARY_DIR}/post-build.stamp"]
byproducts = ["${CMAKE_CURRENT_BINARY_DIR}/post-build.stamp"]
working-directory = "${CMAKE_CURRENT_BINARY_DIR}"
comment = "Post-build step"
verbatim = true
command-expand-lists = false
uses-terminal = false

For each custom command entry, exactly one of outputs or build-event is required. Relative outputs/byproducts paths follow CMake and are interpreted from the current binary directory. build-event is only valid for non-interface targets, and pre-link is not supported for type = "custom". In both add_custom_command(OUTPUT ...) and add_custom_target(...), job-pool cannot be combined with uses-terminal = true. When append = true is used with the OUTPUT form, at least one command/commands entry or depends must also be provided.

A table mapping the cmkr features to the relevant CMake construct and the relevant documentation pages:

cmkr CMake construct Description
alias Alias Libraries Create an alias target, used for namespacing or clarity.
sources target_sources Source files (PRIVATE except interface targets).
headers target_sources For readability (and future packaging).
msvc-runtime MSVC_RUNTIME_LIBRARY The CMP0091 policy is set automatically.
compile-definitions target_compile_definitions Adds a macro definition (define, -DMYMACRO=XXX).
compile-features target_compile_features Specifies the C++ standard version (cxx_std_20).
compile-options target_compile_options Adds compiler flags.
include-directories target_include_directories Adds include directories.
link-directories target_link_directories Adds library directories.
link-libraries target_link_libraries Adds library dependencies. Use ::mylib to make sure a target exists.
link-options target_link_options Adds linker flags.
precompile-headers target_precompile_headers Specifies precompiled headers.
dependencies add_dependencies Adds target-level dependencies.
type = "custom" + custom target keys add_custom_target Creates a custom target with command/dependency options.
[[target.<name>.custom-command]] add_custom_command Supports both OUTPUT and TARGET forms.
properties set_target_properties See properties on targets for more information.

The default visibility is as follows:

Type Visibility
executable PRIVATE
library PUBLIC
shared PUBLIC
static PUBLIC
object PUBLIC
interface INTERFACE

Templates

To avoid repeating yourself you can create your own target type and use it in your targets:

[template.example]
condition = "MYPROJECT_BUILD_EXAMPLES"
type = "executable"
link-libraries = ["myproject::mylib"]
add-function = ""
add-arguments = ["myoption"]
pass-sources = false

# Properties from the template are merged with the ones here
[target.myexample]
type = "example"
sources = ["src/myexample.cpp"]

The properties declared on a template are the same as the ones you use for targets. The only exceptions are:

  • add-function: Specifies a custom add function. Projects like pybind11 have their own add_xxx function, which you can specify here.
  • add-arguments: Arguments to pass to the add-function before the list of sources. See cmake_parse_arguments for more details.
  • pass-sources: Pass sources directly to the add function instead of using target_sources.

Tests and installation (unfinished)

Note: The [[test]] and [[install]] are unfinished features and will likely change in a future release.

# You can declare as many as you want like this, but the name has to be unique
[[test]]
condition = "mycondition"
name = "mytest"
command = "$<TARGET_FILE:mytest>"
arguments = ["arg1", "arg2"]
configurations = ["Debug", "Release", "RelWithDebInfo", "MinSizeRelease"]
working-directory = "mytest-dir"

[[install]]
condition = "mycondition"
targets = ["mytarget", "mytest"]
destination = ["bin"]
component = "mycomponent"
files = ["content/my.png"]
dirs = ["include"]
configs = ["Release", "Debug"]
optional = false