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):

C
CXX → C++
CSharp → C#
CUDA
OBJC → Objective-C
OBJCXX → Objective-C++
Fortran
HIP
ISPC
Swift
ASM
ASM_MASM → Microsoft Macro Assembler (MASM)
ASM_NASM → Netwide Assembler (NASM)
ASM_MARMASM Microsoft ARM Assembler
ASM-ATT
Java (undocumented)
RC (undocumented)

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.03.25"
url = "https://github.com/microsoft/vcpkg/archive/refs/tags/2024.03.25.tar.gz"
packages = ["fmt", "zlib"]

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.

To specify package features you can use the following syntax: imgui[docking-experimental,freetype,sdl2-binding,opengl3-binding].

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.

[fetch-content.gitcontent]
condition = "mycondition"
git = "https://github.com/myuser/gitcontent"
tag = "v0.1"
shallow = false
system = false
subdir = ""

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

[fetch-content.urlcontent]
condition = "mycondition"
url = "https://content-host.com/urlcontent.zip"
# These are equivalent, supported algorithms:
# md5, sha1, sha224, sha256, sha384, sha512, sha3_224, sha3_256, sha3_384, sha3_512
hash = "SHA1 502a4e25b8b209889c99c7fa0732102682c2e4ff"
sha1 = "502a4e25b8b209889c99c7fa0732102682c2e4ff"

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

Targets

[target.mytarget]
condition = "mycondition"
alias = "mytarget::mytarget"
type = "static" # executable, shared (DLL), static, interface, object, library, 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 = [""]
private-compile-definitions = [""]
compile-features = [""]
private-compile-features = [""]
compile-options = [""]
private-compile-options = [""]
include-directories = [""]
private-include-directories = [""]
link-directories = [""]
private-link-directories = [""]
link-libraries = [""]
private-link-libraries = [""]
link-options = [""]
private-link-options = [""]
precompile-headers = [""]
private-precompile-headers = [""]

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"

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 = ""
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.
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