1 .. cmake-manual-description: CMake Command-Line Reference
11 `Generate a Project Buildsystem`_
12 cmake [<options>] <path-to-source>
13 cmake [<options>] <path-to-existing-build>
14 cmake [<options>] -S <path-to-source> -B <path-to-build>
17 cmake --build <dir> [<options>] [-- <build-tool-options>]
20 cmake --install <dir> [<options>]
26 cmake [{-D <var>=<value>}...] -P <cmake-script-file>
28 `Run a Command-Line Tool`_
29 cmake -E <command> [<options>]
31 `Run the Find-Package Tool`_
32 cmake --find-package [<options>]
35 cmake --help[-<topic>]
40 The **cmake** executable is the command-line interface of the cross-platform
41 buildsystem generator CMake. The above `Synopsis`_ lists various actions
42 the tool can perform as described in sections below.
44 To build a software project with CMake, `Generate a Project Buildsystem`_.
45 Optionally use **cmake** to `Build a Project`_, `Install a Project`_ or just
46 run the corresponding build tool (e.g. ``make``) directly. **cmake** can also
47 be used to `View Help`_.
49 The other actions are meant for use by software developers writing
50 scripts in the :manual:`CMake language <cmake-language(7)>` to support
53 For graphical user interfaces that may be used in place of **cmake**,
54 see :manual:`ccmake <ccmake(1)>` and :manual:`cmake-gui <cmake-gui(1)>`.
55 For command-line interfaces to the CMake testing and packaging facilities,
56 see :manual:`ctest <ctest(1)>` and :manual:`cpack <cpack(1)>`.
58 For more information on CMake at large, `see also`_ the links at the end
62 Introduction to CMake Buildsystems
63 ==================================
65 A *buildsystem* describes how to build a project's executables and libraries
66 from its source code using a *build tool* to automate the process. For
67 example, a buildsystem may be a ``Makefile`` for use with a command-line
68 ``make`` tool or a project file for an Integrated Development Environment
69 (IDE). In order to avoid maintaining multiple such buildsystems, a project
70 may specify its buildsystem abstractly using files written in the
71 :manual:`CMake language <cmake-language(7)>`. From these files CMake
72 generates a preferred buildsystem locally for each user through a backend
75 To generate a buildsystem with CMake, the following must be selected:
78 The top-level directory containing source files provided by the project.
79 The project specifies its buildsystem using files as described in the
80 :manual:`cmake-language(7)` manual, starting with a top-level file named
81 ``CMakeLists.txt``. These files specify build targets and their
82 dependencies as described in the :manual:`cmake-buildsystem(7)` manual.
85 The top-level directory in which buildsystem files and build output
86 artifacts (e.g. executables and libraries) are to be stored.
87 CMake will write a ``CMakeCache.txt`` file to identify the directory
88 as a build tree and store persistent information such as buildsystem
89 configuration options.
91 To maintain a pristine source tree, perform an *out-of-source* build
92 by using a separate dedicated build tree. An *in-source* build in
93 which the build tree is placed in the same directory as the source
94 tree is also supported, but discouraged.
97 This chooses the kind of buildsystem to generate. See the
98 :manual:`cmake-generators(7)` manual for documentation of all generators.
99 Run ``cmake --help`` to see a list of generators available locally.
100 Optionally use the ``-G`` option below to specify a generator, or simply
101 accept the default CMake chooses for the current platform.
103 When using one of the :ref:`Command-Line Build Tool Generators`
104 CMake expects that the environment needed by the compiler toolchain
105 is already configured in the shell. When using one of the
106 :ref:`IDE Build Tool Generators`, no particular environment is needed.
109 Generate a Project Buildsystem
110 ==============================
112 Run CMake with one of the following command signatures to specify the
113 source and build trees and generate a buildsystem:
115 ``cmake [<options>] <path-to-source>``
116 Uses the current working directory as the build tree, and
117 ``<path-to-source>`` as the source tree. The specified path may
118 be absolute or relative to the current working directory.
119 The source tree must contain a ``CMakeLists.txt`` file and must
120 *not* contain a ``CMakeCache.txt`` file because the latter
121 identifies an existing build tree. For example:
123 .. code-block:: console
125 $ mkdir build ; cd build
128 ``cmake [<options>] <path-to-existing-build>``
129 Uses ``<path-to-existing-build>`` as the build tree, and loads the
130 path to the source tree from its ``CMakeCache.txt`` file, which must
131 have already been generated by a previous run of CMake. The specified
132 path may be absolute or relative to the current working directory.
135 .. code-block:: console
140 ``cmake [<options>] -S <path-to-source> -B <path-to-build>``
141 Uses ``<path-to-build>`` as the build tree and ``<path-to-source>``
142 as the source tree. The specified paths may be absolute or relative
143 to the current working directory. The source tree must contain a
144 ``CMakeLists.txt`` file. The build tree will be created automatically
145 if it does not already exist. For example:
147 .. code-block:: console
149 $ cmake -S src -B build
151 In all cases the ``<options>`` may be zero or more of the `Options`_ below.
153 After generating a buildsystem one may use the corresponding native
154 build tool to build the project. For example, after using the
155 :generator:`Unix Makefiles` generator one may run ``make`` directly:
157 .. code-block:: console
162 Alternatively, one may use **cmake** to `Build a Project`_ by
163 automatically choosing and invoking the appropriate native build tool.
170 .. include:: OPTIONS_BUILD.txt
173 List non-advanced cached variables.
175 List ``CACHE`` variables will run CMake and list all the variables from
176 the CMake ``CACHE`` that are not marked as ``INTERNAL`` or :prop_cache:`ADVANCED`.
177 This will effectively display current CMake settings, which can then be
178 changed with ``-D`` option. Changing some of the variables may result
179 in more variables being created. If ``A`` is specified, then it will
180 display also advanced variables. If ``H`` is specified, it will also
181 display help for each variable.
186 Only load the cache. Do not actually run configure and generate
189 ``--graphviz=[file]``
190 Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more.
192 Generate a graphviz input file that will contain all the library and
193 executable dependencies in the project. See the documentation for
194 :module:`CMakeGraphVizOptions` for more details.
196 ``--system-information [file]``
197 Dump information about this system.
199 Dump a wide range of information about the current system. If run
200 from the top of a binary tree for a CMake project it will dump
201 additional information such as the cache, log files etc.
203 ``--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>``
206 The :command:`message` command will only output messages of the specified
207 log level or higher. The default log level is ``STATUS``.
209 To make a log level persist between CMake runs, set
210 :variable:`CMAKE_MESSAGE_LOG_LEVEL` as a cache variable instead.
211 If both the command line option and the variable are given, the command line
212 option takes precedence.
214 For backward compatibility reasons, ``--loglevel`` is also accepted as a
215 synonym for this option.
218 Enable the :command:`message` command outputting context attached to each
221 This option turns on showing context for the current CMake run only.
222 To make showing the context persistent for all subsequent CMake runs, set
223 :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` as a cache variable instead.
224 When this command line option is given, :variable:`CMAKE_MESSAGE_CONTEXT_SHOW`
227 ``--debug-trycompile``
228 Do not delete the :command:`try_compile` build tree.
229 Only useful on one :command:`try_compile` at a time.
231 Do not delete the files and directories created for :command:`try_compile`
232 calls. This is useful in debugging failed try_compiles. It may
233 however change the results of the try-compiles as old junk from a
234 previous try-compile may cause a different test to either pass or
235 fail incorrectly. This option is best used for one try-compile at a
236 time, and only when debugging.
239 Put cmake in a debug mode.
241 Print extra information during the cmake run like stack traces with
242 :command:`message(SEND_ERROR)` calls.
245 Put cmake find in a debug mode.
247 Print extra find call information during the cmake run to standard
248 error. Output is designed for human consumption and not for parsing.
251 Put cmake in trace mode.
253 Print a trace of all calls made and from where.
256 Put cmake in trace mode.
258 Like ``--trace``, but with variables expanded.
260 ``--trace-format=<format>``
261 Put cmake in trace mode and sets the trace output format.
263 ``<format>`` can be one of the following values.
266 Prints each trace line in a human-readable format. This is the
270 Prints each line as a separate JSON document. Each document is
271 separated by a newline ( ``\n`` ). It is guaranteed that no
272 newline characters will be present inside a JSON document.
279 "file": "/full/path/to/the/CMake/file.txt",
281 "cmd": "add_executable",
282 "args": ["foo", "bar"],
283 "time": 1579512535.9687231,
290 The full path to the CMake source file where the function
294 The line in ``file`` of the function call.
297 The name of the function that was called.
300 A string list of all function parameters.
303 Timestamp (seconds since epoch) of the function call.
306 Stack frame depth of the function that was called.
308 Additionally, the first JSON document outputted contains the
309 ``version`` key for the current major and minor version of the
325 Indicates the version of the JSON format. The version has a
326 major and minor components following semantic version conventions.
328 ``--trace-source=<file>``
329 Put cmake in trace mode, but output only lines of a specified file.
331 Multiple options are allowed.
333 ``--trace-redirect=<file>``
334 Put cmake in trace mode and redirect trace output to a file instead of stderr.
336 ``--warn-uninitialized``
337 Warn about uninitialized values.
339 Print a warning when an uninitialized variable is used.
341 ``--warn-unused-vars``
342 Warn about unused variables.
344 Find variables that are declared or set, but not used.
346 ``--no-warn-unused-cli``
347 Don't warn about command line options.
349 Don't find variables that are declared on the command line, but not
352 ``--check-system-vars``
353 Find problems with variable usage in system files.
355 Normally, unused and uninitialized variables are searched for only
356 in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`.
357 This flag tells CMake to warn about other files as well.
359 .. _`Build Tool Mode`:
364 CMake provides a command-line signature to build an already-generated
367 .. code-block:: shell
369 cmake --build <dir> [<options>] [-- <build-tool-options>]
371 This abstracts a native build tool's command-line interface with the
375 Project binary directory to be built. This is required and must be first.
377 ``--parallel [<jobs>], -j [<jobs>]``
378 The maximum number of concurrent processes to use when building.
379 If ``<jobs>`` is omitted the native build tool's default number is used.
381 The :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment variable, if set,
382 specifies a default parallel level when this option is not given.
384 Some native build tools always build in parallel. The use of ``<jobs>``
385 value of ``1`` can be used to limit to a single job.
387 ``--target <tgt>..., -t <tgt>...``
388 Build ``<tgt>`` instead of the default target. Multiple targets may be
389 given, separated by spaces.
392 For multi-configuration tools, choose configuration ``<cfg>``.
395 Build target ``clean`` first, then build.
396 (To clean only, use ``--target clean``.)
399 Ignored. Behavior is default in CMake >= 3.0.
402 Enable verbose output - if supported - including the build commands to be
405 This option can be omitted if :envvar:`VERBOSE` environment variable or
406 :variable:`CMAKE_VERBOSE_MAKEFILE` cached variable is set.
410 Pass remaining options to the native tool.
412 Run ``cmake --build`` with no options for quick help.
417 CMake provides a command-line signature to install an already-generated
420 .. code-block:: shell
422 cmake --install <dir> [<options>]
424 This may be used after building a project to run installation without
425 using the generated build system or the native build tool.
429 Project binary directory to install. This is required and must be first.
432 For multi-configuration generators, choose configuration ``<cfg>``.
434 ``--component <comp>``
435 Component-based install. Only install component ``<comp>``.
437 ``--prefix <prefix>``
438 Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`.
441 Strip before installing.
444 Enable verbose output.
446 This option can be omitted if :envvar:`VERBOSE` environment variable is set.
448 Run ``cmake --install`` with no options for quick help.
453 .. code-block:: shell
457 Open the generated project in the associated application. This is only
458 supported by some generators.
461 .. _`Script Processing Mode`:
466 .. code-block:: shell
468 cmake [{-D <var>=<value>}...] -P <cmake-script-file>
470 Process the given cmake file as a script written in the CMake
471 language. No configure or generate step is performed and the cache
472 is not modified. If variables are defined using ``-D``, this must be
473 done before the ``-P`` argument.
476 Run a Command-Line Tool
477 =======================
479 CMake provides builtin command-line tools through the signature
481 .. code-block:: shell
483 cmake -E <command> [<options>]
485 Run ``cmake -E`` or ``cmake -E help`` for a summary of commands.
486 Available commands are:
489 Report cmake capabilities in JSON format. The output is a JSON object
490 with the following keys:
493 A JSON object with version information. Keys are:
496 The full version string as displayed by cmake ``--version``.
498 The major version number in integer form.
500 The minor version number in integer form.
502 The patch level in integer form.
504 The cmake version suffix string.
506 A bool that is set if the cmake build is from a dirty tree.
509 A list available generators. Each generator is a JSON object with the
513 A string containing the name of the generator.
515 ``true`` if the generator supports toolsets and ``false`` otherwise.
517 ``true`` if the generator supports platforms and ``false`` otherwise.
519 A list of strings with all the extra generators compatible with
523 Optional member that is present when the :manual:`cmake-file-api(7)`
524 is available. The value is a JSON object with one member:
527 A JSON array containing zero or more supported file-api requests.
528 Each request is a JSON object with members:
531 Specifies one of the supported :ref:`file-api object kinds`.
534 A JSON array whose elements are each a JSON object containing
535 ``major`` and ``minor`` members specifying non-negative integer
539 ``true`` if cmake supports server-mode and ``false`` otherwise.
541 ``chdir <dir> <cmd> [<arg>...]``
542 Change the current working directory and run a command.
544 ``compare_files [--ignore-eol] <file1> <file2>``
545 Check if ``<file1>`` is same as ``<file2>``. If files are the same,
546 then returns ``0``, if not it returns ``1``. The ``--ignore-eol`` option
547 implies line-wise comparison and ignores LF/CRLF differences.
549 ``copy <file>... <destination>``
550 Copy files to ``<destination>`` (either file or directory).
551 If multiple files are specified, the ``<destination>`` must be
552 directory and it must exist. Wildcards are not supported.
553 ``copy`` does follow symlinks. That means it does not copy symlinks,
554 but the files or directories it point to.
556 ``copy_directory <dir>... <destination>``
557 Copy content of ``<dir>...`` directories to ``<destination>`` directory.
558 If ``<destination>`` directory does not exist it will be created.
559 ``copy_directory`` does follow symlinks.
561 ``copy_if_different <file>... <destination>``
562 Copy files to ``<destination>`` (either file or directory) if
564 If multiple files are specified, the ``<destination>`` must be
565 directory and it must exist.
566 ``copy_if_different`` does follow symlinks.
568 ``create_symlink <old> <new>``
569 Create a symbolic link ``<new>`` naming ``<old>``.
572 Path to where ``<new>`` symbolic link will be created has to exist beforehand.
574 ``echo [<string>...]``
575 Displays arguments as text.
577 ``echo_append [<string>...]``
578 Displays arguments as text but no new line.
580 ``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...``
581 Run command in a modified environment.
584 Display the current environment variables.
587 Do nothing, with an exit code of 1.
589 ``make_directory <dir>...``
590 Create ``<dir>`` directories. If necessary, create parent
591 directories too. If a directory already exists it will be
595 Create MD5 checksum of files in ``md5sum`` compatible format::
597 351abe79cd3800b38cdfb25d45015a15 file1.txt
598 052f86c15bbde68af55c7f7b340ab639 file2.txt
600 ``sha1sum <file>...``
601 Create SHA1 checksum of files in ``sha1sum`` compatible format::
603 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt
604 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt
606 ``sha224sum <file>...``
607 Create SHA224 checksum of files in ``sha224sum`` compatible format::
609 b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt
610 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt
612 ``sha256sum <file>...``
613 Create SHA256 checksum of files in ``sha256sum`` compatible format::
615 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt
616 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt
618 ``sha384sum <file>...``
619 Create SHA384 checksum of files in ``sha384sum`` compatible format::
621 acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt
622 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt
624 ``sha512sum <file>...``
625 Create SHA512 checksum of files in ``sha512sum`` compatible format::
627 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt
628 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt
630 ``remove [-f] <file>...``
633 Remove the file(s). The planned behaviour was that if any of the
634 listed files already do not exist, the command returns a non-zero exit code,
635 but no message is logged. The ``-f`` option changes the behavior to return a
636 zero exit code (i.e. success) in such situations instead.
637 ``remove`` does not follow symlinks. That means it remove only symlinks
638 and not files it point to.
640 The implementation was buggy and always returned 0. It cannot be fixed without
641 breaking backwards compatibility. Use ``rm`` instead.
643 ``remove_directory <dir>...``
646 Remove ``<dir>`` directories and their contents. If a directory does
647 not exist it will be silently ignored. If ``<dir>`` is a symlink to
648 a directory, just the symlink will be removed.
651 ``rename <oldname> <newname>``
652 Rename a file or directory (on one volume). If file with the ``<newname>`` name
653 already exists, then it will be silently replaced.
655 ``rm [-rRf] <file> <dir>...``
656 Remove the files ``<file>`` or directories ``dir``.
657 Use ``-r`` or ``-R`` to remove directories and their contents recursively.
658 If any of the listed files/directories do not exist, the command returns a
659 non-zero exit code, but no message is logged. The ``-f`` option changes
660 the behavior to return a zero exit code (i.e. success) in such
664 Launch :manual:`cmake-server(7)` mode.
666 ``sleep <number>...``
667 Sleep for given number of seconds.
669 ``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]``
670 Create or extract a tar or zip archive. Options are:
673 Create a new archive containing the specified files.
674 If used, the ``<pathname>...`` argument is mandatory.
676 Extract to disk from the archive.
677 The ``<pathname>...`` argument could be used to extract only selected files
679 When extracting selected files or directories, you must provide their exact
680 names including the path, as printed by list (``-t``).
682 List archive contents.
683 The ``<pathname>...`` argument could be used to list only selected files
686 Produce verbose output.
688 Compress the resulting archive with gzip.
690 Compress the resulting archive with bzip2.
692 Compress the resulting archive with XZ.
694 Compress the resulting archive with Zstandard.
695 ``--files-from=<file>``
696 Read file names from the given file, one per line.
697 Blank lines are ignored. Lines may not start in ``-``
698 except for ``--add-file=<name>`` to add files whose
699 names start in ``-``.
700 ``--format=<format>``
701 Specify the format of the archive to be created.
702 Supported formats are: ``7zip``, ``gnutar``, ``pax``,
703 ``paxr`` (restricted pax, default), and ``zip``.
705 Specify modification time recorded in tarball entries.
707 Stop interpreting options and treat all remaining arguments
708 as file names, even if they start with ``-``.
711 ``time <command> [<args>...]``
712 Run command and display elapsed time.
715 Creates ``<file>`` if file do not exist.
716 If ``<file>`` exists, it is changing ``<file>`` access and modification times.
718 ``touch_nocreate <file>...``
719 Touch a file if it exists but do not create it. If a file does
720 not exist it will be silently ignored.
723 Do nothing, with an exit code of 0.
725 Windows-specific Command-Line Tools
726 -----------------------------------
728 The following ``cmake -E`` commands are available only on Windows:
730 ``delete_regv <key>``
731 Delete Windows registry value.
733 ``env_vs8_wince <sdkname>``
734 Displays a batch file which sets the environment for the provided
735 Windows CE SDK installed in VS2005.
737 ``env_vs9_wince <sdkname>``
738 Displays a batch file which sets the environment for the provided
739 Windows CE SDK installed in VS2008.
741 ``write_regv <key> <value>``
742 Write Windows registry value.
745 Run the Find-Package Tool
746 =========================
748 CMake provides a pkg-config like helper for Makefile-based projects:
750 .. code-block:: shell
752 cmake --find-package [<options>]
754 It searches a package using :command:`find_package()` and prints the
755 resulting flags to stdout. This can be used instead of pkg-config
756 to find installed libraries in plain Makefile-based projects or in
757 autoconf-based projects (via ``share/aclocal/cmake.m4``).
760 This mode is not well-supported due to some technical limitations.
761 It is kept for compatibility but should not be used in new projects.
767 To print selected pages from the CMake documentation, use
769 .. code-block:: shell
771 cmake --help[-<topic>]
773 with one of the following options:
775 .. include:: OPTIONS_HELP.txt
781 .. include:: LINKS.txt