1CMAKE(1) CMake CMAKE(1)
2
6 cmake - CMake Command-Line Reference
7
9 Generate a Project Buildsystem
10 cmake [<options>] <path-to-source>
11 cmake [<options>] <path-to-existing-build>
12 cmake [<options>] -S <path-to-source> -B <path-to-build>
13 Build a Project
15 cmake --build <dir> [<options>] [-- <build-tool-options>]
16 Open a Project
18 cmake --open <dir>
19 Run a Script
21 cmake [{-D <var>=<value>}...] -P <cmake-script-file>
22 Run a Command-Line Tool
24 cmake -E <command> [<options>]
25 Run the Find-Package Tool
27 cmake --find-package [<options>]
28 View Help
30 cmake --help[-<topic>]
31
33 The cmake executable is the command-line interface of the cross-plat‐
34 form buildsystem generator CMake. The above Synopsis lists various
35 actions the tool can perform as described in sections below.
36 To build a software project with CMake, Generate a Project Buildsystem.
38 Optionally use cmake to Build a Project or just run the corresponding
39 build tool (e.g. make) directly. cmake can also be used to View Help.
40 The other actions are meant for use by software developers writing
42 scripts in the CMake language to support their builds.
43 For graphical user interfaces that may be used in place of cmake, see
45 ccmake and cmake-gui. For command-line interfaces to the CMake testing
46 and packaging facilities, see ctest and cpack.
47 For more information on CMake at large, see also the links at the end
49 of this manual.
50
52 A buildsystem describes how to build a project’s executables and
53 libraries from its source code using a build tool to automate the
54 process. For example, a buildsystem may be a Makefile for use with a
55 command-line make tool or a project file for an Integrated Development
56 Environment (IDE). In order to avoid maintaining multiple such
57 buildsystems, a project may specify its buildsystem abstractly using
58 files written in the CMake language. From these files CMake generates
59 a preferred buildsystem locally for each user through a backend called
60 a generator.
61 To generate a buildsystem with CMake, the following must be selected:
63 Source Tree
65 The top-level directory containing source files provided by the
66 project. The project specifies its buildsystem using files as
67 described in the cmake-language(7) manual, starting with a
68 top-level file named CMakeLists.txt. These files specify build
69 targets and their dependencies as described in the
70 cmake-buildsystem(7) manual.
71 Build Tree
73 The top-level directory in which buildsystem files and build
74 output artifacts (e.g. executables and libraries) are to be
75 stored. CMake will write a CMakeCache.txt file to identify the
76 directory as a build tree and store persistent information such
77 as buildsystem configuration options.
78 To maintain a pristine source tree, perform an out-of-source
80 build by using a separate dedicated build tree. An in-source
81 build in which the build tree is placed in the same directory as
82 the source tree is also supported, but discouraged.
83 Generator
85 This chooses the kind of buildsystem to generate. See the
86 cmake-generators(7) manual for documentation of all generators.
87 Run cmake --help to see a list of generators available locally.
88 Optionally use the -G option below to specify a generator, or
89 simply accept the default CMake chooses for the current plat‐
90 form.
91 When using one of the Command-Line Build Tool Generators CMake
93 expects that the environment needed by the compiler toolchain is
94 already configured in the shell. When using one of the IDE
95 Build Tool Generators, no particular environment is needed.
96
98 Run CMake with one of the following command signatures to specify the
99 source and build trees and generate a buildsystem:
100 cmake [<options>] <path-to-source>
102 Uses the current working directory as the build tree, and
103 <path-to-source> as the source tree. The specified path may be
104 absolute or relative to the current working directory. The
105 source tree must contain a CMakeLists.txt file and must not con‐
106 tain a CMakeCache.txt file because the latter identifies an
107 existing build tree. For example:
108 $ mkdir build ; cd build
110 $ cmake ../src
111 cmake [<options>] <path-to-existing-build>
113 Uses <path-to-existing-build> as the build tree, and loads the
114 path to the source tree from its CMakeCache.txt file, which must
115 have already been generated by a previous run of CMake. The
116 specified path may be absolute or relative to the current work‐
117 ing directory. For example:
118 $ cd build
120 $ cmake .
121 cmake [<options>] -S <path-to-source> -B <path-to-build>
123 Uses <path-to-build> as the build tree and <path-to-source> as
124 the source tree. The specified paths may be absolute or rela‐
125 tive to the current working directory. The source tree must
126 contain a CMakeLists.txt file. The build tree will be created
127 automatically if it does not already exist. For example:
128 $ cmake -S src -B build
130 In all cases the <options> may be zero or more of the Options below.
132 After generating a buildsystem one may use the corresponding native
134 build tool to build the project. For example, after using the Unix
135 Makefiles generator one may run make directly:
136 $ make
138 $ make install
139 Alternatively, one may use cmake to Build a Project by automatically
141 choosing and invoking the appropriate native build tool.
142 Options
144 -S <path-to-source>
145 Path to root directory of the CMake project to build.
146 -B <path-to-build>
148 Path to directory which CMake will use as the root of build
149 directory.
150 If the directory doesn’t already exist CMake will make it.
152 -C <initial-cache>
154 Pre-load a script to populate the cache.
155 When cmake is first run in an empty build tree, it creates a
157 CMakeCache.txt file and populates it with customizable settings
158 for the project. This option may be used to specify a file from
159 which to load cache entries before the first pass through the
160 project’s cmake listfiles. The loaded entries take priority
161 over the project’s default values. The given file should be a
162 CMake script containing SET commands that use the CACHE option,
163 not a cache-format file.
164 -D <var>:<type>=<value>, -D <var>=<value>
166 Create or update a cmake cache entry.
167 When cmake is first run in an empty build tree, it creates a
169 CMakeCache.txt file and populates it with customizable settings
170 for the project. This option may be used to specify a setting
171 that takes priority over the project’s default value. The
172 option may be repeated for as many cache entries as desired.
173 If the :<type> portion is given it must be one of the types
175 specified by the set() command documentation for its CACHE sig‐
176 nature. If the :<type> portion is omitted the entry will be
177 created with no type if it does not exist with a type already.
178 If a command in the project sets the type to PATH or FILEPATH
179 then the <value> will be converted to an absolute path.
180 This option may also be given as a single argument:
182 -D<var>:<type>=<value> or -D<var>=<value>.
183 -U <globbing_expr>
185 Remove matching entries from CMake cache.
186 This option may be used to remove one or more variables from the
188 CMakeCache.txt file, globbing expressions using * and ? are sup‐
189 ported. The option may be repeated for as many cache entries as
190 desired.
191 Use with care, you can make your CMakeCache.txt non-working.
193 -G <generator-name>
195 Specify a build system generator.
196 CMake may support multiple native build systems on certain plat‐
198 forms. A generator is responsible for generating a particular
199 build system. Possible generator names are specified in the
200 cmake-generators(7) manual.
201 -T <toolset-spec>
203 Toolset specification for the generator, if supported.
204 Some CMake generators support a toolset specification to tell
206 the native build system how to choose a compiler. See the
207 CMAKE_GENERATOR_TOOLSET variable for details.
208 -A <platform-name>
210 Specify platform name if supported by generator.
211 Some CMake generators support a platform name to be given to the
213 native build system to choose a compiler or SDK. See the
214 CMAKE_GENERATOR_PLATFORM variable for details.
215 -Wno-dev
217 Suppress developer warnings.
218 Suppress warnings that are meant for the author of the CMake‐
220 Lists.txt files. By default this will also turn off deprecation
221 warnings.
222 -Wdev Enable developer warnings.
224 Enable warnings that are meant for the author of the CMake‐
226 Lists.txt files. By default this will also turn on deprecation
227 warnings.
228 -Werror=dev
230 Make developer warnings errors.
231 Make warnings that are meant for the author of the CMake‐
233 Lists.txt files errors. By default this will also turn on depre‐
234 cated warnings as errors.
235 -Wno-error=dev
237 Make developer warnings not errors.
238 Make warnings that are meant for the author of the CMake‐
240 Lists.txt files not errors. By default this will also turn off
241 deprecated warnings as errors.
242 -Wdeprecated
244 Enable deprecated functionality warnings.
245 Enable warnings for usage of deprecated functionality, that are
247 meant for the author of the CMakeLists.txt files.
248 -Wno-deprecated
250 Suppress deprecated functionality warnings.
251 Suppress warnings for usage of deprecated functionality, that
253 are meant for the author of the CMakeLists.txt files.
254 -Werror=deprecated
256 Make deprecated macro and function warnings errors.
257 Make warnings for usage of deprecated macros and functions, that
259 are meant for the author of the CMakeLists.txt files, errors.
260 -Wno-error=deprecated
262 Make deprecated macro and function warnings not errors.
263 Make warnings for usage of deprecated macros and functions, that
265 are meant for the author of the CMakeLists.txt files, not
266 errors.
267 -L[A][H]
269 List non-advanced cached variables.
270 List cache variables will run CMake and list all the variables
272 from the CMake cache that are not marked as INTERNAL or
273 ADVANCED. This will effectively display current CMake settings,
274 which can then be changed with -D option. Changing some of the
275 variables may result in more variables being created. If A is
276 specified, then it will display also advanced variables. If H
277 is specified, it will also display help for each variable.
278 -N View mode only.
280 Only load the cache. Do not actually run configure and generate
282 steps.
283 --graphviz=[file]
285 Generate graphviz of dependencies, see CMakeGraphVizOptions for
286 more.
287 Generate a graphviz input file that will contain all the library
289 and executable dependencies in the project. See the documenta‐
290 tion for CMakeGraphVizOptions for more details.
291 --system-information [file]
293 Dump information about this system.
294 Dump a wide range of information about the current system. If
296 run from the top of a binary tree for a CMake project it will
297 dump additional information such as the cache, log files etc.
298 --debug-trycompile
300 Do not delete the try_compile build tree. Only useful on one
301 try_compile at a time.
302 Do not delete the files and directories created for try_compile
304 calls. This is useful in debugging failed try_compiles. It may
305 however change the results of the try-compiles as old junk from
306 a previous try-compile may cause a different test to either pass
307 or fail incorrectly. This option is best used for one try-com‐
308 pile at a time, and only when debugging.
309 --debug-output
311 Put cmake in a debug mode.
312 Print extra information during the cmake run like stack traces
314 with message(send_error ) calls.
315 --trace
317 Put cmake in trace mode.
318 Print a trace of all calls made and from where.
320 --trace-expand
322 Put cmake in trace mode.
323 Like --trace, but with variables expanded.
325 --trace-source=<file>
327 Put cmake in trace mode, but output only lines of a specified
328 file.
329 Multiple options are allowed.
331 --warn-uninitialized
333 Warn about uninitialized values.
334 Print a warning when an uninitialized variable is used.
336 --warn-unused-vars
338 Warn about unused variables.
339 Find variables that are declared or set, but not used.
341 --no-warn-unused-cli
343 Don’t warn about command line options.
344 Don’t find variables that are declared on the command line, but
346 not used.
347 --check-system-vars
349 Find problems with variable usage in system files.
350 Normally, unused and uninitialized variables are searched for
352 only in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells
353 CMake to warn about other files as well.
354
356 CMake provides a command-line signature to build an already-generated
357 project binary tree:
358 cmake --build <dir> [<options>] [-- <build-tool-options>]
360 This abstracts a native build tool’s command-line interface with the
362 following options:
363 --build <dir>
365 Project binary directory to be built. This is required and must
366 be first.
367 -j [<jobs>], --parallel [<jobs>]
369 The maximum number of concurrent processes to use when building.
370 If <jobs> is omitted the native build tool’s default number is
371 used.
372 The CMAKE_BUILD_PARALLEL_LEVEL environment variable, if set,
374 specifies a default parallel level when this option is not
375 given.
376 --target <tgt>
378 Build <tgt> instead of default targets. May only be specified
379 once.
380 --config <cfg>
382 For multi-configuration tools, choose configuration <cfg>.
383 --clean-first
385 Build target clean first, then build. (To clean only, use
386 --target clean.)
387 --use-stderr
389 Ignored. Behavior is default in CMake >= 3.0.
390 -v, --verbose
392 Enable verbose output - if supported - including the build com‐
393 mands to be executed.
394 This option can be omitted if VERBOSE environment variable or
396 CMAKE_VERBOSE_MAKEFILE cached variable is set.
397 -- Pass remaining options to the native tool.
399 Run cmake --build with no options for quick help.
401
403 cmake --open <dir>
404 Open the generated project in the associated application. This is only
406 supported by some generators.
407
409 cmake [{-D <var>=<value>}...] -P <cmake-script-file>
410 Process the given cmake file as a script written in the CMake language.
412 No configure or generate step is performed and the cache is not modi‐
413 fied. If variables are defined using -D, this must be done before the
414 -P argument.
415
417 CMake provides builtin command-line tools through the signature
418 cmake -E <command> [<options>]
420 Run cmake -E or cmake -E help for a summary of commands. Available
422 commands are:
423 capabilities
425 Report cmake capabilities in JSON format. The output is a JSON
426 object with the following keys:
427 version
429 A JSON object with version information. Keys are:
430 string The full version string as displayed by cmake
432 --version.
433 major The major version number in integer form.
435 minor The minor version number in integer form.
437 patch The patch level in integer form.
439 suffix The cmake version suffix string.
441 isDirty
443 A bool that is set if the cmake build is from a
444 dirty tree.
445 generators
447 A list available generators. Each generator is a JSON
448 object with the following keys:
449 name A string containing the name of the generator.
451 toolsetSupport
453 true if the generator supports toolsets and false
454 otherwise.
455 platformSupport
457 true if the generator supports platforms and false
458 otherwise.
459 extraGenerators
461 A list of strings with all the extra generators
462 compatible with the generator.
463 serverMode
465 true if cmake supports server-mode and false otherwise.
466 chdir <dir> <cmd> [<arg>...]
468 Change the current working directory and run a command.
469 compare_files [--ignore-eol] <file1> <file2>
471 Check if <file1> is same as <file2>. If files are the same, then
472 returns 0, if not it returns 1. The --ignore-eol option implies
473 line-wise comparison and ignores LF/CRLF differences.
474 copy <file>... <destination>
476 Copy files to <destination> (either file or directory). If mul‐
477 tiple files are specified, the <destination> must be directory
478 and it must exist. Wildcards are not supported.
479 copy_directory <dir>... <destination>
481 Copy directories to <destination> directory. If <destination>
482 directory does not exist it will be created.
483 copy_if_different <file>... <destination>
485 Copy files to <destination> (either file or directory) if they
486 have changed. If multiple files are specified, the <destina‐
487 tion> must be directory and it must exist.
488 echo [<string>...]
490 Displays arguments as text.
491 echo_append [<string>...]
493 Displays arguments as text but no new line.
494 env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...
496 Run command in a modified environment.
497 environment
499 Display the current environment variables.
500 make_directory <dir>...
502 Create <dir> directories. If necessary, create parent directo‐
503 ries too. If a directory already exists it will be silently
504 ignored.
505 md5sum <file>...
507 Create MD5 checksum of files in md5sum compatible format:
508 351abe79cd3800b38cdfb25d45015a15 file1.txt
510 052f86c15bbde68af55c7f7b340ab639 file2.txt
511 sha1sum <file>...
513 Create SHA1 checksum of files in sha1sum compatible format:
514 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt
516 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt
517 sha224sum <file>...
519 Create SHA224 checksum of files in sha224sum compatible format:
520 b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt
522 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt
523 sha256sum <file>...
525 Create SHA256 checksum of files in sha256sum compatible format:
526 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt
528 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt
529 sha384sum <file>...
531 Create SHA384 checksum of files in sha384sum compatible format:
532 acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt
534 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt
535 sha512sum <file>...
537 Create SHA512 checksum of files in sha512sum compatible format:
538 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt
540 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt
541 remove [-f] <file>...
543 Remove the file(s). If any of the listed files already do not
544 exist, the command returns a non-zero exit code, but no message
545 is logged. The -f option changes the behavior to return a zero
546 exit code (i.e. success) in such situations instead.
547 remove_directory <dir>
549 Remove a directory and its contents. If a directory does not
550 exist it will be silently ignored.
551 rename <oldname> <newname>
553 Rename a file or directory (on one volume).
554 server Launch cmake-server(7) mode.
556 sleep <number>...
558 Sleep for given number of seconds.
559 tar [cxt][vf][zjJ] file.tar [<options>] [--] [<file>...]
561 Create or extract a tar or zip archive. Options are:
562 -- Stop interpreting options and treat all remaining argu‐
564 ments as file names even if they start in -.
565 --files-from=<file>
567 Read file names from the given file, one per line. Blank
568 lines are ignored. Lines may not start in - except for
569 --add-file=<name> to add files whose names start in -.
570 --mtime=<date>
572 Specify modification time recorded in tarball entries.
573 --format=<format>
575 Specify the format of the archive to be created. Sup‐
576 ported formats are: 7zip, gnutar, pax, paxr (restricted
577 pax, default), and zip.
578 time <command> [<args>...]
580 Run command and display elapsed time.
581 touch <file>
583 Touch a file.
584 touch_nocreate <file>
586 Touch a file if it exists but do not create it. If a file does
587 not exist it will be silently ignored.
588 create_symlink <old> <new>
590 Create a symbolic link <new> naming <old>.
591 NOTE:
593 Path to where <new> symbolic link will be created has to exist
594 beforehand.
595 Windows-specific Command-Line Tools
597 The following cmake -E commands are available only on Windows:
598 delete_regv <key>
600 Delete Windows registry value.
601 env_vs8_wince <sdkname>
603 Displays a batch file which sets the environment for the pro‐
604 vided Windows CE SDK installed in VS2005.
605 env_vs9_wince <sdkname>
607 Displays a batch file which sets the environment for the pro‐
608 vided Windows CE SDK installed in VS2008.
609 write_regv <key> <value>
611 Write Windows registry value.
612
614 CMake provides a pkg-config like helper for Makefile-based projects:
615 cmake --find-package [<options>]
617 It searches a package using find_package() and prints the resulting
619 flags to stdout. This can be used instead of pkg-config to find
620 installed libraries in plain Makefile-based projects or in auto‐
621 conf-based projects (via share/aclocal/cmake.m4).
622 NOTE:
624 This mode is not well-supported due to some technical limitations.
625 It is kept for compatibility but should not be used in new projects.
626
628 To print selected pages from the CMake documentation, use
629 cmake --help[-<topic>]
631 with one of the following options:
633 --help,-help,-usage,-h,-H,/?
635 Print usage information and exit.
636 Usage describes the basic command line interface and its
638 options.
639 --version,-version,/V [<f>]
641 Show program name/version banner and exit.
642 If a file is specified, the version is written into it. The
644 help is printed to a named <f>ile if given.
645 --help-full [<f>]
647 Print all help manuals and exit.
648 All manuals are printed in a human-readable text format. The
650 help is printed to a named <f>ile if given.
651 --help-manual <man> [<f>]
653 Print one help manual and exit.
654 The specified manual is printed in a human-readable text format.
656 The help is printed to a named <f>ile if given.
657 --help-manual-list [<f>]
659 List help manuals available and exit.
660 The list contains all manuals for which help may be obtained by
662 using the --help-manual option followed by a manual name. The
663 help is printed to a named <f>ile if given.
664 --help-command <cmd> [<f>]
666 Print help for one command and exit.
667 The cmake-commands(7) manual entry for <cmd> is printed in a
669 human-readable text format. The help is printed to a named
670 <f>ile if given.
671 --help-command-list [<f>]
673 List commands with help available and exit.
674 The list contains all commands for which help may be obtained by
676 using the --help-command option followed by a command name. The
677 help is printed to a named <f>ile if given.
678 --help-commands [<f>]
680 Print cmake-commands manual and exit.
681 The cmake-commands(7) manual is printed in a human-readable text
683 format. The help is printed to a named <f>ile if given.
684 --help-module <mod> [<f>]
686 Print help for one module and exit.
687 The cmake-modules(7) manual entry for <mod> is printed in a
689 human-readable text format. The help is printed to a named
690 <f>ile if given.
691 --help-module-list [<f>]
693 List modules with help available and exit.
694 The list contains all modules for which help may be obtained by
696 using the --help-module option followed by a module name. The
697 help is printed to a named <f>ile if given.
698 --help-modules [<f>]
700 Print cmake-modules manual and exit.
701 The cmake-modules(7) manual is printed in a human-readable text
703 format. The help is printed to a named <f>ile if given.
704 --help-policy <cmp> [<f>]
706 Print help for one policy and exit.
707 The cmake-policies(7) manual entry for <cmp> is printed in a
709 human-readable text format. The help is printed to a named
710 <f>ile if given.
711 --help-policy-list [<f>]
713 List policies with help available and exit.
714 The list contains all policies for which help may be obtained by
716 using the --help-policy option followed by a policy name. The
717 help is printed to a named <f>ile if given.
718 --help-policies [<f>]
720 Print cmake-policies manual and exit.
721 The cmake-policies(7) manual is printed in a human-readable text
723 format. The help is printed to a named <f>ile if given.
724 --help-property <prop> [<f>]
726 Print help for one property and exit.
727 The cmake-properties(7) manual entries for <prop> are printed in
729 a human-readable text format. The help is printed to a named
730 <f>ile if given.
731 --help-property-list [<f>]
733 List properties with help available and exit.
734 The list contains all properties for which help may be obtained
736 by using the --help-property option followed by a property name.
737 The help is printed to a named <f>ile if given.
738 --help-properties [<f>]
740 Print cmake-properties manual and exit.
741 The cmake-properties(7) manual is printed in a human-readable
743 text format. The help is printed to a named <f>ile if given.
744 --help-variable <var> [<f>]
746 Print help for one variable and exit.
747 The cmake-variables(7) manual entry for <var> is printed in a
749 human-readable text format. The help is printed to a named
750 <f>ile if given.
751 --help-variable-list [<f>]
753 List variables with help available and exit.
754 The list contains all variables for which help may be obtained
756 by using the --help-variable option followed by a variable name.
757 The help is printed to a named <f>ile if given.
758 --help-variables [<f>]
760 Print cmake-variables manual and exit.
761 The cmake-variables(7) manual is printed in a human-readable
763 text format. The help is printed to a named <f>ile if given.
764
766 The following resources are available to get help using CMake:
767 Home Page
769 https://cmake.org
770 The primary starting point for learning about CMake.
772 Online Documentation and Community Resources
774 https://cmake.org/documentation
775 Links to available documentation and community resources may be
777 found on this web page.
778 Mailing List
780 https://cmake.org/mailing-lists
781 For help and discussion about using cmake, a mailing list is
783 provided at cmake@cmake.org. The list is member-post-only but
784 one may sign up on the CMake web page. Please first read the
785 full documentation at https://cmake.org before posting questions
786 to the list.
787
789 2000-2019 Kitware, Inc. and Contributors
7903.14.5 Jun 01, 2019 CMAKE(1)