CMAKE(1)

💖 CMAKE(1) — the CMake Command-Line Reference, explained by your favorite terminal gremlin 💖

okay so. bestie. you opened the CMake manual. it's a lot. it's giving "final boss of build systems" energy and honestly? iconic. let's break it down together, no cap, every single flag intact. 🫶

✨ SYNOPSIS ✨

here's the whole vibe menu of things cmake can do, fr fr:

Generate a Project Buildsystem

cmake [<options>] -B <path-to-build> [-S <path-to-source>]
cmake [<options>] <path-to-source | path-to-existing-build>

Build a Project

cmake --build <dir> [<options>] [-- <build-tool-options>]

Install a Project

cmake --install <dir> [<options>]

Open a Project

cmake --open <dir>

Run a Script

cmake [-D <var>=<value>]... -P <cmake-script-file>

Run a Command-Line Tool

cmake -E <command> [<options>]

Run the Find-Package Tool

cmake --find-package [<options>]

Run a Workflow Preset

cmake --workflow <options>

View Help

cmake --help[-<topic>]

🌸 DESCRIPTION 🌸

so the cmake executable is literally the command-line interface of the cross-platform buildsystem generator CMake. the Synopsis up there is the full list of actions the tool can perform, and each one gets its own section below. 💅

to build a software project with CMake, you Generate a Project Buildsystem. optionally you can then use cmake to Build a Project, Install a Project, or just run the corresponding build tool (e.g. make) directly. cmake can also be used to View Help. 👑

the other actions are meant for use by software developers writing scripts in the CMake language (link: #manual:cmake-language(7)) to support their builds. iykyk.

for graphical user interfaces that may be used in place of cmake, see ccmake (link: #manual:ccmake(1)) and cmake-gui (link: #manual:cmake-gui(1)). for command-line interfaces to the CMake testing and packaging facilities, see ctest (link: #manual:ctest(1)) and cpack (link: #manual:cpack(1)). 🎀

for more information on CMake at large, see also the links at the end of this manual.

🦋 INTRODUCTION TO CMAKE BUILDSYSTEMS 🦋

okay so a buildsystem describes how to build a project's executables and libraries from its source code, using a build tool to automate the whole process. for example, a buildsystem may be a Makefile for use with a command-line make tool, or a project file for an Integrated Development Environment (IDE). 🧚

in order to avoid maintaining multiple such buildsystems, a project may specify its buildsystem abstractly using files written in the CMake language (link: #manual:cmake-language(7)). from these files CMake generates a preferred buildsystem locally for each user through a backend called a generator. ✨

to generate a buildsystem with CMake, the following must be selected:

Source Tree — the top-level directory containing source files provided by the project. the project specifies its buildsystem using files as described in the cmake-language(7) (link: #manual:cmake-language(7)) manual, starting with a top-level file named CMakeLists.txt. these files specify build targets and their dependencies as described in the cmake-buildsystem(7) (link: #manual:cmake-buildsystem(7)) manual.
Build Tree — the top-level directory in which buildsystem files and build output artifacts (e.g. executables and libraries) are to be stored. CMake will write a CMakeCache.txt file to identify the directory as a build tree and store persistent information such as buildsystem configuration options.

to maintain a pristine source tree, perform an out-of-source build by using a separate dedicated build tree. an in-source build in which the build tree is placed in the same directory as the source tree is also supported, but discouraged. 🙈

Generator — this chooses the kind of buildsystem to generate. see the cmake-generators(7) (link: #manual:cmake-generators(7)) manual for documentation of all generators. run cmake --help to see a list of generators available locally. optionally use the -G option below to specify a generator, or simply accept the default CMake chooses for the current platform.

when using one of the Command-Line Build Tool Generators (link: #command-line-build-tool-generators), CMake expects that the environment needed by the compiler toolchain is already configured in the shell. when using one of the IDE Build Tool Generators (link: #ide-build-tool-generators), no particular environment is needed. 🫶

💜 GENERATE A PROJECT BUILDSYSTEM 💜

run CMake with one of the following command signatures to specify the source and build trees and generate a buildsystem:

cmake [<options>] -B <path-to-build> [-S <path-to-source>]

added in version 3.13. ✨

uses <path-to-build> as the build tree and <path-to-source> as the source tree. the specified paths may be absolute or relative to the current working directory. the source tree must contain a CMakeLists.txt file. the build tree will be created automatically if it does not already exist. for example:

$ cmake -S src -B build

cmake [<options>] <path-to-source>

uses the current working directory as the build tree, and <path-to-source> as the source tree. the specified path may be absolute or relative to the current working directory. the source tree must contain a CMakeLists.txt file and must not contain a CMakeCache.txt file because the latter identifies an existing build tree. for example:

$ mkdir build ; cd build
$ cmake ../src

cmake [<options>] <path-to-existing-build>

uses <path-to-existing-build> as the build tree, and loads the path to the source tree from its CMakeCache.txt file, which must have already been generated by a previous run of CMake. the specified path may be absolute or relative to the current working directory. for example:

$ cd build
$ cmake .

in all cases the <options> may be zero or more of the Options below. 💅

the above styles for specifying the source and build trees may be mixed. paths specified with -S or -B are always classified as source or build trees, respectively. paths specified with plain arguments are classified based on their content and the types of paths given earlier. if only one type of path is given, the current working directory (cwd) is used for the other. for example:

cmake -B build → source dir: cwd, build dir: build
cmake -B build src → source dir: src, build dir: build
cmake -B build -S src → source dir: src, build dir: build
cmake src → source dir: src, build dir: cwd
cmake build (existing) → source dir: loaded, build dir: build
cmake -S src → source dir: src, build dir: cwd
cmake -S src build → source dir: src, build dir: build
cmake -S src -B build → source dir: src, build dir: build

changed in version 3.23: CMake warns when multiple source paths are specified. this has never been officially documented or supported, but older versions accidentally accepted multiple source paths and used the last path specified. avoid passing multiple source path arguments. fr fr, don't do it. 💀

after generating a buildsystem one may use the corresponding native build tool to build the project. for example, after using the Unix Makefiles (link: #generator:Unix Makefiles) generator one may run make directly:

$ make
$ make install

alternatively, one may use cmake to Build a Project by automatically choosing and invoking the appropriate native build tool. slay. 🔥

🎀 Options 🎀

-S <path-to-source> — path to root directory of the CMake project to build.
-B <path-to-build> — path to directory which CMake will use as the root of build directory.

if the directory doesn't already exist CMake will make it. ✨

-C <initial-cache> — pre-load a script to populate the cache.

when CMake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. this option may be used to specify a file from which to load cache entries before the first pass through the project's CMake listfiles. the loaded entries take priority over the project's default values. the given file should be a CMake script containing set() (link: #command:set) commands that use the CACHE option, not a cache-format file. 🙈

references to CMAKE_SOURCE_DIR (link: #variable:CMAKE_SOURCE_DIR) and CMAKE_BINARY_DIR (link: #variable:CMAKE_BINARY_DIR) within the script evaluate to the top-level source and build tree. 🫶

-D <var>:<type>=<value>, -D <var>=<value> — create or update a CMake CACHE entry.

when CMake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. this option may be used to specify a setting that takes priority over the project's default value. the option may be repeated for as many CACHE entries as desired. 💅

(more parts incoming, bestie — don't touch that dial 🦋)

So if you do include that :<type> portion, it must be one of the types spelled out in the set() command documentation for its CACHE signature. No making up your own type, bestie, that's not the vibe. 🫶 If you leave the :<type> portion off, the entry gets created with no type — but only if it doesn't already exist with a type. And plot twist: if a command in the project sets the type to PATH or FILEPATH, then your <value> gets converted to an absolute path. Sneaky, but honestly iconic.

You can also drop the whole thing as a single argument: -D<var>:<type>=<value> or -D<var>=<value>. Same energy, fewer keystrokes. ✨

The cache HELPSTRING gets populated like this:

If the cache entry is known to CMake, its help string is set to a one-line description of the variable.
- Added in version 4.4.
Otherwise, its help string gets the generic default: No help, variable specified on the command line.

Okay so this next part is lowkey the most important thing on this whole page, don't skip it: the order of -C and -D arguments is significant. They get carried out in the order they're listed, and the last argument takes precedence over the previous ones. Periodt. 💅

For example, if you specify -DCMAKE_BUILD_TYPE=Debug, followed by a -C argument with a file that calls:

set(CMAKE_BUILD_TYPE "Release" CACHE STRING "" FORCE)

then the -C argument takes precedence, and CMAKE_BUILD_TYPE will be set to Release. But if the -D argument comes after the -C argument, it'll be set to Debug. Order is literally everything. 🦋

And if a set(... CACHE ...) call in the -C file doesn't use FORCE, and a -D argument sets that same variable, the -D argument takes precedence regardless of order, because that's just the nature of non-FORCE set(... CACHE ...) calls. No cap. 😭

-U <globbing_expr> — remove matching entries from the CMake CACHE.

This one's for removing one or more variables from the CMakeCache.txt file. Globbing expressions using * and ? are supported, and you can repeat the option for as many CACHE entries as you want. 🙈

Use with care — you can make your CMakeCache.txt non-working. That's not a vibe, that's a cautionary tale. 💀

-G <generator-name> — specify a build system generator.

CMake may support multiple native build systems on certain platforms. A generator is the thing responsible for generating a particular build system. The possible generator names are all listed in the cmake-generators(7) manual. 👑

If you don't specify one, CMake checks the CMAKE_GENERATOR environment variable, and otherwise falls back to a builtin default selection. It's giving "I'll figure it out myself." 🌸

-T <toolset-spec> — toolset specification for the generator, if supported.

Some CMake generators support a toolset specification so you can tell the native build system how to choose a compiler. See the CMAKE_GENERATOR_TOOLSET variable for the details. 🔥

-A <platform-name> — specify platform name if supported by the generator.

Some CMake generators support a platform name, which gets handed to the native build system to choose a compiler or SDK. See the CMAKE_GENERATOR_PLATFORM variable for the deets. 💜

--toolchain <path-to-file> — Added in version 3.21.

Specifies the cross compiling toolchain file. This is equivalent to setting the CMAKE_TOOLCHAIN_FILE variable. Relative paths are interpreted as relative to the build directory, and if not found, relative to the source directory. It's giving "I'll look in two places, bestie." 🎀

--install-prefix <directory> — Added in version 3.21.

Specifies the installation directory, used by the CMAKE_INSTALL_PREFIX variable. Must be an absolute path. No exceptions, no shortcuts. ⭐

--project-file <project-file-name> — Added in version 4.0.

Specifies an alternate project file name. 🦋

This determines the top-level file processed by CMake when configuring a project, and the file processed by add_subdirectory().

By default, this is CMakeLists.txt. If you set it to anything else, CMakeLists.txt will be used as a fallback whenever the specified file cannot be found within a project subdirectory. Cute backup plan honestly.

Note: this feature is intended for temporary use by developers during an incremental transition, and not for publication of a final product. CMake will always emit a warning when the project file is anything other than CMakeLists.txt. So like... it's a phase, not a personality. 😭

-W<category> — promote the specified diagnostic category (and any children) to at least WARN severity.

Heads up: this has no effect on diagnostics that are already set to a higher severity. ✨

See the cmake-diagnostics(7) manual for the list of accepted values for <category>. 📋

-Wno-<category> — disable (ignore) all diagnostics of the specified category, including any child categories. Out of sight, out of mind. 🙈
-Werror=<category> — promote the specified diagnostic category (and any children) to at least SEND_ERROR severity.

Same caveat as before: this has no effect on diagnostics already set to a higher severity. 🔥

-Wno-error=<category> — demote the specified diagnostic category (and any children) to at most WARN severity.

And again: no effect on diagnostics already set to a lower severity. Balanced, as all things should be. ⚖️

-Wdev, -Wno-dev — deprecated since version 4.4.

These are compatibility synonyms for -Wauthor / -Wno-author. They're still here, but like... they're on their way out. 👋

--fresh — Added in version 3.24.

Perform a fresh configuration of the build tree. This removes any existing CMakeCache.txt file and associated CMakeFiles/ directory, and recreates them from scratch. It's giving factory reset, bestie. 🔄

Changed in version 3.30: for dependencies previously populated by FetchContent with the NEW setting for policy CMP0168, their stamp and script files from any previous run will be removed. The download, update, and patch steps will therefore be forced to re-execute. No skipping, no caching your way out of it. 💀

-L[A][H] — list non-advanced cached variables.

List CACHE variables will run CMake and list all the variables from the CMake CACHE that are not marked as INTERNAL or ADVANCED. This effectively displays your current CMake settings, which you can then go change with the -D option. Changing some of those variables may result in more variables being created — yes, they multiply, sorry. 🍓

If A is specified, it'll also display advanced variables. If H is specified, it'll also display help for each variable. 🎀

-LR[A][H] <regex> — Added in version 3.31.

Show specific non-advanced cached variables. 💅

Shows non-INTERNAL nor ADVANCED variables from the CMake CACHE that match the given regex. If A is specified, it'll also show advanced variables. If H is specified, it'll also display help for each variable. Same energy, but filtered, and honestly the filtering is the main character here. 👑

-N — view mode only.

Only load the cache. Do not actually run configure and generate steps. Just looking, not touching. 👀

--graphviz=<file> — generate Graphviz of dependencies.

This option generates a graphviz input file containing all the library and executable dependencies in the project — it shows the dependencies between the targets in a project, as well as external libraries which are linked against. 🌈

When you run CMake with the --graphviz=foo.dot option, it produces:

a foo.dot file, showing all dependencies in the project
a foo.dot.<target> file for each target, showing on which other targets it depends
a foo.dot.<target>.dependers file for each target, showing which other targets depend on it

Those .dot files can be converted to images using the dot command from the Graphviz package:

dot -Tpng -o foo.png foo.dot

Added in version 3.10: the different dependency types PUBLIC, INTERFACE and PRIVATE are represented as solid, dashed and dotted edges. Aesthetic and informative. 🦋

Variables specific to the Graphviz support

The resulting graphs can be huge — like, unhinged huge. 😭 The look and content of the generated graphs can be controlled using the file CMakeGraphVizOptions.cmake. This file is first searched in CMAKE_BINARY_DIR, and then in CMAKE_SOURCE_DIR. If found, the variables set in it are used to adjust options for the generated Graphviz files. 🌸

GRAPHVIZ_GRAPH_NAME — the graph name.
- Mandatory: NO
- Default: value of CMAKE_PROJECT_NAME
GRAPHVIZ_GRAPH_HEADER — the header written at the top of the Graphviz files.
- Mandatory: NO
- Default: "node [ fontsize = "12" ];
GRAPHVIZ_NODE_PREFIX — the prefix for each node in the Graphviz files.
- Mandatory: NO
- Default: "node"
GRAPHVIZ_EXECUTABLES — set to FALSE to exclude executables from the generated graphs.
- Mandatory: NO
- Default: TRUE
GRAPHVIZ_STATIC_LIBS — set to FALSE to exclude static libraries from the generated graphs.
- Mandatory: NO
- Default: TRUE
GRAPHVIZ_SHARED_LIBS — set to FALSE to exclude shared libraries from the generated graphs.
- Mandatory: NO
- Default: TRUE
GRAPHVIZ_MODULE_LIBS — set to FALSE to exclude module libraries from the generated graphs.
- Mandatory: NO
- Default: TRUE
GRAPHVIZ_INTERFACE_LIBS — set to FALSE to exclude interface libraries from the generated graphs.
- Mandatory: NO
- Default: TRUE
GRAPHVIZ_OBJECT_LIBS — set to FALSE to exclude object libraries from the generated graphs.
- Mandatory: NO
- Default: TRUE
GRAPHVIZ_UNKNOWN_LIBS — set to FALSE to exclude unknown libraries from the generated graphs.
- Mandatory: NO
Default: TRUE

🦋 `GRAPHVIZ_EXTERNAL_LIBS`

Set to FALSE to exclude external libraries from the generated graphs.

Mandatory: NO
Default: TRUE

🎀 `GRAPHVIZ_CUSTOM_TARGETS`

Set to TRUE to include custom targets in the generated graphs.

Mandatory: NO
Default: FALSE

🌸 `GRAPHVIZ_IGNORE_TARGETS`

A list of regular expressions for names of targets to exclude from the generated graphs.

Mandatory: NO
Default: empty

✨ `GRAPHVIZ_GENERATE_PER_TARGET`

Set to FALSE to not generate per-target graphs foo.dot.<target>.

Mandatory: NO
Default: TRUE

💅 `GRAPHVIZ_GENERATE_DEPENDERS`

Set to FALSE to not generate depender graphs foo.dot.<target>.dependers.

Mandatory: NO
Default: TRUE

--system-information [file] — dump info about this system, bestie.

Dump a wide range of information about the current system. If you run it from the top of a binary tree for a CMake project, it'll dump additional info too, like the cache, log files, etc. 💖

--print-config-dir — print the CMake config directory for user-wide FileAPI queries. 🗂️

Added in version 3.31.

See CMAKE_CONFIG_DIR for more details.

--log-level=<level> — set the log level, periodt. 🔥

Added in version 3.16.

The message() command will only output messages of the specified log level or higher. The valid log levels are ERROR, WARNING, NOTICE, STATUS (default), VERBOSE, DEBUG, or TRACE.

To make a log level persist between CMake runs, set CMAKE_MESSAGE_LOG_LEVEL as a cache variable instead. If both the command line option and the variable are given, the command line option takes precedence — CLI stays winning, no cap.

For backward compatibility reasons, --loglevel is also accepted as a synonym for this option.

Added in version 3.25: See the cmake_language(GET_MESSAGE_LOG_LEVEL) command for a way to query the current message logging level.

--log-context — make the message() command output context attached to each message. 🫶

This option turns on showing context for the current CMake run only. To make showing the context persistent for all subsequent CMake runs, set CMAKE_MESSAGE_CONTEXT_SHOW as a cache variable instead. When this command line option is given, CMAKE_MESSAGE_CONTEXT_SHOW is ignored.

--sarif-output=<path> — enable logging of diagnostic messages produced by CMake in the SARIF format. 🌈

Added in version 4.0.

Write diagnostic messages to a SARIF file at the path specified. Projects can also set CMAKE_EXPORT_SARIF to ON to enable this feature for a build tree.

--debug-trycompile — do not delete the files and directories created for try_compile() / try_run() calls. Iconic for debugging failed checks. 🧚

Heads up though: some uses of try_compile() may use the same build tree, which will limit the usefulness of this option if a project executes more than one try_compile(). For example, such uses may change results as artifacts from a previous try-compile may cause a different test to either pass or fail incorrectly. This option is best used only when debugging. (With respect to the preceding, the try_run() command is effectively a try_compile(). Any combination of the two is subject to the potential issues described.)

Added in version 3.25: When this option is enabled, every try-compile check prints a log message reporting the directory in which the check is performed.

--debug-output — put cmake in a debug mode. 🐛

Print extra information during the cmake run, like stack traces with message(SEND_ERROR) calls.

--debug-find — put cmake find commands in a debug mode. 🔍

Added in version 3.17.

Print extra find call information during the cmake run to standard error. Output is designed for human consumption and not for parsing. See also the CMAKE_FIND_DEBUG_MODE variable for debugging a more local part of the project.

--debug-find-pkg=<pkg>[,...] — put cmake find commands in a debug mode when running under calls to find_package(<pkg>), where <pkg> is an entry in the given comma-separated list of case-sensitive package names. 🎯

Added in version 3.23.

Like --debug-find, but limiting scope to the specified packages.

--debug-find-var=<var>[,...] — put cmake find commands in a debug mode when called with <var> as the result variable, where <var> is an entry in the given comma-separated list. 🫧

Added in version 3.23.

Like --debug-find, but limiting scope to the specified variable names.

--trace — put cmake in trace mode. 👑

Print a trace of all calls made and from where.

--trace-expand — put cmake in trace mode, but make it the expanded version. 💫

Like --trace, but with variables expanded.

--trace-format=<format> — put cmake in trace mode and set the trace output format. 🎨

Added in version 3.17.

<format> can be one of the following values:

human — prints each trace line in a human-readable format. This is the default format.
json-v1 — prints each line as a separate JSON document. Each document is separated by a newline (\n). It is guaranteed that no newline characters will be present inside a JSON document.

JSON trace format:

{
  "file": "/full/path/to/the/CMake/file.txt",
  "line": 0,
  "cmd": "add_executable",
  "args": ["foo", "bar"],
  "time": 1579512535.9687231,
  "frame": 2,
  "global_frame": 4
}

The members are:

file — the full path to the CMake source file where the function was called.
line — the line in file where the function call begins.
line_end — if the function call spans multiple lines, this field will be set to the line where the function call ends. If the function call spans a single line, this field will be unset. This field was added in minor version 2 of the json-v1 format.
defer — optional member that is present when the function call was deferred by cmake_language(DEFER). If present, its value is a string containing the deferred call <id>.
cmd — the name of the function that was called.
args — a string list of all function parameters.
time — timestamp (seconds since epoch) of the function call.
frame — stack frame depth of the function that was called, within the context of the CMakeLists.txt being processed currently.
global_frame — stack frame depth of the function that was called, tracked globally across all CMakeLists.txt files involved in the trace. This field was added in minor version 2 of the json-v1 format.

Additionally, the first JSON document outputted contains the version key for the current major and minor version of the JSON version format:

{
  "version": {
    "major": 1,
    "minor": 2
  }
}

The members are:

version — indicates the version of the JSON format. The version has a major and minor components following semantic version conventions.

--trace-source=<file> — put cmake in trace mode, but only output lines of a specified file. 🌟

Multiple options are allowed.

--trace-redirect=<file> — put cmake in trace mode and redirect trace output to a file instead of stderr. 📝
--warn-uninitialized — compatibility synonym for -Wuninitialized.

Deprecated since version 4.4.

--warn-unused-vars — literally does nothing. 💀

Deprecated since version 3.19.

In CMake versions 3.2 and below this enabled warnings about unused variables. In CMake versions 3.3 through 3.18 the option was broken. In CMake 3.19 and above the option has been removed.

--no-warn-unused-cli — compatibility synonym for -Wno-unused-cli.

Deprecated since version 4.4.

--check-system-vars — find problems with variable usage in system files. 🕵️

Normally, unused and uninitialized variables are searched for only in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells CMake to warn about other files as well.

--compile-no-warning-as-error — added in version 3.24. 🍓

Ignore target property COMPILE_WARNING_AS_ERROR and variable CMAKE_COMPILE_WARNING_AS_ERROR, preventing warnings from being treated as errors on compile. 💅

--link-no-warning-as-error — Added in version 4.0. Ignore target property LINK_WARNING_AS_ERROR and variable CMAKE_LINK_WARNING_AS_ERROR, preventing warnings from being treated as errors on link.
--profiling-output=<path> — Added in version 3.18. Used in conjunction with --profiling-format to output to a given path. 🎀
--profiling-format=<file> — Turn on the output of profiling data of CMake script in the given format. This can aid performance analysis of CMake scripts executed. Third party applications should be used to process the output into human readable format. Currently supported values are: google-trace Outputs in Google Trace Format, which can be parsed by the <about:tracing> tab of Google Chrome or using a plugin for a tool like Trace Compass. ✨
--preset <preset>, --preset=<preset> — Reads a preset from CMake presets files. CMakePresets.json and CMakeUserPresets.json are the default files, which must be located in the same directory as the top level CMakeLists.txt file. A file can also be specified with --presets-file.

The preset may specify the generator, the build directory, a list of variables, and other arguments to pass to CMake. 👑

The CMake GUI also recognizes and supports CMakePresets.json and CMakeUserPresets.json files. For full details on these files, see cmake-presets(7). 🦋

The presets are read before all other command line options, although the -S option can be used to specify the source directory containing the CMakePresets.json and CMakeUserPresets.json files. If neither -S nor --presets-file are given, the current working directory is assumed to be the top level source directory and must contain CMakePresets.json and/or CMakeUserPresets.json. 😭

The options specified by the chosen preset (variables, generator, etc.) can all be overridden by manually specifying them on the command line. For example, if the preset sets a variable called MYVAR to 1, but the user sets it to 2 with a -D argument, the value 2 is preferred. periodt.

Added in version 3.21: The -B option may optionally be specified with a different binary directory than the one specified by the binaryDir field.

Changed in version 4.4: If --presets-file is specified, neither of CMakePresets.json nor CMakeUserPresets.json are required to be present. In prior versions, the presence of these files in the top-level source directory (whether via -S or the current working directory) was strictly required. glow-up fr fr ✨

--presets-file <file>, --presets-file=<file> — Added in version 4.4. Reads presets from the given <file>. The specified path may be absolute or relative to the current working directory. If --presets-file is given, presets defined in CMakePresets.json and CMakeUserPresets.json will be ignored. 💖
--list-presets[=<type>] — Lists the available presets of the specified <type>. Valid values for <type> are configure, build, test, package, or all. If <type> is omitted, configure is assumed. 🌸

Changed in version 4.4: If --presets-file is specified, the presets defined in the given <file> will be listed. Otherwise, the top-level source directory (whether via -S or the current working directory) must contain CMakePresets.json and/or CMakeUserPresets.json. In prior versions, the latter was strictly required.

--debugger — Enables interactive debugging of the CMake language. CMake exposes a debugging interface on the pipe named by --debugger-pipe that conforms to the Debug Adapter Protocol specification with the following modifications. 💀

The initialize response includes an additional field named cmakeVersion which specifies the version of CMake being debugged.

Debugger initialize response

   {
     "cmakeVersion": {
       "major": 3,
       "minor": 27,
       "patch": 0,
       "full": "3.27.0"
     }
   }

The members are:

major — An integer specifying the major version number.
minor — An integer specifying the minor version number.
patch — An integer specifying the patch version number.
full — A string specifying the full CMake version. 🧚

--debugger-pipe <pipe name>, --debugger-pipe=<pipe name> — Name of the pipe (on Windows) or domain socket (on Unix) to use for debugger communication. 🫶
--debugger-dap-log <log path>, --debugger-dap-log=<log path> — Logs all debugger communication to the specified file. 📝

🔨 BUILD A PROJECT 🔨

So like, CMake also gives you a command-line signature to build an already-generated project binary tree — no cap, you don't generate anything new here, you just build what's already there:

cmake --build <dir>                     [<options>] [-- <build-tool-options>]
cmake --build [<dir>] --preset <preset> [<options>] [-- <build-tool-options>]

This abstracts a native build tool's command-line interface with the following options, bestie: 👇

--build <dir> — Project binary directory to be built. This is required (unless a preset is specified) and must be first. like, first-first. no cutting the line. 🙈
--preset <preset>, --preset=<preset> — Use a build preset to specify build options. The project binary directory is inferred from the configurePreset key unless a directory is specified after --build.

Added in version 4.3: cmake --build now supports specifying a build directory and preset together. 🎀

Changed in version 4.4: cmake --build <dir> --preset no longer needs to be called from the directory containing CMakePresets.json or CMakeUserPresets.json. If --presets-file is specified, CMake will use that file; otherwise, the presets file(s) can be inferred from the current build directory's CMakeCache.txt. ✨

--presets-file <file>, --presets-file=<file> — Added in version 4.4. Reads presets from the given <file>. The specified path may be absolute or relative to the current working directory. If --presets-file is given, presets defined in CMakePresets.json and CMakeUserPresets.json will be ignored.
--list-presets — Lists the available build presets. 🌈

Changed in version 4.4: cmake --build <dir> --list-presets no longer needs to be called from the directory containing CMakePresets.json or CMakeUserPresets.json. If --presets-file is specified, only presets defined in the given <file> will be listed; otherwise, the presets file(s) are inferred from the current build directory's CMakeCache.txt.

-j [<jobs>], --parallel [<jobs>] — Added in version 3.12. The maximum number of concurrent processes to use when building. If <jobs> is omitted the native build tool's default number is used. 🔥

The CMAKE_BUILD_PARALLEL_LEVEL environment variable, if set, specifies a default parallel level when this option is not given.

Some native build tools always build in parallel. The use of <jobs> value of 1 can be used to limit to a single job. one. singular. 🫠

-t <tgt>..., --target <tgt>... — Build <tgt> instead of the default target. Multiple targets may be given, separated by spaces. 👑
--config <cfg> — For multi-configuration tools, choose configuration <cfg>.
--clean-first — Build target clean first, then build. (To clean only, use --target clean.) 🧼
--resolve-package-references=<value> — Added in version 3.23. Resolve remote package references from external package managers (e.g. NuGet) before build. When <value> is set to on (default), packages will be restored before building a target. When <value> is set to only, the packages will be restored, but no build will be performed. When <value> is set to off, no packages will be restored. 💅

If the target does not define any package references, this option does nothing.

This setting can be specified in a build preset (using resolvePackageReferences). The preset setting will be ignored, if this command line option is specified.

If no command line parameter or preset option are provided, an environment-specific cache variable will be evaluated to decide, if package restoration should be performed.

When using Visual Studio Generators, package references are defined using the VS_PACKAGE_REFERENCES property. Package references are restored using NuGet. It can be disabled by setting the CMAKE_VS_NUGET_PACKAGE_RESTORE variable to OFF. 😮‍💨

--use-stderr — Ignored. Behavior is default in CMake >= 3.0. literally a ghost 👻
-v, --verbose — Enable verbose output — if supported — including the build commands to be executed. 🗣️

This option can be omitted if VERBOSE environment variable or CMAKE_VERBOSE_MAKEFILE cached variable is set.

-- — Pass remaining options to the native tool. 🫶

Run cmake --build with no options for quick help.

🛠️ Generator-Specific Build Tool Behavior 🛠️

cmake --build has special behavior with some generators:

Xcode — Added in version 4.1: If a third-party tool has written a .xcworkspace next to the CMake-generated .xcodeproj, cmake --build drives the build through the workspace instead. iconic behavior honestly 💖

🛠️ INSTALL A PROJECT 💅

okay bestie, this is the install era: your already-built project finally gets placed where it belongs 😌 CMake gives you a command-line signature to install an already-generated project binary tree:

cmake --install <dir> [<options>]

Use this after building a project when you wanna run installation without using the generated build system or the native build tool. The options are:

--install <dir> — project binary directory to install. This one is required and must be first, no cap.
--config <cfg> — for multi-configuration generators, choose configuration <cfg>.
--component <comp> — component-based install. Only install component <comp>.

Added in version 4.4: supports installing more than one component:

--component <compA> <compB>
--component <compA> --component <compB>

--default-directory-permissions <permissions> — default directory install permissions. The permissions format is <u=rwx,g=rx,o=rx>.
--prefix <prefix> — specifies an alternative installation prefix, temporarily replacing the value of the CMAKE_INSTALL_PREFIX variable at the installation phase.

The main purpose of this option is to let installation happen in an arbitrary location. It's commonly used in certain installation and packaging workflows, and it's analogous to selecting the installation directory during the installation phase — like on Windows, where a user may choose the destination folder for the project.

Note: when the project is using the GNUInstallDirs module, some special cases are evaluated based on the value of CMAKE_INSTALL_PREFIX during the configuration phase. Those results persist even if an alternative prefix is used during installation. So yeah — the config-phase tea does not get re-steeped 💀

--strip — strip before installing.
-v, --verbose — enable verbose output. This option can be omitted if the VERBOSE environment variable is set.
-j <jobs>, --parallel <jobs> — Added in version 3.31. Install in parallel using the given number of jobs. Only available if INSTALL_PARALLEL is enabled. The CMAKE_INSTALL_PARALLEL_LEVEL environment variable specifies a default parallel level when this option is not provided.

Run cmake --install with no options for quick help ✨

🚪 OPEN A PROJECT 🌈

cmake --open <dir>

Open the generated project in the associated application. This is only supported by some generators — some generators ate, some did not 🙈

📜 RUN A SCRIPT 🧚

cmake [-D <var>=<value>]... -P <cmake-script-file> [-- <unparsed-options>...]

-D <var>=<value> — define a variable for script mode.
-P <cmake-script-file> — process the given cmake file as a script written in the CMake language. No configure or generate step is performed, and the cache is not modified. If variables are defined using -D, this must be done before the -P argument.

Any options after -- are not parsed by CMake, but they are still included in the set of CMAKE_ARGV<n> variables passed to the script — including the -- itself. iykyk 👑

💻 RUN A COMMAND-LINE TOOL 🔥

CMake provides builtin command-line tools through this signature:

cmake -E <command> [<options>]

-E [help] — run cmake -E or cmake -E help for a summary of commands.

Available commands are:

🧰 `bin2c [<options>...] [--] [<input-file> [<output-file>]]`

Added in version 4.3. Convert a binary file to a C array. If the input file is unspecified or -, read from standard input instead of a file. If the output file is unspecified or -, write to standard output instead of a file.

By default, this prints only the bytes. Enclosing text can be added with the --template-file argument. You can also #include the bytes from another file, acting as a drop-in replacement for the #embed directive from C23 and C++26:

unsigned char my_bytes[] = {
/* #embed "bin2c_input.bin" */
#include "bin2c_output.c.txt"
};

--signed — print the bytes as signed integers rather than unsigned.
--decimal — print the bytes as decimal rather than hexadecimal.
--trailing-comma — append a trailing comma after the last byte (not included by default.)
--template-file <template-file> — format from a template file. The template file contains placeholders for the array and optionally the length (which will be a non-negative decimal integer). Such placeholders are enclosed in @ at the beginning and end of the placeholder. This functionality is similar to configure_file() called with the @ONLY argument, but only the array and length placeholders will be replaced, and any other placeholders will be left as-is.

An example of a potential template file:

unsigned char my_bytes[] = {@array@};

size_t length = @length@;

The array placeholder may occur at most once in the template file. The length placeholder may occur zero or more times after the array placeholder, but not before it.

Note that the length is the number of elements printed, and may not match the sizeof the resulting array if a type other than unsigned char is used. read that twice, bestie 👀

--template-array-placeholder <placeholder-name> — specify a name for the array placeholder in the template file. Set to array by default.
--template-length-placeholder <placeholder-name> — specify a name for the length placeholder in the template file. Set to length by default.

🧰 `capabilities`

Added in version 3.7. Report cmake capabilities in JSON format. The output is a JSON object with the following keys:

version — a JSON object with version information. Keys are:
- string — the full version string as displayed by cmake --version.
- major — the major version number in integer form.
- minor — the minor version number in integer form.
- patch — the patch level in integer form.
- suffix — the cmake version suffix string.
- isDirty — a bool that is set if the cmake build is from a dirty tree.
generators — a list available generators. Each generator is a JSON object with the following keys:
- name — a string containing the name of the generator.
- toolsetSupport — true if the generator supports toolsets and false otherwise.
- platformSupport — true if the generator supports platforms and false otherwise.
- supportedPlatforms — Added in version 3.21. Optional member that may be present when the generator supports platform specification via CMAKE_GENERATOR_PLATFORM (-A ...). The value is a list of platforms known to be supported.
- extraGenerators — a list of strings with all the Extra Generators compatible with the generator.
fileApi — optional member that is present when the cmake-file-api(7) is available. The value is a JSON object with one member:
- requests — a JSON array containing zero or more supported file-api requests. Each request is a JSON object with members:
  - kind — specifies one of the supported Object Kinds.
  - version — a JSON array whose elements are each a JSON object containing major and minor members specifying non-negative integer version components.
serverMode — true if cmake supports server-mode and false otherwise. Always false since CMake 3.20.
tls — Added in version 3.25. true if TLS support is enabled and false otherwise.
debugger — Added in version 3.27. true if the --debugger mode is supported and false otherwise.

🧰 `cat [--] <files>...`

Added in version 3.18. Concatenate files and print on the standard output.

-- — Added in version 3.24. Added support for the double dash argument --. This basic implementation of cat does not support any options, so using an option starting with - will result in an error. Use -- to indicate the end of options, in case a file starts with -.

Added in version 3.29: cat can now print the standard input by passing the - argument.

Added in version 4.4: cat will print the standard input when no arguments are passed.

🧰 `chdir <dir> <cmd> [<arg>...]`

Change the current working directory and run a command.

🧰 `compare_files [--ignore-eol] <file1> <file2>`

Check if <file1> is same as <file2>. If files are the same, then returns 0, if not it returns 1. In case of invalid arguments, it returns 2.

--ignore-eol — Added in version 3.14. The option implies line-wise comparison and ignores LF/CRLF differences.

🧰 `copy <file>... <destination>,`

the source snippet cuts off here mid-command, so I'm not inventing behaviour — that trailing comma is literally where the page stops. 🫶

📁 `copy`

copy -t <destination> <file>...

Copies your files over to <destination>, which can be either a file or a directory. Here's the vibe check though: if you're passing multiple files, or if you used -t, then <destination> must be a directory and it must already exist — no silent auto-creation, bestie. If you didn't use -t, the last argument is just assumed to be the <destination>.

Wildcards? Nope, not supported. 💀

copy does follow symlinks — meaning it does not copy the symlink itself, it copies the files or directories the link points to.

Added in version 3.5: support for multiple input files.
Added in version 3.26: support for the -t argument.

🌸 `copy_directory`

copy_directory <dir>... <destination>,
copy_directory -t <destination> <dir>...

Copies the content of the <dir>... directories into a <destination> directory. Unlike copy, if <destination> doesn't exist, it will be created for you 🫶. No -t? Then the last argument is assumed to be the <destination>. And yes, copy_directory follows symlinks.

Added in version 3.15: the command now fails when the source directory doesn't exist. Previously it "succeeded" by creating an empty destination directory (iconic flop behaviour, honestly).
Added in version 3.5: support for multiple input directories.
Added in version 4.4: support for the -t argument.

🦋 `copy_directory_if_different`

copy_directory_if_different <dir>... <destination>,
copy_directory_if_different -t <destination> <dir>...

Added in version 3.26.

Only copies the changed content of the <dir>... directories over to <destination>. If <destination> doesn't exist, it gets created. No -t? Last argument = <destination>, as always.

copy_directory_if_different follows symlinks, and it fails when the source directory doesn't exist.

Added in version 4.4: support for the -t argument.

🎀 `copy_directory_if_newer`

copy_directory_if_newer <dir>... <destination>,
copy_directory_if_newer -t <destination> <dir>...

Added in version 4.2.

Copies the content of the <dir>... directories to <destination> if the source files are newer than the destination files (based on file timestamps ⏰). <destination> gets created if it's missing. No -t? Last argument is the <destination>.

copy_directory_if_newer follows symlinks, and it fails when the source directory doesn't exist. She's faster than copy_directory_if_different because she only compares timestamps instead of actually reading file contents. Efficiency queen 👑.

Added in version 4.4: support for the -t argument.

💅 `copy_if_different`

copy_if_different <file>... <destination>,
copy_if_different -t <destination> <file>...

Copies files to <destination> (file or directory) if they have changed. Multiple files, or -t? Then <destination> must be a directory and it must exist. copy_if_different follows symlinks.

Added in version 3.5: support for multiple input files.
Added in version 4.4: support for the -t argument.

✨ `copy_if_newer`

copy_if_newer <file>... <destination>,
copy_if_newer -t <destination> <file>...

Added in version 4.2.

Copies files to <destination> (file or directory) if the source files are newer than the destination files (based on file timestamps). Multiple files, or -t? <destination> must be a directory and it must exist. copy_if_newer follows symlinks, and it's faster than copy_if_different since it only checks timestamps instead of comparing contents.

Added in version 4.4: support for the -t argument.

🔗 `create_symlink`

create_symlink <old> <new>

Creates a symbolic link <new> naming <old>. Baby symlink, welcome to the world 🍼.

Added in version 3.13: support for creating symlinks on Windows.

⚠️ The path to where the <new> symbolic link will be created has to exist beforehand. No parent folder, no symlink, periodt.

🧲 `create_hardlink`

create_hardlink <old> <new>

Added in version 3.19.

Creates a hard link <new> naming <old>.

⚠️ Two things have to exist beforehand: the path where the <new> hard link will be created, and <old> itself. Both. Not one. Both 😭.

🗣️ `echo`

echo [<string>...]

Displays arguments as text. That's it, that's the whole command, and honestly? She ate.

🤫 `echo_append`

echo_append [<string>...]

Displays arguments as text but with no new line. Same energy as echo, just quieter, no dramatic line break at the end 🙈.

🌈 `env`

env [<options>] [--] <command> [<arg>...]

Added in version 3.1.

Runs a command in a modified environment. The options are:

NAME=VALUE — replaces the current value of NAME with VALUE.
--unset=NAME — unsets the current value of NAME.
--modify ENVIRONMENT_MODIFICATION — Added in version 3.25. Applies a single ENVIRONMENT_MODIFICATION operation to the modified environment.
-- — Added in version 3.24. Support for the double dash argument --. Use -- to stop interpreting options/environment variables and treat the next argument as the command, even if it starts with - or contains an =.

💡 Heads up bestie: NAME=VALUE and --unset=NAME are equivalent to --modify NAME=set:VALUE and --modify NAME=unset:, respectively. But note that --modify NAME=reset: resets NAME to the value it had when cmake launched (or unsets it) — not to the most recent NAME=VALUE option. The plot twist matters, okay? 😭

🌍 `environment`

environment

Displays the current environment variables. All of them. The whole gossip folder.

💀 `false`

false

Added in version 3.16.

Does absolutely nothing, with an exit code of 1. She's not lazy, she's intentional. Main character of "no" 💅.

📂 `make_directory`

make_directory <dir>...

Creates the <dir> directories. If necessary, it creates parent directories too. If a directory already exists, it's silently ignored — no drama, no error, just vibes 🫶.

Added in version 3.5: support for multiple input directories.

🧮 `md5sum`

md5sum <file>...

Creates MD5 checksums of files in md5sum compatible format:

351abe79cd3800b38cdfb25d45015a15  file1.txt
052f86c15bbde68af55c7f7b340ab639  file2.txt

Changed in version 4.3: passing - reads from standard input.

⭐ `sha1sum`

sha1sum <file>...

Added in version 3.10.

Creates SHA1 checksums of files in sha1sum compatible format:

4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt

Changed in version 4.3: passing - reads from standard input.

⭐ `sha224sum`

sha224sum <file>...

Added in version 3.10.

Creates SHA224 checksums of files in sha224sum compatible format:

b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930  file1.txt
6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24  file2.txt

Changed in version 4.3: passing - reads from standard input.

⭐ `sha256sum`

sha256sum <file>...

Added in version 3.10.

Creates SHA256 checksums of files in sha256sum compatible format:

76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc  file1.txt
15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea  file2.txt

Changed in version 4.3: passing - reads from standard input.

⭐ `sha384sum`

sha384sum <file>...

Added in version 3.10.

Creates SHA384 checksums of files in sha384sum compatible format:

acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434  file1.txt
668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d  file2.txt

Changed in version 4.3: passing - reads from standard input.

⭐ `sha512sum`

sha512sum <file>...

Added in version 3.10.

Creates SHA512 checksums of files in sha512sum compatible format:

2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89  file1.txt
7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d  file2.txt

Changed in version 4.3: passing - reads from standard input.

🗑️ `remove`

remove [-f] <file>...

Deprecated since version 3.17. Do not use, bestie, I'm begging 😭

Removes the file(s). The planned behaviour was that if any of the listed files already don't exist, the command returns a non-zero exit code, but no message is logged. The -f option changes that to return a zero exit code (i.e. success) in such situations instead.

remove does not follow symlinks — meaning it removes only the symlinks and not the files they point to.

💀 Okay so the tea: the implementation was buggy and always returned 0. It cannot be fixed without breaking backwards compatibility. Use rm instead. Periodt.

🗑️ `remove_directory`

remove_directory <dir>...

Deprecated since version 3.17.

Removes the <dir> directories and their contents. If a directory doesn't exist, it's silently ignored. Use rm instead 🫶.

Added in version 3.15: support for multiple directories.
Added in version 3.16: if <dir> is a symlink to a directory, just the symlink is removed.

✏️ `rename`

rename <oldname> <newname>

Renames a file or directory (on one volume). If a file with the <newname> name already exists, it will be silently replaced. No warning, no "are you sure", just gone 💀. You've been warned.

🧹 `rm`

rm [-rRf] [--] <file|dir>...

Added in version 3.17. Honestly? The glow-up we deserved 💅

Removes the files <file> or directories <dir>. Use -r or -R to remove directories and their contents recursively. If any of the listed files/directories don't exist, the command returns a non-zero exit code, but no message is logged. The -f option changes that to return a zero exit code (i.e. success) instead.

Use -- to stop interpreting options and treat all remaining arguments as paths, even if they start with -. So your weirdly-named -myfile.txt is safe 🫶.

😴 `sleep`

sleep <number>

Added in version 3.0.

Sleeps for <number> seconds. <number> can be a floating point number, so 0.5 is valid and valid is cute. A practical minimum is about 0.1 seconds due to overhead in starting/stopping the CMake executable.

Super useful inside a CMake script when you want to insert a delay:

# Sleep for about 0.5 seconds
execute_process(COMMAND ${CMAKE_COMMAND} -E sleep 0.5)

Go take a nap, you've earned it 🌸

🎁 `tar`

tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]

Creates or extracts a tar or zip archive. The options so far are:

c — creates a new archive containing the specified files. If you use this, the <pathname>... argument is mandatory 👑.
x — extracts to disk from the archive.
t — lists what's inside the archive. a little peek inside the box 💅

Added in version 3.15: you can pass <pathname>... to list only the selected files or directories. choosey queen behavior, love that

v — verbose output. it tells you everything, no gatekeeping
z — compress the archive you're making with gzip (Deflate). classic, reliable, does the job ✨
j — compress with bzip2.
J — Added in version 3.1. compress with XZ (LZMA2).
--zstd — Added in version 3.15. compress with Zstandard. zstd girlies rise 🫶
--lzma — Added in version 4.3. compress with the LZMA algorithm.
--files-from=<file> — Added in version 3.1. read the file names from <file>, one per line. Blank lines get ignored. Lines are not allowed to start with -, except for --add-file=<name> so you can add files whose names start with -. iykyk, gotta make room for the chaotic filenames
--format=<format> — Added in version 3.3. pick the format of the archive you're creating. The supported formats are:
- 7zip
- gnutar
- pax
- paxr (restricted pax, this one's the default)
- raw

Added in version 4.3. If you use this format, only one file gets compressed, using whatever compression type --cmake-tar-compression-method says. one file and one file only, she's exclusive 💅

zip

If you don't specify a compression method, the compression method depends on the format:

7zip uses LZMA compression
zip uses Deflate compression
everything else uses no compression by default

Added in version 4.3: the 7zip and zip formats support changing the default compression method and the compression level. glow-up for the archive formats ✨

--mtime=<date> — Added in version 3.1. set the modification time that gets recorded in the tarball entries. time travel but make it timestamped 🕰️
--cmake-tar-compression-method=<compression-method> — Added in version 4.3. The <compression-method> has to be one of these:
- none or store — no compression at all
- deflate or gzip — Deflate-based
- bzip2 — BZip2-based
- lzma — LZMA-based
- lzma2 or xz — LZMA2-based
- ppmd — PPMd-based

This compression method is only supported by the 7zip archive format. no 7zip, no ppmd, that's the rule 😤

zstd — Zstandard-based

This is the second variant for picking your compression method. It gives you more compression methods than the classic tar-like interface. You can use any of them. more options, more power 👑

The default value depends on the --format option value, and it's described in the corresponding section. it's giving "read the room (and the format)"

--cmake-tar-compression-level=<compression-level> — Added in version 4.3. The <compression-level> should be between 0 and 9, and the default is 0. The compression algorithm must be selected when you give the --cmake-tar-compression-level option. don't be out here setting a level with no algorithm, it will not slay 😭

The <compression-level> for the Zstd algorithm can be set between 0 and 19, except for the zip format. zstd got the extended range, she's built different

The value 0 means "use the default compression level." It gets selected automatically by the archive library backend and is not directly set by CMake itself. So the default compression level may vary between archive formats, platforms, etc. lowkey mysterious, but that's the backend's business ✨

--cmake-tar-encoding=<encoding> — Added in version 4.4. specify the pathname character encoding used in the archive. The <encoding> may be one of:
- UTF-8 — archive pathnames are encoded as UTF-8. This is the default since CMake 4.4. the moment, the icon, the standard 💅
- OEM — on Windows platforms, pathnames are encoded using the original equipment manufacturer (OEM) code page. On non-Windows platforms, pathnames are encoded according to the current locale. In CMake 4.3 and below, the OEM encoding (current locale) was always used. throwback behavior, respectfully
- UTF-16LE, UTF-16BE — archive pathnames are encoded as UTF-16 little-endian or big-endian. endian girlies, pick your fighter 🦋
- ... — any encoding name that iconv supports on the current platform. On Windows, code page names may be specified. the "etc etc" of encodings, she contains multitudes

Note: 7zip archives always encode paths as UTF-16LE, so this option is silently ignored for that format. she heard you, she just chose not to listen 🙈

--cmake-tar-threads=<number> — Added in version 4.3. use <number> threads to operate on the archive. Currently only multi-threaded compression is supported. parallel slay ⚡

If set to 0, the number of available cores on the machine gets used instead. Note that not all compression modes support threading in all environments. vibe check your environment first, bestie

--touch — Added in version 3.24. use the current local timestamp instead of extracting the file timestamps from the archive. "these files are from now, thank you" 🕰️
-- — Added in version 3.1. stop interpreting options and treat every remaining argument as a file name, even if it starts with -. the great separator, the "I said what I said" of flags 💅

Added in version 3.1: LZMA (7zip) support. we've come so far 🫶

Added in version 3.15: the command now continues adding files to an archive even if some of the files aren't readable. This behavior is more consistent with the classic tar tool. The command also now parses all flags, and if an invalid flag was provided, a warning is issued. she doesn't stop for one unreadable file, she's a professional 😤✨

⏱️ `time <command> [<args>...]` 🌸

Run <command> and display the elapsed time (including the overhead of the CMake frontend). stopwatch era ⏱️

Added in version 3.5: the command now properly passes arguments with spaces or special characters through to the child process. This may break scripts that worked around the bug with their own extra quoting or escaping. if you were doing manual quoting to dodge the old bug… yeah, that's gonna bite now 🙈

🫶 `touch <file>...` 💖

Creates <file> if the file doesn't exist. If <file> does exist, it changes the <file> access and modification times. manifesting timestamps for your files ✨

🌸 `touch_nocreate <file>...` 🦋

Touch a file if it exists, but don't create it. If a file doesn't exist, it will be silently ignored. no notes, no drama, just vibes 💅

⭐ `true` 🌈

Added in version 3.16. Do nothing, with an exit code of 0. the most unbothered command in existence, and honestly? iconic 👑

💻 Windows-Specific Command-Line Tools 🪟

The following cmake -E commands are available only on Windows: Windows besties, this section is for you 🫶

delete_regv <key> — delete a Windows registry value. careful with the registry, bestie, it doesn't do take-backs 💀
env_vs8_wince <sdkname> — Added in version 3.2. displays a batch file which sets the environment for the provided Windows CE SDK installed in VS2005. vintage 💅
env_vs9_wince <sdkname> — Added in version 3.2. displays a batch file which sets the environment for the provided Windows CE SDK installed in VS2008. also vintage, slightly less vintage
write_regv <key> <value> — write a Windows registry value. writing to the registry, main character energy, don't mess it up 😭

🔎 RUN THE FIND-PACKAGE TOOL 🎀

CMake provides a pkg-config-like helper for Makefile-based projects: a little bridge between worlds 🌉

cmake --find-package [<options>]

Note: This mode is not well-supported due to some technical limitations. It's kept for compatibility but should not be used in new projects. it's giving "still invited to the party but please don't bring it up" 🙈

--find-package — searches a package using the find_package() command and prints the resulting flags to stdout. This can be used instead of pkg-config to find installed libraries in plain Makefile-based projects or in Autoconf-based projects, using auxiliary macros installed in share/aclocal/cmake.m4 on the system. lowkey a translator between CMake and the Makefile girlies 🫶

When you use this option, the following variables are expected:

NAME — the name of the package, as called in find_package(<PackageName>). gotta use the right name, no nicknames 💅
COMPILER_ID — the compiler ID (CMAKE_<LANG>_COMPILER_ID) used for searching the package, i.e. GNU/Intel/Clang/MSVC, etc. know your compiler, respect your compiler
LANGUAGE — the language used for searching the package, i.e. C/CXX/Fortran/ASM, etc.
MODE — the package search mode. The value can be one of:
- EXIST — only checks for the existence of the given package. she's just checking if you're home 🚪
- COMPILE — prints the flags needed for compiling an object file which uses the given package.
- LINK — prints the flags needed for linking when using the given package. the connector, the glue, the moment 🔗
SILENT — (optional) if TRUE, the find result message is not printed. stealth mode activated 🤫

For example: literally copy-paste this one, it's a whole vibe ✨

cmake --find-package -DNAME=CURL -DCOMPILER_ID=GNU -DLANGUAGE=C -DMODE=LINK

🌈 RUN A WORKFLOW PRESET 🌈

okay so bestie, this one was Added in version 3.25 and it's genuinely iconic. CMake Presets gives you a way to execute multiple build steps in order, like a little build choreography 💅

cmake --workflow <options>

The options are:

--workflow — Select a Workflow Preset using one of the following options.
--preset <preset>, --preset=<preset> — Use a workflow preset to specify a workflow. The project binary directory is inferred from the initial configure preset.

Changed in version 3.31: When following immediately after the --workflow option, the --preset argument can be omitted and just the <preset> name can be given. This means the following syntax is valid: $ cmake --workflow my-preset

Changed in version 4.4: If --presets-file is specified, neither of CMakePresets.json nor CMakeUserPresets.json are required to be present. Otherwise, they are required to be present in the top level source directory. In prior versions, this was strictly required. 💀

--presets-file <file>, --presets-file=<file> — Added in version 4.4. Reads presets from the given <file>. The specified path may be absolute or relative to the current working directory. If --presets-file is given, presets defined in CMakePresets.json and CMakeUserPresets.json will be ignored. lowkey a vibe shift ✨
--list-presets — Lists the available workflow presets.

Changed in version 4.4: If --presets-file is specified, neither of CMakePresets.json nor CMakeUserPresets.json are required to be present, and only presets defined in the given <file> will be listed. Otherwise, they are required to be present in the top level source directory. In prior versions, this was strictly required.

--fresh — Perform a fresh configuration of the build tree, which has the same effect as cmake --fresh. clean slate energy 🫶

✨ VIEW HELP ✨

To print selected pages from the CMake documentation, use

cmake --help[-<topic>]

with one of the following options:

-version[=json-v1] [<file>], --version[=json-v1] [<file>], /V[=json-v1] [<file>], /version[=json-v1] [<file>] — Show program name/version banner and exit. If json-v1 is specified, print extended version information in JSON format. The JSON output contains the versions for the CMake and its dependencies. The output is printed to a named <file> if given.

The JSON output format is described in machine-readable form by this JSON schema. ngl, very much machine-readable queen behavior 📊

-h, -H, --help, -help, -usage, /? — Print usage information and exit.

Usage describes the basic command line interface and its options.

--help <keyword> [<file>] — Print help for one CMake keyword.

<keyword> can be a property, variable, command, policy, generator or module.

The relevant manual entry for <keyword> is printed in a human-readable text format. The output is printed to a named <file> if given.

Changed in version 3.28: Prior to CMake 3.28, this option supported command names only. she grew 💅

--help-full [<file>] — Print all help manuals and exit.

All manuals are printed in a human-readable text format. The output is printed to a named <file> if given. literally everything, no crumbs 🍓

--help-manual <man> [<file>] — Print one help manual and exit.

The specified manual is printed in a human-readable text format. The output is printed to a named <file> if given.

--help-manual-list [<file>] — List help manuals available and exit.

The list contains all manuals for which help may be obtained by using the --help-manual option followed by a manual name. The output is printed to a named <file> if given.

--help-command <cmd> [<file>] — Print help for one command and exit.

The cmake-commands(7) manual entry for <cmd> is printed in a human-readable text format. The output is printed to a named <file> if given.

--help-command-list [<file>] — List commands with help available and exit.

The list contains all commands for which help may be obtained by using the --help-command option followed by a command name. The output is printed to a named <file> if given.

--help-commands [<file>] — Print cmake-commands manual and exit.

The cmake-commands(7) manual is printed in a human-readable text format. The output is printed to a named <file> if given.

--help-module <mod> [<file>] — Print help for one module and exit.

The cmake-modules(7) manual entry for <mod> is printed in a human-readable text format. The output is printed to a named <file> if given.

--help-module-list [<file>] — List modules with help available and exit.

The list contains all modules for which help may be obtained by using the --help-module option followed by a module name. The output is printed to a named <file> if given.

--help-modules [<file>] — Print cmake-modules manual and exit.

The cmake-modules(7) manual is printed in a human-readable text format. The output is printed to a named <file> if given.

--help-policy <cmp> [<file>] — Print help for one policy and exit.

The cmake-policies(7) manual entry for <cmp> is printed in a human-readable text format. The output is printed to a named <file> if given.

--help-policy-list [<file>] — List policies with help available and exit.

The list contains all policies for which help may be obtained by using the --help-policy option followed by a policy name. The output is printed to a named <file> if given.

--help-policies [<file>] — Print cmake-policies manual and exit.

The cmake-policies(7) manual is printed in a human-readable text format. The output is printed to a named <file> if given.

--help-property <prop> [<file>] — Print help for one property and exit.

The cmake-properties(7) manual entries for <prop> are printed in a human-readable text format. The output is printed to a named <file> if given.

--help-property-list [<file>] — List properties with help available and exit.

The list contains all properties for which help may be obtained by using the --help-property option followed by a property name. The output is printed to a named <file> if given.

--help-properties [<file>] — Print cmake-properties manual and exit.

The cmake-properties(7) manual is printed in a human-readable text format. The output is printed to a named <file> if given.

--help-variable <var> [<file>] — Print help for one variable and exit.

The cmake-variables(7) manual entry for <var> is printed in a human-readable text format. The output is printed to a named <file> if given.

--help-variable-list [<file>] — List variables with help available and exit.

The list contains all variables for which help may be obtained by using the --help-variable option followed by a variable name. The output is printed to a named <file> if given.

--help-variables [<file>] — Print cmake-variables manual and exit.

The cmake-variables(7) manual is printed in a human-readable text format. The output is printed to a named <file> if given.

To view the presets available for a project, use

cmake <source-dir> --list-presets

🎀 RETURN VALUE (EXIT CODE) 🎀

Upon regular termination, the cmake executable returns the exit code 0. she said "we're done here" and left gracefully 💅

If termination is caused by the command message(FATAL_ERROR), or another error condition, then a non-zero exit code is returned. 😭 drama, but make it exit-code.

👑 SEE ALSO 👑

The following resources are available to get help using CMake:

Home Page https://cmake.org

The primary starting point for learning about CMake. the main character of starting points fr 🏠

Online Documentation and Community Resources https://cmake.org/documentation

Links to available documentation and community resources may be found on this web page.

Discourse Forum https://discourse.cmake.org

The Discourse Forum hosts discussion and questions about CMake. come through and ask ur questions bestie 🫶

💖 Copyright 💖

2000-2026 Kitware, Inc. and Contributors

okay so that's the whole page, bestie, and this last bit is the footer tea: it's version 4.4.5, dated Oct 28, 2026, and it lives at CMAKE(1). go build something iconic 🦋✨

📦 where this page comes from

arch rolling: cmake 4.4.5-1 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

CMAKE(1)

💖 CMAKE(1) — the CMake Command-Line Reference, explained by your favorite terminal gremlin 💖

✨ SYNOPSIS ✨

🌸 DESCRIPTION 🌸

🦋 INTRODUCTION TO CMAKE BUILDSYSTEMS 🦋

💜 GENERATE A PROJECT BUILDSYSTEM 💜

🎀 Options 🎀

Variables specific to the Graphviz support

🦋 GRAPHVIZ_EXTERNAL_LIBS

🎀 GRAPHVIZ_CUSTOM_TARGETS

🌸 GRAPHVIZ_IGNORE_TARGETS

✨ GRAPHVIZ_GENERATE_PER_TARGET

💅 GRAPHVIZ_GENERATE_DEPENDERS

🔨 BUILD A PROJECT 🔨

🛠️ Generator-Specific Build Tool Behavior 🛠️

🛠️ INSTALL A PROJECT 💅

🚪 OPEN A PROJECT 🌈

📜 RUN A SCRIPT 🧚

💻 RUN A COMMAND-LINE TOOL 🔥

🧰 bin2c [<options>...] [--] [<input-file> [<output-file>]]

🧰 capabilities

🧰 cat [--] <files>...

🧰 chdir <dir> <cmd> [<arg>...]

🧰 compare_files [--ignore-eol] <file1> <file2>

🧰 copy <file>... <destination>,

📁 copy

🌸 copy_directory

🦋 copy_directory_if_different

🎀 copy_directory_if_newer

💅 copy_if_different

✨ copy_if_newer

🔗 create_symlink

🧲 create_hardlink

🗣️ echo

🤫 echo_append

🌈 env

🌍 environment

💀 false

📂 make_directory

🧮 md5sum

⭐ sha1sum

⭐ sha224sum

⭐ sha256sum

⭐ sha384sum

⭐ sha512sum

🗑️ remove

🗑️ remove_directory

✏️ rename

🧹 rm

😴 sleep

🎁 tar

⏱️ time <command> [<args>...] 🌸

🫶 touch <file>... 💖

🌸 touch_nocreate <file>... 🦋

⭐ true 🌈

💻 Windows-Specific Command-Line Tools 🪟

🔎 RUN THE FIND-PACKAGE TOOL 🎀

🌈 RUN A WORKFLOW PRESET 🌈

✨ VIEW HELP ✨

🎀 RETURN VALUE (EXIT CODE) 🎀

👑 SEE ALSO 👑

💖 Copyright 💖

🦋 `GRAPHVIZ_EXTERNAL_LIBS`

🎀 `GRAPHVIZ_CUSTOM_TARGETS`

🌸 `GRAPHVIZ_IGNORE_TARGETS`

✨ `GRAPHVIZ_GENERATE_PER_TARGET`

💅 `GRAPHVIZ_GENERATE_DEPENDERS`

🧰 `bin2c [<options>...] [--] [<input-file> [<output-file>]]`

🧰 `capabilities`

🧰 `cat [--] <files>...`

🧰 `chdir <dir> <cmd> [<arg>...]`

🧰 `compare_files [--ignore-eol] <file1> <file2>`

🧰 `copy <file>... <destination>,`

📁 `copy`

🌸 `copy_directory`

🦋 `copy_directory_if_different`

🎀 `copy_directory_if_newer`

💅 `copy_if_different`

✨ `copy_if_newer`

🔗 `create_symlink`

🧲 `create_hardlink`

🗣️ `echo`

🤫 `echo_append`

🌈 `env`

🌍 `environment`

💀 `false`

📂 `make_directory`

🧮 `md5sum`

⭐ `sha1sum`

⭐ `sha224sum`

⭐ `sha256sum`

⭐ `sha384sum`

⭐ `sha512sum`

🗑️ `remove`

🗑️ `remove_directory`

✏️ `rename`

🧹 `rm`

😴 `sleep`

🎁 `tar`

⏱️ `time <command> [<args>...]` 🌸

🫶 `touch <file>...` 💖

🌸 `touch_nocreate <file>...` 🦋

⭐ `true` 🌈