1CMAKE(1) CMake CMAKE(1)
2
6 cmake - CMake Command-Line Reference
7
9 cmake [<options>] (<path-to-source> | <path-to-existing-build>)
10 cmake [(-D <var>=<value>)...] -P <cmake-script-file>
11 cmake --build <dir> [<options>...] [-- <build-tool-options>...]
12 cmake --open <dir>
13 cmake -E <command> [<options>...]
14 cmake --find-package <options>...
15
17 The “cmake” executable is the CMake command-line interface. It may be
18 used to configure projects in scripts. Project configuration settings
19 may be specified on the command line with the -D option.
20 CMake is a cross-platform build system generator. Projects specify
22 their build process with platform-independent CMake listfiles included
23 in each directory of a source tree with the name CMakeLists.txt. Users
24 build a project by using CMake to generate a build system for a native
25 tool on their platform.
26
28 -C <initial-cache>
29 Pre-load a script to populate the cache.
30 When cmake is first run in an empty build tree, it creates a
32 CMakeCache.txt file and populates it with customizable settings
33 for the project. This option may be used to specify a file from
34 which to load cache entries before the first pass through the
35 project’s cmake listfiles. The loaded entries take priority
36 over the project’s default values. The given file should be a
37 CMake script containing SET commands that use the CACHE option,
38 not a cache-format file.
39 -D <var>:<type>=<value>, -D <var>=<value>
41 Create a cmake cache entry.
42 When cmake is first run in an empty build tree, it creates a
44 CMakeCache.txt file and populates it with customizable settings
45 for the project. This option may be used to specify a setting
46 that takes priority over the project’s default value. The
47 option may be repeated for as many cache entries as desired.
48 If the :<type> portion is given it must be one of the types
50 specified by the set() command documentation for its CACHE sig‐
51 nature. If the :<type> portion is omitted the entry will be
52 created with no type if it does not exist with a type already.
53 If a command in the project sets the type to PATH or FILEPATH
54 then the <value> will be converted to an absolute path.
55 This option may also be given as a single argument:
57 -D<var>:<type>=<value> or -D<var>=<value>.
58 -U <globbing_expr>
60 Remove matching entries from CMake cache.
61 This option may be used to remove one or more variables from the
63 CMakeCache.txt file, globbing expressions using * and ? are sup‐
64 ported. The option may be repeated for as many cache entries as
65 desired.
66 Use with care, you can make your CMakeCache.txt non-working.
68 -G <generator-name>
70 Specify a build system generator.
71 CMake may support multiple native build systems on certain plat‐
73 forms. A generator is responsible for generating a particular
74 build system. Possible generator names are specified in the
75 cmake-generators(7) manual.
76 -T <toolset-spec>
78 Toolset specification for the generator, if supported.
79 Some CMake generators support a toolset specification to tell
81 the native build system how to choose a compiler. See the
82 CMAKE_GENERATOR_TOOLSET variable for details.
83 -A <platform-name>
85 Specify platform name if supported by generator.
86 Some CMake generators support a platform name to be given to the
88 native build system to choose a compiler or SDK. See the
89 CMAKE_GENERATOR_PLATFORM variable for details.
90 -Wno-dev
92 Suppress developer warnings.
93 Suppress warnings that are meant for the author of the CMake‐
95 Lists.txt files. By default this will also turn off deprecation
96 warnings.
97 -Wdev Enable developer warnings.
99 Enable warnings that are meant for the author of the CMake‐
101 Lists.txt files. By default this will also turn on deprecation
102 warnings.
103 -Werror=dev
105 Make developer warnings errors.
106 Make warnings that are meant for the author of the CMake‐
108 Lists.txt files errors. By default this will also turn on depre‐
109 cated warnings as errors.
110 -Wno-error=dev
112 Make developer warnings not errors.
113 Make warnings that are meant for the author of the CMake‐
115 Lists.txt files not errors. By default this will also turn off
116 deprecated warnings as errors.
117 -Wdeprecated
119 Enable deprecated functionality warnings.
120 Enable warnings for usage of deprecated functionality, that are
122 meant for the author of the CMakeLists.txt files.
123 -Wno-deprecated
125 Suppress deprecated functionality warnings.
126 Suppress warnings for usage of deprecated functionality, that
128 are meant for the author of the CMakeLists.txt files.
129 -Werror=deprecated
131 Make deprecated macro and function warnings errors.
132 Make warnings for usage of deprecated macros and functions, that
134 are meant for the author of the CMakeLists.txt files, errors.
135 -Wno-error=deprecated
137 Make deprecated macro and function warnings not errors.
138 Make warnings for usage of deprecated macros and functions, that
140 are meant for the author of the CMakeLists.txt files, not
141 errors.
142 -E <command> [<options>...]
144 See Command-Line Tool Mode.
145 -L[A][H]
147 List non-advanced cached variables.
148 List cache variables will run CMake and list all the variables
150 from the CMake cache that are not marked as INTERNAL or
151 ADVANCED. This will effectively display current CMake settings,
152 which can then be changed with -D option. Changing some of the
153 variables may result in more variables being created. If A is
154 specified, then it will display also advanced variables. If H
155 is specified, it will also display help for each variable.
156 --build <dir>
158 See Build Tool Mode.
159 --open <dir>
161 Open the generated project in the associated application. This
162 is only supported by some generators.
163 -N View mode only.
165 Only load the cache. Do not actually run configure and generate
167 steps.
168 -P <file>
170 Process script mode.
171 Process the given cmake file as a script written in the CMake
173 language. No configure or generate step is performed and the
174 cache is not modified. If variables are defined using -D, this
175 must be done before the -P argument.
176 --find-package
178 See Find-Package Tool Mode.
179 --graphviz=[file]
181 Generate graphviz of dependencies, see CMakeGraphVizOptions for
182 more.
183 Generate a graphviz input file that will contain all the library
185 and executable dependencies in the project. See the documenta‐
186 tion for CMakeGraphVizOptions for more details.
187 --system-information [file]
189 Dump information about this system.
190 Dump a wide range of information about the current system. If
192 run from the top of a binary tree for a CMake project it will
193 dump additional information such as the cache, log files etc.
194 --debug-trycompile
196 Do not delete the try_compile build tree. Only useful on one
197 try_compile at a time.
198 Do not delete the files and directories created for try_compile
200 calls. This is useful in debugging failed try_compiles. It may
201 however change the results of the try-compiles as old junk from
202 a previous try-compile may cause a different test to either pass
203 or fail incorrectly. This option is best used for one try-com‐
204 pile at a time, and only when debugging.
205 --debug-output
207 Put cmake in a debug mode.
208 Print extra information during the cmake run like stack traces
210 with message(send_error ) calls.
211 --trace
213 Put cmake in trace mode.
214 Print a trace of all calls made and from where.
216 --trace-expand
218 Put cmake in trace mode.
219 Like --trace, but with variables expanded.
221 --trace-source=<file>
223 Put cmake in trace mode, but output only lines of a specified
224 file.
225 Multiple options are allowed.
227 --warn-uninitialized
229 Warn about uninitialized values.
230 Print a warning when an uninitialized variable is used.
232 --warn-unused-vars
234 Warn about unused variables.
235 Find variables that are declared or set, but not used.
237 --no-warn-unused-cli
239 Don’t warn about command line options.
240 Don’t find variables that are declared on the command line, but
242 not used.
243 --check-system-vars
245 Find problems with variable usage in system files.
246 Normally, unused and uninitialized variables are searched for
248 only in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells
249 CMake to warn about other files as well.
250 --help,-help,-usage,-h,-H,/?
252 Print usage information and exit.
253 Usage describes the basic command line interface and its
255 options.
256 --version,-version,/V [<f>]
258 Show program name/version banner and exit.
259 If a file is specified, the version is written into it. The
261 help is printed to a named <f>ile if given.
262 --help-full [<f>]
264 Print all help manuals and exit.
265 All manuals are printed in a human-readable text format. The
267 help is printed to a named <f>ile if given.
268 --help-manual <man> [<f>]
270 Print one help manual and exit.
271 The specified manual is printed in a human-readable text format.
273 The help is printed to a named <f>ile if given.
274 --help-manual-list [<f>]
276 List help manuals available and exit.
277 The list contains all manuals for which help may be obtained by
279 using the --help-manual option followed by a manual name. The
280 help is printed to a named <f>ile if given.
281 --help-command <cmd> [<f>]
283 Print help for one command and exit.
284 The cmake-commands(7) manual entry for <cmd> is printed in a
286 human-readable text format. The help is printed to a named
287 <f>ile if given.
288 --help-command-list [<f>]
290 List commands with help available and exit.
291 The list contains all commands for which help may be obtained by
293 using the --help-command option followed by a command name. The
294 help is printed to a named <f>ile if given.
295 --help-commands [<f>]
297 Print cmake-commands manual and exit.
298 The cmake-commands(7) manual is printed in a human-readable text
300 format. The help is printed to a named <f>ile if given.
301 --help-module <mod> [<f>]
303 Print help for one module and exit.
304 The cmake-modules(7) manual entry for <mod> is printed in a
306 human-readable text format. The help is printed to a named
307 <f>ile if given.
308 --help-module-list [<f>]
310 List modules with help available and exit.
311 The list contains all modules for which help may be obtained by
313 using the --help-module option followed by a module name. The
314 help is printed to a named <f>ile if given.
315 --help-modules [<f>]
317 Print cmake-modules manual and exit.
318 The cmake-modules(7) manual is printed in a human-readable text
320 format. The help is printed to a named <f>ile if given.
321 --help-policy <cmp> [<f>]
323 Print help for one policy and exit.
324 The cmake-policies(7) manual entry for <cmp> is printed in a
326 human-readable text format. The help is printed to a named
327 <f>ile if given.
328 --help-policy-list [<f>]
330 List policies with help available and exit.
331 The list contains all policies for which help may be obtained by
333 using the --help-policy option followed by a policy name. The
334 help is printed to a named <f>ile if given.
335 --help-policies [<f>]
337 Print cmake-policies manual and exit.
338 The cmake-policies(7) manual is printed in a human-readable text
340 format. The help is printed to a named <f>ile if given.
341 --help-property <prop> [<f>]
343 Print help for one property and exit.
344 The cmake-properties(7) manual entries for <prop> are printed in
346 a human-readable text format. The help is printed to a named
347 <f>ile if given.
348 --help-property-list [<f>]
350 List properties with help available and exit.
351 The list contains all properties for which help may be obtained
353 by using the --help-property option followed by a property name.
354 The help is printed to a named <f>ile if given.
355 --help-properties [<f>]
357 Print cmake-properties manual and exit.
358 The cmake-properties(7) manual is printed in a human-readable
360 text format. The help is printed to a named <f>ile if given.
361 --help-variable <var> [<f>]
363 Print help for one variable and exit.
364 The cmake-variables(7) manual entry for <var> is printed in a
366 human-readable text format. The help is printed to a named
367 <f>ile if given.
368 --help-variable-list [<f>]
370 List variables with help available and exit.
371 The list contains all variables for which help may be obtained
373 by using the --help-variable option followed by a variable name.
374 The help is printed to a named <f>ile if given.
375 --help-variables [<f>]
377 Print cmake-variables manual and exit.
378 The cmake-variables(7) manual is printed in a human-readable
380 text format. The help is printed to a named <f>ile if given.
381
383 CMake provides a command-line signature to build an already-generated
384 project binary tree:
385 cmake --build <dir> [<options>...] [-- <build-tool-options>...]
387 This abstracts a native build tool’s command-line interface with the
389 following options:
390 --build <dir>
392 Project binary directory to be built. This is required and must
393 be first.
394 --target <tgt>
396 Build <tgt> instead of default targets. May only be specified
397 once.
398 --config <cfg>
400 For multi-configuration tools, choose configuration <cfg>.
401 --clean-first
403 Build target clean first, then build. (To clean only, use
404 --target clean.)
405 --use-stderr
407 Ignored. Behavior is default in CMake >= 3.0.
408 -- Pass remaining options to the native tool.
410 Run cmake --build with no options for quick help.
412
414 CMake provides builtin command-line tools through the signature:
415 cmake -E <command> [<options>...]
417 Run cmake -E or cmake -E help for a summary of commands. Available
419 commands are:
420 capabilities
422 Report cmake capabilities in JSON format. The output is a JSON
423 object with the following keys:
424 version
426 A JSON object with version information. Keys are:
427 string The full version string as displayed by cmake
429 --version.
430 major The major version number in integer form.
432 minor The minor version number in integer form.
434 patch The patch level in integer form.
436 suffix The cmake version suffix string.
438 isDirty
440 A bool that is set if the cmake build is from a
441 dirty tree.
442 generators
444 A list available generators. Each generator is a JSON
445 object with the following keys:
446 name A string containing the name of the generator.
448 toolsetSupport
450 true if the generator supports toolsets and false
451 otherwise.
452 platformSupport
454 true if the generator supports platforms and false
455 otherwise.
456 extraGenerators
458 A list of strings with all the extra generators
459 compatible with the generator.
460 serverMode
462 true if cmake supports server-mode and false otherwise.
463 chdir <dir> <cmd> [<arg>...]
465 Change the current working directory and run a command.
466 compare_files <file1> <file2>
468 Check if <file1> is same as <file2>. If files are the same, then
469 returns 0, if not it returns 1.
470 copy <file>... <destination>
472 Copy files to <destination> (either file or directory). If mul‐
473 tiple files are specified, the <destination> must be directory
474 and it must exist. Wildcards are not supported.
475 copy_directory <dir>... <destination>
477 Copy directories to <destination> directory. If <destination>
478 directory does not exist it will be created.
479 copy_if_different <file>... <destination>
481 Copy files to <destination> (either file or directory) if they
482 have changed. If multiple files are specified, the <destina‐
483 tion> must be directory and it must exist.
484 echo [<string>...]
486 Displays arguments as text.
487 echo_append [<string>...]
489 Displays arguments as text but no new line.
490 env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...
492 Run command in a modified environment.
493 environment
495 Display the current environment variables.
496 make_directory <dir>...
498 Create <dir> directories. If necessary, create parent directo‐
499 ries too. If a directory already exists it will be silently
500 ignored.
501 md5sum <file>...
503 Create MD5 checksum of files in md5sum compatible format:
504 351abe79cd3800b38cdfb25d45015a15 file1.txt
506 052f86c15bbde68af55c7f7b340ab639 file2.txt
507 sha1sum <file>...
509 Create SHA1 checksum of files in sha1sum compatible format:
510 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt
512 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt
513 sha224sum <file>...
515 Create SHA224 checksum of files in sha224sum compatible format:
516 b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt
518 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt
519 sha256sum <file>...
521 Create SHA256 checksum of files in sha256sum compatible format:
522 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt
524 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt
525 sha384sum <file>...
527 Create SHA384 checksum of files in sha384sum compatible format:
528 acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt
530 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt
531 sha512sum <file>...
533 Create SHA512 checksum of files in sha512sum compatible format:
534 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt
536 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt
537 remove [-f] <file>...
539 Remove the file(s). If any of the listed files already do not
540 exist, the command returns a non-zero exit code, but no message
541 is logged. The -f option changes the behavior to return a zero
542 exit code (i.e. success) in such situations instead.
543 remove_directory <dir>
545 Remove a directory and its contents. If a directory does not
546 exist it will be silently ignored.
547 rename <oldname> <newname>
549 Rename a file or directory (on one volume).
550 server Launch cmake-server(7) mode.
552 sleep <number>...
554 Sleep for given number of seconds.
555 tar [cxt][vf][zjJ] file.tar [<options>...] [--] [<file>...]
557 Create or extract a tar or zip archive. Options are:
558 -- Stop interpreting options and treat all remaining argu‐
560 ments as file names even if they start in -.
561 --files-from=<file>
563 Read file names from the given file, one per line. Blank
564 lines are ignored. Lines may not start in - except for
565 --add-file=<name> to add files whose names start in -.
566 --mtime=<date>
568 Specify modification time recorded in tarball entries.
569 --format=<format>
571 Specify the format of the archive to be created. Sup‐
572 ported formats are: 7zip, gnutar, pax, paxr (restricted
573 pax, default), and zip.
574 time <command> [<args>...]
576 Run command and display elapsed time.
577 touch <file>
579 Touch a file.
580 touch_nocreate <file>
582 Touch a file if it exists but do not create it. If a file does
583 not exist it will be silently ignored.
584 UNIX-specific Command-Line Tools
586 The following cmake -E commands are available only on UNIX:
587 create_symlink <old> <new>
589 Create a symbolic link <new> naming <old>.
590 NOTE:
592 Path to where <new> symbolic link will be created has to exist
593 beforehand.
594 Windows-specific Command-Line Tools
596 The following cmake -E commands are available only on Windows:
597 delete_regv <key>
599 Delete Windows registry value.
600 env_vs8_wince <sdkname>
602 Displays a batch file which sets the environment for the pro‐
603 vided Windows CE SDK installed in VS2005.
604 env_vs9_wince <sdkname>
606 Displays a batch file which sets the environment for the pro‐
607 vided Windows CE SDK installed in VS2008.
608 write_regv <key> <value>
610 Write Windows registry value.
611
613 CMake provides a helper for Makefile-based projects with the signature:
614 cmake --find-package <options>...
616 This runs in a pkg-config like mode.
618 Search a package using find_package() and print the resulting flags to
620 stdout. This can be used to use cmake instead of pkg-config to find
621 installed libraries in plain Makefile-based projects or in auto‐
622 conf-based projects (via share/aclocal/cmake.m4).
623 NOTE:
625 This mode is not well-supported due to some technical limitations.
626 It is kept for compatibility but should not be used in new projects.
627
629 The following resources are available to get help using CMake:
630 Home Page
632 https://cmake.org
633 The primary starting point for learning about CMake.
635 Frequently Asked Questions
637 https://cmake.org/Wiki/CMake_FAQ
638 A Wiki is provided containing answers to frequently asked ques‐
640 tions.
641 Online Documentation
643 https://cmake.org/documentation
644 Links to available documentation may be found on this web page.
646 Mailing List
648 https://cmake.org/mailing-lists
649 For help and discussion about using cmake, a mailing list is
651 provided at cmake@cmake.org. The list is member-post-only but
652 one may sign up on the CMake web page. Please first read the
653 full documentation at https://cmake.org before posting questions
654 to the list.
655
657 2000-2018 Kitware, Inc. and Contributors
6583.11.4 May 13, 2019 CMAKE(1)