1CMAKE(1) CMake CMAKE(1)
2
6 cmake - CMake Command-Line Reference
7
9 Generate a Project Buildsystem
10 cmake [<options>] -B <path-to-build> [-S <path-to-source>]
11 cmake [<options>] <path-to-source | path-to-existing-build>
12 Build a Project
14 cmake --build <dir> [<options>] [-- <build-tool-options>]
15 Install a Project
17 cmake --install <dir> [<options>]
18 Open a Project
20 cmake --open <dir>
21 Run a Script
23 cmake [-D <var>=<value>]... -P <cmake-script-file>
24 Run a Command-Line Tool
26 cmake -E <command> [<options>]
27 Run the Find-Package Tool
29 cmake --find-package [<options>]
30 Run a Workflow Preset
32 cmake --workflow [<options>]
33 View Help
35 cmake --help[-<topic>]
36
38 The cmake executable is the command-line interface of the cross-plat‐
39 form buildsystem generator CMake. The above Synopsis lists various ac‐
40 tions the tool can perform as described in sections below.
41 To build a software project with CMake, Generate a Project Buildsystem.
43 Optionally use cmake to Build a Project, Install a Project or just run
44 the corresponding build tool (e.g. make) directly. cmake can also be
45 used to View Help.
46 The other actions are meant for use by software developers writing
48 scripts in the CMake language to support their builds.
49 For graphical user interfaces that may be used in place of cmake, see
51 ccmake and cmake-gui. For command-line interfaces to the CMake testing
52 and packaging facilities, see ctest and cpack.
53 For more information on CMake at large, see also the links at the end
55 of this manual.
56
58 A buildsystem describes how to build a project's executables and li‐
59 braries from its source code using a build tool to automate the
60 process. For example, a buildsystem may be a Makefile for use with a
61 command-line make tool or a project file for an Integrated Development
62 Environment (IDE). In order to avoid maintaining multiple such
63 buildsystems, a project may specify its buildsystem abstractly using
64 files written in the CMake language. From these files CMake generates
65 a preferred buildsystem locally for each user through a backend called
66 a generator.
67 To generate a buildsystem with CMake, the following must be selected:
69 Source Tree
71 The top-level directory containing source files provided by the
72 project. The project specifies its buildsystem using files as
73 described in the cmake-language(7) manual, starting with a
74 top-level file named CMakeLists.txt. These files specify build
75 targets and their dependencies as described in the
76 cmake-buildsystem(7) manual.
77 Build Tree
79 The top-level directory in which buildsystem files and build
80 output artifacts (e.g. executables and libraries) are to be
81 stored. CMake will write a CMakeCache.txt file to identify the
82 directory as a build tree and store persistent information such
83 as buildsystem configuration options.
84 To maintain a pristine source tree, perform an out-of-source
86 build by using a separate dedicated build tree. An in-source
87 build in which the build tree is placed in the same directory as
88 the source tree is also supported, but discouraged.
89 Generator
91 This chooses the kind of buildsystem to generate. See the
92 cmake-generators(7) manual for documentation of all generators.
93 Run cmake --help to see a list of generators available locally.
94 Optionally use the -G option below to specify a generator, or
95 simply accept the default CMake chooses for the current plat‐
96 form.
97 When using one of the Command-Line Build Tool Generators CMake
99 expects that the environment needed by the compiler toolchain is
100 already configured in the shell. When using one of the IDE
101 Build Tool Generators, no particular environment is needed.
102
104 Run CMake with one of the following command signatures to specify the
105 source and build trees and generate a buildsystem:
106 cmake [<options>] -B <path-to-build> [-S <path-to-source>]
108 New in version 3.13.
109 Uses <path-to-build> as the build tree and <path-to-source> as the
112 source tree. The specified paths may be absolute or relative to the
113 current working directory. The source tree must contain a CMake‐
114 Lists.txt file. The build tree will be created automatically if it
115 does not already exist. For example:
116 $ cmake -S src -B build
118 cmake [<options>] <path-to-source>
120 Uses the current working directory as the build tree, and
121 <path-to-source> as the source tree. The specified path may be
122 absolute or relative to the current working directory. The
123 source tree must contain a CMakeLists.txt file and must not con‐
124 tain a CMakeCache.txt file because the latter identifies an ex‐
125 isting build tree. For example:
126 $ mkdir build ; cd build
128 $ cmake ../src
129 cmake [<options>] <path-to-existing-build>
131 Uses <path-to-existing-build> as the build tree, and loads the
132 path to the source tree from its CMakeCache.txt file, which must
133 have already been generated by a previous run of CMake. The
134 specified path may be absolute or relative to the current work‐
135 ing directory. For example:
136 $ cd build
138 $ cmake .
139 In all cases the <options> may be zero or more of the Options below.
141 The above styles for specifying the source and build trees may be
143 mixed. Paths specified with -S or -B are always classified as source
144 or build trees, respectively. Paths specified with plain arguments are
145 classified based on their content and the types of paths given earlier.
146 If only one type of path is given, the current working directory (cwd)
147 is used for the other. For example:
148 ┌────────────────────┬────────────┬───────────┐
150 │Command Line │ Source Dir │ Build Dir │
151 ├────────────────────┼────────────┼───────────┤
152 │cmake -B build │ cwd │ build │
153 ├────────────────────┼────────────┼───────────┤
154 │cmake -B build src │ src │ build │
155 ├────────────────────┼────────────┼───────────┤
156 │cmake -B build -S │ src │ build │
157 │src │ │ │
158 ├────────────────────┼────────────┼───────────┤
159 │cmake src │ src │ cwd │
160 ├────────────────────┼────────────┼───────────┤
161 │cmake build (exist‐ │ loaded │ build │
162 │ing) │ │ │
163 ├────────────────────┼────────────┼───────────┤
164 │cmake -S src │ src │ cwd │
165 ├────────────────────┼────────────┼───────────┤
166 │cmake -S src build │ src │ build │
167 ├────────────────────┼────────────┼───────────┤
168 │cmake -S src -B │ src │ build │
169 │build │ │ │
170 └────────────────────┴────────────┴───────────┘
171 Changed in version 3.23: CMake warns when multiple source paths are
173 specified. This has never been officially documented or supported, but
174 older versions accidentally accepted multiple source paths and used the
175 last path specified. Avoid passing multiple source path arguments.
176 After generating a buildsystem one may use the corresponding native
179 build tool to build the project. For example, after using the Unix
180 Makefiles generator one may run make directly:
181 $ make
183 $ make install
184 Alternatively, one may use cmake to Build a Project by automatically
186 choosing and invoking the appropriate native build tool.
187 Options
189 -S <path-to-source>
190 Path to root directory of the CMake project to build.
191 -B <path-to-build>
193 Path to directory which CMake will use as the root of build di‐
194 rectory.
195 If the directory doesn't already exist CMake will make it.
197 -C <initial-cache>
199 Pre-load a script to populate the cache.
200 When CMake is first run in an empty build tree, it creates a
202 CMakeCache.txt file and populates it with customizable settings
203 for the project. This option may be used to specify a file from
204 which to load cache entries before the first pass through the
205 project's CMake listfiles. The loaded entries take priority
206 over the project's default values. The given file should be a
207 CMake script containing set() commands that use the CACHE op‐
208 tion, not a cache-format file.
209 References to CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR within the
211 script evaluate to the top-level source and build tree.
212 -D <var>:<type>=<value>, -D <var>=<value>
214 Create or update a CMake CACHE entry.
215 When CMake is first run in an empty build tree, it creates a
217 CMakeCache.txt file and populates it with customizable settings
218 for the project. This option may be used to specify a setting
219 that takes priority over the project's default value. The op‐
220 tion may be repeated for as many CACHE entries as desired.
221 If the :<type> portion is given it must be one of the types
223 specified by the set() command documentation for its CACHE sig‐
224 nature. If the :<type> portion is omitted the entry will be
225 created with no type if it does not exist with a type already.
226 If a command in the project sets the type to PATH or FILEPATH
227 then the <value> will be converted to an absolute path.
228 This option may also be given as a single argument:
230 -D<var>:<type>=<value> or -D<var>=<value>.
231 It's important to note that the order of -C and -D arguments is
233 significant. They will be carried out in the order they are
234 listed, with the last argument taking precedence over the previ‐
235 ous ones. For example, if you specify -DCMAKE_BUILD_TYPE=Debug,
236 followed by a -C argument with a file that calls:
237 set(CMAKE_BUILD_TYPE "Release" CACHE STRING "" FORCE)
239 then the -C argument will take precedence, and CMAKE_BUILD_TYPE
241 will be set to Release. However, if the -D argument comes after
242 the -C argument, it will be set to Debug.
243 If a set(... CACHE ...) call in the -C file does not use FORCE,
245 and a -D argument sets the same variable, the -D argument will
246 take precedence regardless of order because of the nature of
247 non-FORCE set(... CACHE ...) calls.
248 -U <globbing_expr>
250 Remove matching entries from CMake CACHE.
251 This option may be used to remove one or more variables from the
253 CMakeCache.txt file, globbing expressions using * and ? are sup‐
254 ported. The option may be repeated for as many CACHE entries as
255 desired.
256 Use with care, you can make your CMakeCache.txt non-working.
258 -G <generator-name>
260 Specify a build system generator.
261 CMake may support multiple native build systems on certain plat‐
263 forms. A generator is responsible for generating a particular
264 build system. Possible generator names are specified in the
265 cmake-generators(7) manual.
266 If not specified, CMake checks the CMAKE_GENERATOR environment
268 variable and otherwise falls back to a builtin default selec‐
269 tion.
270 -T <toolset-spec>
272 Toolset specification for the generator, if supported.
273 Some CMake generators support a toolset specification to tell
275 the native build system how to choose a compiler. See the
276 CMAKE_GENERATOR_TOOLSET variable for details.
277 -A <platform-name>
279 Specify platform name if supported by generator.
280 Some CMake generators support a platform name to be given to the
282 native build system to choose a compiler or SDK. See the
283 CMAKE_GENERATOR_PLATFORM variable for details.
284 --toolchain <path-to-file>
286 Specify the cross compiling toolchain file, equivalent to set‐
287 ting CMAKE_TOOLCHAIN_FILE variable.
288 --install-prefix <directory>
290 Specify the installation directory, used by the
291 CMAKE_INSTALL_PREFIX variable. Must be an absolute path.
292 -Wno-dev
294 Suppress developer warnings.
295 Suppress warnings that are meant for the author of the CMake‐
297 Lists.txt files. By default this will also turn off deprecation
298 warnings.
299 -Wdev Enable developer warnings.
301 Enable warnings that are meant for the author of the CMake‐
303 Lists.txt files. By default this will also turn on deprecation
304 warnings.
305 -Wdeprecated
307 Enable deprecated functionality warnings.
308 Enable warnings for usage of deprecated functionality, that are
310 meant for the author of the CMakeLists.txt files.
311 -Wno-deprecated
313 Suppress deprecated functionality warnings.
314 Suppress warnings for usage of deprecated functionality, that
316 are meant for the author of the CMakeLists.txt files.
317 -Werror=<what>
319 Treat CMake warnings as errors. <what> must be one of the fol‐
320 lowing:
321 dev Make developer warnings errors.
323 Make warnings that are meant for the author of the CMake‐
325 Lists.txt files errors. By default this will also turn on
326 deprecated warnings as errors.
327 deprecated
329 Make deprecated macro and function warnings errors.
330 Make warnings for usage of deprecated macros and func‐
332 tions, that are meant for the author of the CMake‐
333 Lists.txt files, errors.
334 -Wno-error=<what>
336 Do not treat CMake warnings as errors. <what> must be one of the
337 following:
338 dev Make warnings that are meant for the author of the CMake‐
340 Lists.txt files not errors. By default this will also
341 turn off deprecated warnings as errors.
342 deprecated
344 Make warnings for usage of deprecated macros and func‐
345 tions, that are meant for the author of the CMake‐
346 Lists.txt files, not errors.
347 --fresh
349 New in version 3.24.
350 Perform a fresh configuration of the build tree. This removes
353 any existing CMakeCache.txt file and associated CMakeFiles/ di‐
354 rectory, and recreates them from scratch.
355 -L[A][H]
357 List non-advanced cached variables.
358 List CACHE variables will run CMake and list all the variables
360 from the CMake CACHE that are not marked as INTERNAL or
361 ADVANCED. This will effectively display current CMake settings,
362 which can then be changed with -D option. Changing some of the
363 variables may result in more variables being created. If A is
364 specified, then it will display also advanced variables. If H
365 is specified, it will also display help for each variable.
366 -N View mode only.
368 Only load the cache. Do not actually run configure and generate
370 steps.
371 --graphviz=<file>
373 Generate graphviz of dependencies, see CMakeGraphVizOptions for
374 more.
375 Generate a graphviz input file that will contain all the library
377 and executable dependencies in the project. See the documenta‐
378 tion for CMakeGraphVizOptions for more details.
379 --system-information [file]
381 Dump information about this system.
382 Dump a wide range of information about the current system. If
384 run from the top of a binary tree for a CMake project it will
385 dump additional information such as the cache, log files etc.
386 --log-level=<level>
388 Set the log <level>.
389 The message() command will only output messages of the specified
391 log level or higher. The valid log levels are ERROR, WARNING,
392 NOTICE, STATUS (default), VERBOSE, DEBUG, or TRACE.
393 To make a log level persist between CMake runs, set
395 CMAKE_MESSAGE_LOG_LEVEL as a cache variable instead. If both
396 the command line option and the variable are given, the command
397 line option takes precedence.
398 For backward compatibility reasons, --loglevel is also accepted
400 as a synonym for this option.
401 New in version 3.25: See the cmake_language() command for a way
403 to query the current message logging level.
404 --log-context
407 Enable the message() command outputting context attached to each
408 message.
409 This option turns on showing context for the current CMake run
411 only. To make showing the context persistent for all subsequent
412 CMake runs, set CMAKE_MESSAGE_CONTEXT_SHOW as a cache variable
413 instead. When this command line option is given,
414 CMAKE_MESSAGE_CONTEXT_SHOW is ignored.
415 --debug-trycompile
417 Do not delete the files and directories created for
418 try_compile() / try_run() calls. This is useful in debugging
419 failed checks.
420 Note that some uses of try_compile() may use the same build
422 tree, which will limit the usefulness of this option if a
423 project executes more than one try_compile(). For example, such
424 uses may change results as artifacts from a previous try-compile
425 may cause a different test to either pass or fail incorrectly.
426 This option is best used only when debugging.
427 (With respect to the preceding, the try_run() command is effec‐
429 tively a try_compile(). Any combination of the two is subject
430 to the potential issues described.)
431 New in version 3.25: When this option is enabled, every try-com‐
433 pile check prints a log message reporting the directory in which
434 the check is performed.
435 --debug-output
438 Put cmake in a debug mode.
439 Print extra information during the cmake run like stack traces
441 with message(SEND_ERROR) calls.
442 --debug-find
444 Put cmake find commands in a debug mode.
445 Print extra find call information during the cmake run to stan‐
447 dard error. Output is designed for human consumption and not for
448 parsing. See also the CMAKE_FIND_DEBUG_MODE variable for debug‐
449 ging a more local part of the project.
450 --debug-find-pkg=<pkg>[,...]
452 Put cmake find commands in a debug mode when running under calls
453 to find_package(<pkg>), where <pkg> is an entry in the given
454 comma-separated list of case-sensitive package names.
455 Like --debug-find, but limiting scope to the specified packages.
457 --debug-find-var=<var>[,...]
459 Put cmake find commands in a debug mode when called with <var>
460 as the result variable, where <var> is an entry in the given
461 comma-separated list.
462 Like --debug-find, but limiting scope to the specified variable
464 names.
465 --trace
467 Put cmake in trace mode.
468 Print a trace of all calls made and from where.
470 --trace-expand
472 Put cmake in trace mode.
473 Like --trace, but with variables expanded.
475 --trace-format=<format>
477 Put cmake in trace mode and sets the trace output format.
478 <format> can be one of the following values.
480 human Prints each trace line in a human-readable format.
482 This is the default format.
483 json-v1
485 Prints each line as a separate JSON document. Each
486 document is separated by a newline ( \n ). It is guar‐
487 anteed that no newline characters will be present in‐
488 side a JSON document.
489 JSON trace format
491 {
493 "file": "/full/path/to/the/CMake/file.txt",
494 "line": 0,
495 "cmd": "add_executable",
496 "args": ["foo", "bar"],
497 "time": 1579512535.9687231,
498 "frame": 2,
499 "global_frame": 4
500 }
501 The members are:
503 file The full path to the CMake source file where
505 the function was called.
506 line The line in file where the function call be‐
508 gins.
509 line_end
511 If the function call spans multiple lines, this
512 field will be set to the line where the func‐
513 tion call ends. If the function calls spans a
514 single line, this field will be unset. This
515 field was added in minor version 2 of the
516 json-v1 format.
517 defer Optional member that is present when the func‐
519 tion call was deferred by
520 cmake_language(DEFER). If present, its value
521 is a string containing the deferred call <id>.
522 cmd The name of the function that was called.
524 args A string list of all function parameters.
526 time Timestamp (seconds since epoch) of the function
528 call.
529 frame Stack frame depth of the function that was
531 called, within the context of the CMake‐
532 Lists.txt being processed currently.
533 global_frame
535 Stack frame depth of the function that was
536 called, tracked globally across all CMake‐
537 Lists.txt files involved in the trace. This
538 field was added in minor version 2 of the
539 json-v1 format.
540 Additionally, the first JSON document outputted con‐
542 tains the version key for the current major and minor
543 version of the
544 JSON version format
546 {
548 "version": {
549 "major": 1,
550 "minor": 2
551 }
552 }
553 The members are:
555 version
557 Indicates the version of the JSON format. The
558 version has a major and minor components fol‐
559 lowing semantic version conventions.
560 --trace-source=<file>
562 Put cmake in trace mode, but output only lines of a specified
563 file.
564 Multiple options are allowed.
566 --trace-redirect=<file>
568 Put cmake in trace mode and redirect trace output to a file in‐
569 stead of stderr.
570 --warn-uninitialized
572 Warn about uninitialized values.
573 Print a warning when an uninitialized variable is used.
575 --warn-unused-vars
577 Does nothing. In CMake versions 3.2 and below this enabled
578 warnings about unused variables. In CMake versions 3.3 through
579 3.18 the option was broken. In CMake 3.19 and above the option
580 has been removed.
581 --no-warn-unused-cli
583 Don't warn about command line options.
584 Don't find variables that are declared on the command line, but
586 not used.
587 --check-system-vars
589 Find problems with variable usage in system files.
590 Normally, unused and uninitialized variables are searched for
592 only in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells
593 CMake to warn about other files as well.
594 --compile-no-warning-as-error
596 Ignore target property COMPILE_WARNING_AS_ERROR and variable
597 CMAKE_COMPILE_WARNING_AS_ERROR, preventing warnings from being
598 treated as errors on compile.
599 --profiling-output=<path>
601 Used in conjunction with --profiling-format to output to a given
602 path.
603 --profiling-format=<file>
605 Enable the output of profiling data of CMake script in the given
606 format.
607 This can aid performance analysis of CMake scripts executed.
609 Third party applications should be used to process the output
610 into human readable format.
611 Currently supported values are: google-trace Outputs in Google
613 Trace Format, which can be parsed by the about:tracing tab of
614 Google Chrome or using a plugin for a tool like Trace Compass.
615 --preset <preset>, --preset=<preset>
617 Reads a preset from <path-to-source>/CMakePresets.json and
618 <path-to-source>/CMakeUserPresets.json. The preset may specify
619 the generator and the build directory, and a list of variables
620 and other arguments to pass to CMake. The current working direc‐
621 tory must contain CMake preset files. The CMake GUI can also
622 recognize CMakePresets.json and CMakeUserPresets.json files. For
623 full details on these files, see cmake-presets(7).
624 The presets are read before all other command line options. The
626 options specified by the preset (variables, generator, etc.) can
627 all be overridden by manually specifying them on the command
628 line. For example, if the preset sets a variable called MYVAR to
629 1, but the user sets it to 2 with a -D argument, the value 2 is
630 preferred.
631 --list-presets[=<type>]
633 Lists the available presets of the specified <type>. Valid val‐
634 ues for <type> are configure, build, test, package, or all. If
635 <type> is omitted, configure is assumed. The current working
636 directory must contain CMake preset files.
637 --debugger
639 Enables interactive debugging of the CMake language. CMake ex‐
640 poses a debugging interface on the pipe named by --debugger-pipe
641 that conforms to the Debug Adapter Protocol specification with
642 the following modifications.
643 The initialize response includes an additional field named
645 cmakeVersion which specifies the version of CMake being de‐
646 bugged.
647 Debugger initialize response
649 {
651 "cmakeVersion": {
652 "major": 3,
653 "minor": 27,
654 "patch": 0,
655 "full": "3.27.0"
656 }
657 }
658 The members are:
660 major An integer specifying the major version number.
662 minor An integer specifying the minor version number.
664 patch An integer specifying the patch version number.
666 full A string specifying the full CMake version.
668 --debugger-pipe <pipe name>, --debugger-pipe=<pipe name>
670 Name of the pipe (on Windows) or domain socket (on Unix) to use
671 for debugger communication.
672 --debugger-dap-log <log path>, --debugger-dap-log=<log path>
674 Logs all debugger communication to the specified file.
675
677 CMake provides a command-line signature to build an already-generated
678 project binary tree:
679 cmake --build <dir> [<options>] [-- <build-tool-options>]
681 cmake --build --preset <preset> [<options>] [-- <build-tool-options>]
682 This abstracts a native build tool's command-line interface with the
684 following options:
685 --build <dir>
687 Project binary directory to be built. This is required (unless
688 a preset is specified) and must be first.
689 --preset <preset>, --preset=<preset>
691 Use a build preset to specify build options. The project binary
692 directory is inferred from the configurePreset key. The current
693 working directory must contain CMake preset files. See preset
694 for more details.
695 --list-presets
697 Lists the available build presets. The current working directory
698 must contain CMake preset files.
699 -j [<jobs>], --parallel [<jobs>]
701 New in version 3.12.
702 The maximum number of concurrent processes to use when building.
705 If <jobs> is omitted the native build tool's default number is
706 used.
707 The CMAKE_BUILD_PARALLEL_LEVEL environment variable, if set,
709 specifies a default parallel level when this option is not
710 given.
711 Some native build tools always build in parallel. The use of
713 <jobs> value of 1 can be used to limit to a single job.
714 -t <tgt>..., --target <tgt>...
716 Build <tgt> instead of the default target. Multiple targets may
717 be given, separated by spaces.
718 --config <cfg>
720 For multi-configuration tools, choose configuration <cfg>.
721 --clean-first
723 Build target clean first, then build. (To clean only, use
724 --target clean.)
725 --resolve-package-references=<value>
727 New in version 3.23.
728 Resolve remote package references from external package managers
731 (e.g. NuGet) before build. When <value> is set to on (default),
732 packages will be restored before building a target. When
733 <value> is set to only, the packages will be restored, but no
734 build will be performed. When <value> is set to off, no pack‐
735 ages will be restored.
736 If the target does not define any package references, this op‐
738 tion does nothing.
739 This setting can be specified in a build preset (using re‐
741 solvePackageReferences). The preset setting will be ignored, if
742 this command line option is specified.
743 If no command line parameter or preset option are provided, an
745 environment- specific cache variable will be evaluated to de‐
746 cide, if package restoration should be performed.
747 When using the Visual Studio generator, package references are
749 defined using the VS_PACKAGE_REFERENCES property. Package refer‐
750 ences are restored using NuGet. It can be disabled by setting
751 the CMAKE_VS_NUGET_PACKAGE_RESTORE variable to OFF.
752 --use-stderr
754 Ignored. Behavior is default in CMake >= 3.0.
755 -v, --verbose
757 Enable verbose output - if supported - including the build com‐
758 mands to be executed.
759 This option can be omitted if VERBOSE environment variable or
761 CMAKE_VERBOSE_MAKEFILE cached variable is set.
762 -- Pass remaining options to the native tool.
764 Run cmake --build with no options for quick help.
766
768 CMake provides a command-line signature to install an already-generated
769 project binary tree:
770 cmake --install <dir> [<options>]
772 This may be used after building a project to run installation without
774 using the generated build system or the native build tool. The options
775 are:
776 --install <dir>
778 Project binary directory to install. This is required and must
779 be first.
780 --config <cfg>
782 For multi-configuration generators, choose configuration <cfg>.
783 --component <comp>
785 Component-based install. Only install component <comp>.
786 --default-directory-permissions <permissions>
788 Default directory install permissions. Permissions in format
789 <u=rwx,g=rx,o=rx>.
790 --prefix <prefix>
792 Override the installation prefix, CMAKE_INSTALL_PREFIX.
793 --strip
795 Strip before installing.
796 -v, --verbose
798 Enable verbose output.
799 This option can be omitted if VERBOSE environment variable is
801 set.
802 Run cmake --install with no options for quick help.
804
806 cmake --open <dir>
807 Open the generated project in the associated application. This is only
809 supported by some generators.
810
812 cmake [-D <var>=<value>]... -P <cmake-script-file> [-- <unparsed-options>...]
813 -D <var>=<value>
815 Define a variable for script mode.
816 -P <cmake-script-file>
818 Process the given cmake file as a script written in the CMake
819 language. No configure or generate step is performed and the
820 cache is not modified. If variables are defined using -D, this
821 must be done before the -P argument.
822 Any options after -- are not parsed by CMake, but they are still in‐
824 cluded in the set of CMAKE_ARGV<n> variables passed to the script (in‐
825 cluding the -- itself).
826
828 CMake provides builtin command-line tools through the signature
829 cmake -E <command> [<options>]
831 -E [help]
833 Run cmake -E or cmake -E help for a summary of commands.
834 Available commands are:
836 capabilities
838 New in version 3.7.
839 Report cmake capabilities in JSON format. The output is a JSON
842 object with the following keys:
843 version
845 A JSON object with version information. Keys are:
846 string The full version string as displayed by cmake
848 --version.
849 major The major version number in integer form.
851 minor The minor version number in integer form.
853 patch The patch level in integer form.
855 suffix The cmake version suffix string.
857 isDirty
859 A bool that is set if the cmake build is from a
860 dirty tree.
861 generators
863 A list available generators. Each generator is a JSON ob‐
864 ject with the following keys:
865 name A string containing the name of the generator.
867 toolsetSupport
869 true if the generator supports toolsets and false
870 otherwise.
871 platformSupport
873 true if the generator supports platforms and false
874 otherwise.
875 supportedPlatforms
877 New in version 3.21.
878 Optional member that may be present when the gen‐
881 erator supports platform specification via
882 CMAKE_GENERATOR_PLATFORM (-A ...). The value is a
883 list of platforms known to be supported.
884 extraGenerators
886 A list of strings with all the Extra Generators
887 compatible with the generator.
888 fileApi
890 Optional member that is present when the
891 cmake-file-api(7) is available. The value is a JSON ob‐
892 ject with one member:
893 requests
895 A JSON array containing zero or more supported
896 file-api requests. Each request is a JSON object
897 with members:
898 kind Specifies one of the supported Object
900 Kinds.
901 version
903 A JSON array whose elements are each a JSON
904 object containing major and minor members
905 specifying non-negative integer version
906 components.
907 serverMode
909 true if cmake supports server-mode and false otherwise.
910 Always false since CMake 3.20.
911 tls New in version 3.25.
913 true if TLS support is enabled and false otherwise.
916 debugger
918 New in version 3.27.
919 true if the --debugger mode is supported and false other‐
922 wise.
923 cat [--] <files>...
925 New in version 3.18.
926 Concatenate files and print on the standard output.
929 -- New in version 3.24.
931 Added support for the double dash argument --. This basic
934 implementation of cat does not support any options, so
935 using a option starting with - will result in an error.
936 Use -- to indicate the end of options, in case a file
937 starts with -.
938 chdir <dir> <cmd> [<arg>...]
940 Change the current working directory and run a command.
941 compare_files [--ignore-eol] <file1> <file2>
943 Check if <file1> is same as <file2>. If files are the same, then
944 returns 0, if not it returns 1. In case of invalid arguments,
945 it returns 2.
946 --ignore-eol
948 New in version 3.14.
949 The option implies line-wise comparison and ignores
952 LF/CRLF differences.
953 copy <file>... <destination>, copy -t <destination> <file>...
955 Copy files to <destination> (either file or directory). If mul‐
956 tiple files are specified, or if -t is specified, the <destina‐
957 tion> must be directory and it must exist. If -t is not speci‐
958 fied, the last argument is assumed to be the <destination>.
959 Wildcards are not supported. copy does follow symlinks. That
960 means it does not copy symlinks, but the files or directories it
961 point to.
962 New in version 3.5: Support for multiple input files.
964 New in version 3.26: Support for -t argument.
967 copy_directory <dir>... <destination>
970 Copy content of <dir>... directories to <destination> directory.
971 If <destination> directory does not exist it will be created.
972 copy_directory does follow symlinks.
973 New in version 3.5: Support for multiple input directories.
975 New in version 3.15: The command now fails when the source di‐
978 rectory does not exist. Previously it succeeded by creating an
979 empty destination directory.
980 copy_directory_if_different <dir>... <destination>
983 New in version 3.26.
984 Copy changed content of <dir>... directories to <destination>
987 directory. If <destination> directory does not exist it will be
988 created.
989 copy_directory_if_different does follow symlinks. The command
991 fails when the source directory does not exist.
992 copy_if_different <file>... <destination>
994 Copy files to <destination> (either file or directory) if they
995 have changed. If multiple files are specified, the <destina‐
996 tion> must be directory and it must exist. copy_if_different
997 does follow symlinks.
998 New in version 3.5: Support for multiple input files.
1000 create_symlink <old> <new>
1003 Create a symbolic link <new> naming <old>.
1004 New in version 3.13: Support for creating symlinks on Windows.
1006 NOTE:
1009 Path to where <new> symbolic link will be created has to ex‐
1010 ist beforehand.
1011 create_hardlink <old> <new>
1013 New in version 3.19.
1014 Create a hard link <new> naming <old>.
1017 NOTE:
1019 Path to where <new> hard link will be created has to exist
1020 beforehand. <old> has to exist beforehand.
1021 echo [<string>...]
1023 Displays arguments as text.
1024 echo_append [<string>...]
1026 Displays arguments as text but no new line.
1027 env [<options>] [--] <command> [<arg>...]
1029 New in version 3.1.
1030 Run command in a modified environment. Options are:
1033 NAME=VALUE
1035 Replaces the current value of NAME with VALUE.
1036 --unset=NAME
1038 Unsets the current value of NAME.
1039 --modify ENVIRONMENT_MODIFICATION
1041 New in version 3.25.
1042 Apply a single ENVIRONMENT_MODIFICATION operation to the
1045 modified environment.
1046 The NAME=VALUE and --unset=NAME options are equivalent to
1048 --modify NAME=set:VALUE and --modify NAME=unset:, respec‐
1049 tively. Note that --modify NAME=reset: resets NAME to
1050 the value it had when cmake launched (or unsets it), not
1051 to the most recent NAME=VALUE option.
1052 -- New in version 3.24.
1054 Added support for the double dash argument --. Use -- to
1057 stop interpreting options/environment variables and treat
1058 the next argument as the command, even if it start with -
1059 or contains a =.
1060 environment
1062 Display the current environment variables.
1063 false New in version 3.16.
1065 Do nothing, with an exit code of 1.
1068 make_directory <dir>...
1070 Create <dir> directories. If necessary, create parent directo‐
1071 ries too. If a directory already exists it will be silently ig‐
1072 nored.
1073 New in version 3.5: Support for multiple input directories.
1075 md5sum <file>...
1078 Create MD5 checksum of files in md5sum compatible format:
1079 351abe79cd3800b38cdfb25d45015a15 file1.txt
1081 052f86c15bbde68af55c7f7b340ab639 file2.txt
1082 sha1sum <file>...
1084 New in version 3.10.
1085 Create SHA1 checksum of files in sha1sum compatible format:
1088 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt
1090 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt
1091 sha224sum <file>...
1093 New in version 3.10.
1094 Create SHA224 checksum of files in sha224sum compatible format:
1097 b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt
1099 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt
1100 sha256sum <file>...
1102 New in version 3.10.
1103 Create SHA256 checksum of files in sha256sum compatible format:
1106 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt
1108 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt
1109 sha384sum <file>...
1111 New in version 3.10.
1112 Create SHA384 checksum of files in sha384sum compatible format:
1115 acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt
1117 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt
1118 sha512sum <file>...
1120 New in version 3.10.
1121 Create SHA512 checksum of files in sha512sum compatible format:
1124 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt
1126 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt
1127 remove [-f] <file>...
1129 Deprecated since version 3.17.
1130 Remove the file(s). The planned behavior was that if any of the
1133 listed files already do not exist, the command returns a
1134 non-zero exit code, but no message is logged. The -f option
1135 changes the behavior to return a zero exit code (i.e. success)
1136 in such situations instead. remove does not follow symlinks.
1137 That means it remove only symlinks and not files it point to.
1138 The implementation was buggy and always returned 0. It cannot be
1140 fixed without breaking backwards compatibility. Use rm instead.
1141 remove_directory <dir>...
1143 Deprecated since version 3.17.
1144 Remove <dir> directories and their contents. If a directory does
1147 not exist it will be silently ignored. Use rm instead.
1148 New in version 3.15: Support for multiple directories.
1150 New in version 3.16: If <dir> is a symlink to a directory, just
1153 the symlink will be removed.
1154 rename <oldname> <newname>
1157 Rename a file or directory (on one volume). If file with the
1158 <newname> name already exists, then it will be silently re‐
1159 placed.
1160 rm [-rRf] [--] <file|dir>...
1162 New in version 3.17.
1163 Remove the files <file> or directories <dir>. Use -r or -R to
1166 remove directories and their contents recursively. If any of
1167 the listed files/directories do not exist, the command returns a
1168 non-zero exit code, but no message is logged. The -f option
1169 changes the behavior to return a zero exit code (i.e. success)
1170 in such situations instead. Use -- to stop interpreting options
1171 and treat all remaining arguments as paths, even if they start
1172 with -.
1173 sleep <number>
1175 New in version 3.0.
1176 Sleep for <number> seconds. <number> may be a floating point
1179 number. A practical minimum is about 0.1 seconds due to over‐
1180 head in starting/stopping CMake executable. This can be useful
1181 in a CMake script to insert a delay:
1182 # Sleep for about 0.5 seconds
1184 execute_process(COMMAND ${CMAKE_COMMAND} -E sleep 0.5)
1185 tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]
1187 Create or extract a tar or zip archive. Options are:
1188 c Create a new archive containing the specified files. If
1190 used, the <pathname>... argument is mandatory.
1191 x Extract to disk from the archive.
1193 New in version 3.15: The <pathname>... argument could be
1195 used to extract only selected files or directories. When
1196 extracting selected files or directories, you must pro‐
1197 vide their exact names including the path, as printed by
1198 list (-t).
1199 t List archive contents.
1202 New in version 3.15: The <pathname>... argument could be
1204 used to list only selected files or directories.
1205 v Produce verbose output.
1208 z Compress the resulting archive with gzip.
1210 j Compress the resulting archive with bzip2.
1212 J New in version 3.1.
1214 Compress the resulting archive with XZ.
1217 --zstd New in version 3.15.
1219 Compress the resulting archive with Zstandard.
1222 --files-from=<file>
1224 New in version 3.1.
1225 Read file names from the given file, one per line. Blank
1228 lines are ignored. Lines may not start in - except for
1229 --add-file=<name> to add files whose names start in -.
1230 --format=<format>
1232 New in version 3.3.
1233 Specify the format of the archive to be created. Sup‐
1236 ported formats are: 7zip, gnutar, pax, paxr (restricted
1237 pax, default), and zip.
1238 --mtime=<date>
1240 New in version 3.1.
1241 Specify modification time recorded in tarball entries.
1244 --touch
1246 New in version 3.24.
1247 Use current local timestamp instead of extracting file
1250 timestamps from the archive.
1251 -- New in version 3.1.
1253 Stop interpreting options and treat all remaining argu‐
1256 ments as file names, even if they start with -.
1257 New in version 3.1: LZMA (7zip) support.
1259 New in version 3.15: The command now continues adding files to
1262 an archive even if some of the files are not readable. This be‐
1263 havior is more consistent with the classic tar tool. The command
1264 now also parses all flags, and if an invalid flag was provided,
1265 a warning is issued.
1266 time <command> [<args>...]
1269 Run <command> and display elapsed time (including overhead of
1270 CMake frontend).
1271 New in version 3.5: The command now properly passes arguments
1273 with spaces or special characters through to the child process.
1274 This may break scripts that worked around the bug with their own
1275 extra quoting or escaping.
1276 touch <file>...
1279 Creates <file> if file do not exist. If <file> exists, it is
1280 changing <file> access and modification times.
1281 touch_nocreate <file>...
1283 Touch a file if it exists but do not create it. If a file does
1284 not exist it will be silently ignored.
1285 true New in version 3.16.
1287 Do nothing, with an exit code of 0.
1290 Windows-specific Command-Line Tools
1292 The following cmake -E commands are available only on Windows:
1293 delete_regv <key>
1295 Delete Windows registry value.
1296 env_vs8_wince <sdkname>
1298 New in version 3.2.
1299 Displays a batch file which sets the environment for the pro‐
1302 vided Windows CE SDK installed in VS2005.
1303 env_vs9_wince <sdkname>
1305 New in version 3.2.
1306 Displays a batch file which sets the environment for the pro‐
1309 vided Windows CE SDK installed in VS2008.
1310 write_regv <key> <value>
1312 Write Windows registry value.
1313
1315 CMake provides a pkg-config like helper for Makefile-based projects:
1316 cmake --find-package [<options>]
1318 It searches a package using find_package() and prints the resulting
1320 flags to stdout. This can be used instead of pkg-config to find in‐
1321 stalled libraries in plain Makefile-based projects or in autoconf-based
1322 projects (via share/aclocal/cmake.m4).
1323 NOTE:
1325 This mode is not well-supported due to some technical limitations.
1326 It is kept for compatibility but should not be used in new projects.
1327
1329 CMake Presets provides a way to execute multiple build steps in order:
1330 cmake --workflow [<options>]
1332 The options are:
1334 --workflow
1336 Select a Workflow Preset using one of the following options.
1337 --preset <preset>, --preset=<preset>
1339 Use a workflow preset to specify a workflow. The project binary
1340 directory is inferred from the initial configure preset. The
1341 current working directory must contain CMake preset files. See
1342 preset for more details.
1343 --list-presets
1345 Lists the available workflow presets. The current working direc‐
1346 tory must contain CMake preset files.
1347 --fresh
1349 Perform a fresh configuration of the build tree. This removes
1350 any existing CMakeCache.txt file and associated CMakeFiles/ di‐
1351 rectory, and recreates them from scratch.
1352
1354 To print selected pages from the CMake documentation, use
1355 cmake --help[-<topic>]
1357 with one of the following options:
1359 -version [<file>], --version [<file>], /V [<file>]
1361 Show program name/version banner and exit. The output is
1362 printed to a named <file> if given.
1363 -h, -H, --help, -help, -usage, /?
1365 Print usage information and exit.
1366 Usage describes the basic command line interface and its op‐
1368 tions.
1369 --help-full [<file>]
1371 Print all help manuals and exit.
1372 All manuals are printed in a human-readable text format. The
1374 output is printed to a named <file> if given.
1375 --help-manual <man> [<file>]
1377 Print one help manual and exit.
1378 The specified manual is printed in a human-readable text format.
1380 The output is printed to a named <file> if given.
1381 --help-manual-list [<file>]
1383 List help manuals available and exit.
1384 The list contains all manuals for which help may be obtained by
1386 using the --help-manual option followed by a manual name. The
1387 output is printed to a named <file> if given.
1388 --help-command <cmd> [<file>]
1390 Print help for one command and exit.
1391 The cmake-commands(7) manual entry for <cmd> is printed in a hu‐
1393 man-readable text format. The output is printed to a named
1394 <file> if given.
1395 --help-command-list [<file>]
1397 List commands with help available and exit.
1398 The list contains all commands for which help may be obtained by
1400 using the --help-command option followed by a command name. The
1401 output is printed to a named <file> if given.
1402 --help-commands [<file>]
1404 Print cmake-commands manual and exit.
1405 The cmake-commands(7) manual is printed in a human-readable text
1407 format. The output is printed to a named <file> if given.
1408 --help-module <mod> [<file>]
1410 Print help for one module and exit.
1411 The cmake-modules(7) manual entry for <mod> is printed in a hu‐
1413 man-readable text format. The output is printed to a named
1414 <file> if given.
1415 --help-module-list [<file>]
1417 List modules with help available and exit.
1418 The list contains all modules for which help may be obtained by
1420 using the --help-module option followed by a module name. The
1421 output is printed to a named <file> if given.
1422 --help-modules [<file>]
1424 Print cmake-modules manual and exit.
1425 The cmake-modules(7) manual is printed in a human-readable text
1427 format. The output is printed to a named <file> if given.
1428 --help-policy <cmp> [<file>]
1430 Print help for one policy and exit.
1431 The cmake-policies(7) manual entry for <cmp> is printed in a hu‐
1433 man-readable text format. The output is printed to a named
1434 <file> if given.
1435 --help-policy-list [<file>]
1437 List policies with help available and exit.
1438 The list contains all policies for which help may be obtained by
1440 using the --help-policy option followed by a policy name. The
1441 output is printed to a named <file> if given.
1442 --help-policies [<file>]
1444 Print cmake-policies manual and exit.
1445 The cmake-policies(7) manual is printed in a human-readable text
1447 format. The output is printed to a named <file> if given.
1448 --help-property <prop> [<file>]
1450 Print help for one property and exit.
1451 The cmake-properties(7) manual entries for <prop> are printed in
1453 a human-readable text format. The output is printed to a named
1454 <file> if given.
1455 --help-property-list [<file>]
1457 List properties with help available and exit.
1458 The list contains all properties for which help may be obtained
1460 by using the --help-property option followed by a property name.
1461 The output is printed to a named <file> if given.
1462 --help-properties [<file>]
1464 Print cmake-properties manual and exit.
1465 The cmake-properties(7) manual is printed in a human-readable
1467 text format. The output is printed to a named <file> if given.
1468 --help-variable <var> [<file>]
1470 Print help for one variable and exit.
1471 The cmake-variables(7) manual entry for <var> is printed in a
1473 human-readable text format. The output is printed to a named
1474 <file> if given.
1475 --help-variable-list [<file>]
1477 List variables with help available and exit.
1478 The list contains all variables for which help may be obtained
1480 by using the --help-variable option followed by a variable name.
1481 The output is printed to a named <file> if given.
1482 --help-variables [<file>]
1484 Print cmake-variables manual and exit.
1485 The cmake-variables(7) manual is printed in a human-readable
1487 text format. The output is printed to a named <file> if given.
1488 To view the presets available for a project, use
1490 cmake <source-dir> --list-presets
1492
1494 Upon regular termination, the cmake executable returns the exit code 0.
1495 If termination is caused by the command message(FATAL_ERROR), or an‐
1497 other error condition, then a non-zero exit code is returned.
1498
1500 The following resources are available to get help using CMake:
1501 Home Page
1503 https://cmake.org
1504 The primary starting point for learning about CMake.
1506 Online Documentation and Community Resources
1508 https://cmake.org/documentation
1509 Links to available documentation and community resources may be
1511 found on this web page.
1512 Discourse Forum
1514 https://discourse.cmake.org
1515 The Discourse Forum hosts discussion and questions about CMake.
1517
1519 2000-2023 Kitware, Inc. and Contributors
15203.27.7 Oct 07, 2023 CMAKE(1)