1CMAKE(1) CMake CMAKE(1)
2
3
4
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
21 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
31 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
40 -D <var>:<type>=<value>, -D <var>=<value>
41 Create a cmake cache entry.
42
43 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
49 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
56 This option may also be given as a single argument:
57 -D<var>:<type>=<value> or -D<var>=<value>.
58
59 -U <globbing_expr>
60 Remove matching entries from CMake cache.
61
62 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
67 Use with care, you can make your CMakeCache.txt non-working.
68
69 -G <generator-name>
70 Specify a build system generator.
71
72 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
77 -T <toolset-spec>
78 Toolset specification for the generator, if supported.
79
80 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
84 -A <platform-name>
85 Specify platform name if supported by generator.
86
87 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
91 -Wno-dev
92 Suppress developer warnings.
93
94 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
98 -Wdev Enable developer warnings.
99
100 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
104 -Werror=dev
105 Make developer warnings errors.
106
107 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
111 -Wno-error=dev
112 Make developer warnings not errors.
113
114 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
118 -Wdeprecated
119 Enable deprecated functionality warnings.
120
121 Enable warnings for usage of deprecated functionality, that are
122 meant for the author of the CMakeLists.txt files.
123
124 -Wno-deprecated
125 Suppress deprecated functionality warnings.
126
127 Suppress warnings for usage of deprecated functionality, that
128 are meant for the author of the CMakeLists.txt files.
129
130 -Werror=deprecated
131 Make deprecated macro and function warnings errors.
132
133 Make warnings for usage of deprecated macros and functions, that
134 are meant for the author of the CMakeLists.txt files, errors.
135
136 -Wno-error=deprecated
137 Make deprecated macro and function warnings not errors.
138
139 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
143 -E <command> [<options>...]
144 See Command-Line Tool Mode.
145
146 -L[A][H]
147 List non-advanced cached variables.
148
149 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
157 --build <dir>
158 See Build Tool Mode.
159
160 --open <dir>
161 Open the generated project in the associated application. This
162 is only supported by some generators.
163
164 -N View mode only.
165
166 Only load the cache. Do not actually run configure and generate
167 steps.
168
169 -P <file>
170 Process script mode.
171
172 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
177 --find-package
178 See Find-Package Tool Mode.
179
180 --graphviz=[file]
181 Generate graphviz of dependencies, see CMakeGraphVizOptions for
182 more.
183
184 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
188 --system-information [file]
189 Dump information about this system.
190
191 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
195 --debug-trycompile
196 Do not delete the try_compile build tree. Only useful on one
197 try_compile at a time.
198
199 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
206 --debug-output
207 Put cmake in a debug mode.
208
209 Print extra information during the cmake run like stack traces
210 with message(send_error ) calls.
211
212 --trace
213 Put cmake in trace mode.
214
215 Print a trace of all calls made and from where.
216
217 --trace-expand
218 Put cmake in trace mode.
219
220 Like --trace, but with variables expanded.
221
222 --trace-source=<file>
223 Put cmake in trace mode, but output only lines of a specified
224 file.
225
226 Multiple options are allowed.
227
228 --warn-uninitialized
229 Warn about uninitialized values.
230
231 Print a warning when an uninitialized variable is used.
232
233 --warn-unused-vars
234 Warn about unused variables.
235
236 Find variables that are declared or set, but not used.
237
238 --no-warn-unused-cli
239 Don’t warn about command line options.
240
241 Don’t find variables that are declared on the command line, but
242 not used.
243
244 --check-system-vars
245 Find problems with variable usage in system files.
246
247 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
251 --help,-help,-usage,-h,-H,/?
252 Print usage information and exit.
253
254 Usage describes the basic command line interface and its
255 options.
256
257 --version,-version,/V [<f>]
258 Show program name/version banner and exit.
259
260 If a file is specified, the version is written into it. The
261 help is printed to a named <f>ile if given.
262
263 --help-full [<f>]
264 Print all help manuals and exit.
265
266 All manuals are printed in a human-readable text format. The
267 help is printed to a named <f>ile if given.
268
269 --help-manual <man> [<f>]
270 Print one help manual and exit.
271
272 The specified manual is printed in a human-readable text format.
273 The help is printed to a named <f>ile if given.
274
275 --help-manual-list [<f>]
276 List help manuals available and exit.
277
278 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
282 --help-command <cmd> [<f>]
283 Print help for one command and exit.
284
285 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
289 --help-command-list [<f>]
290 List commands with help available and exit.
291
292 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
296 --help-commands [<f>]
297 Print cmake-commands manual and exit.
298
299 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
302 --help-module <mod> [<f>]
303 Print help for one module and exit.
304
305 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
309 --help-module-list [<f>]
310 List modules with help available and exit.
311
312 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
316 --help-modules [<f>]
317 Print cmake-modules manual and exit.
318
319 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
322 --help-policy <cmp> [<f>]
323 Print help for one policy and exit.
324
325 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
329 --help-policy-list [<f>]
330 List policies with help available and exit.
331
332 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
336 --help-policies [<f>]
337 Print cmake-policies manual and exit.
338
339 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
342 --help-property <prop> [<f>]
343 Print help for one property and exit.
344
345 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
349 --help-property-list [<f>]
350 List properties with help available and exit.
351
352 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
356 --help-properties [<f>]
357 Print cmake-properties manual and exit.
358
359 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
362 --help-variable <var> [<f>]
363 Print help for one variable and exit.
364
365 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
369 --help-variable-list [<f>]
370 List variables with help available and exit.
371
372 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
376 --help-variables [<f>]
377 Print cmake-variables manual and exit.
378
379 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
386 cmake --build <dir> [<options>...] [-- <build-tool-options>...]
387
388 This abstracts a native build tool’s command-line interface with the
389 following options:
390
391 --build <dir>
392 Project binary directory to be built. This is required and must
393 be first.
394
395 --target <tgt>
396 Build <tgt> instead of default targets. May only be specified
397 once.
398
399 --config <cfg>
400 For multi-configuration tools, choose configuration <cfg>.
401
402 --clean-first
403 Build target clean first, then build. (To clean only, use
404 --target clean.)
405
406 --use-stderr
407 Ignored. Behavior is default in CMake >= 3.0.
408
409 -- Pass remaining options to the native tool.
410
411 Run cmake --build with no options for quick help.
412
414 CMake provides builtin command-line tools through the signature:
415
416 cmake -E <command> [<options>...]
417
418 Run cmake -E or cmake -E help for a summary of commands. Available
419 commands are:
420
421 capabilities
422 Report cmake capabilities in JSON format. The output is a JSON
423 object with the following keys:
424
425 version
426 A JSON object with version information. Keys are:
427
428 string The full version string as displayed by cmake
429 --version.
430
431 major The major version number in integer form.
432
433 minor The minor version number in integer form.
434
435 patch The patch level in integer form.
436
437 suffix The cmake version suffix string.
438
439 isDirty
440 A bool that is set if the cmake build is from a
441 dirty tree.
442
443 generators
444 A list available generators. Each generator is a JSON
445 object with the following keys:
446
447 name A string containing the name of the generator.
448
449 toolsetSupport
450 true if the generator supports toolsets and false
451 otherwise.
452
453 platformSupport
454 true if the generator supports platforms and false
455 otherwise.
456
457 extraGenerators
458 A list of strings with all the extra generators
459 compatible with the generator.
460
461 serverMode
462 true if cmake supports server-mode and false otherwise.
463
464 chdir <dir> <cmd> [<arg>...]
465 Change the current working directory and run a command.
466
467 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
471 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
476 copy_directory <dir>... <destination>
477 Copy directories to <destination> directory. If <destination>
478 directory does not exist it will be created.
479
480 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
485 echo [<string>...]
486 Displays arguments as text.
487
488 echo_append [<string>...]
489 Displays arguments as text but no new line.
490
491 env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...
492 Run command in a modified environment.
493
494 environment
495 Display the current environment variables.
496
497 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
502 md5sum <file>...
503 Create MD5 checksum of files in md5sum compatible format:
504
505 351abe79cd3800b38cdfb25d45015a15 file1.txt
506 052f86c15bbde68af55c7f7b340ab639 file2.txt
507
508 sha1sum <file>...
509 Create SHA1 checksum of files in sha1sum compatible format:
510
511 4bb7932a29e6f73c97bb9272f2bdc393122f86e0 file1.txt
512 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c file2.txt
513
514 sha224sum <file>...
515 Create SHA224 checksum of files in sha224sum compatible format:
516
517 b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930 file1.txt
518 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24 file2.txt
519
520 sha256sum <file>...
521 Create SHA256 checksum of files in sha256sum compatible format:
522
523 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc file1.txt
524 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea file2.txt
525
526 sha384sum <file>...
527 Create SHA384 checksum of files in sha384sum compatible format:
528
529 acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434 file1.txt
530 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d file2.txt
531
532 sha512sum <file>...
533 Create SHA512 checksum of files in sha512sum compatible format:
534
535 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89 file1.txt
536 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d file2.txt
537
538 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
544 remove_directory <dir>
545 Remove a directory and its contents. If a directory does not
546 exist it will be silently ignored.
547
548 rename <oldname> <newname>
549 Rename a file or directory (on one volume).
550
551 server Launch cmake-server(7) mode.
552
553 sleep <number>...
554 Sleep for given number of seconds.
555
556 tar [cxt][vf][zjJ] file.tar [<options>...] [--] [<file>...]
557 Create or extract a tar or zip archive. Options are:
558
559 -- Stop interpreting options and treat all remaining argu‐
560 ments as file names even if they start in -.
561
562 --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
567 --mtime=<date>
568 Specify modification time recorded in tarball entries.
569
570 --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
575 time <command> [<args>...]
576 Run command and display elapsed time.
577
578 touch <file>
579 Touch a file.
580
581 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
585 UNIX-specific Command-Line Tools
586 The following cmake -E commands are available only on UNIX:
587
588 create_symlink <old> <new>
589 Create a symbolic link <new> naming <old>.
590
591 NOTE:
592 Path to where <new> symbolic link will be created has to exist
593 beforehand.
594
595 Windows-specific Command-Line Tools
596 The following cmake -E commands are available only on Windows:
597
598 delete_regv <key>
599 Delete Windows registry value.
600
601 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
605 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
609 write_regv <key> <value>
610 Write Windows registry value.
611
613 CMake provides a helper for Makefile-based projects with the signature:
614
615 cmake --find-package <options>...
616
617 This runs in a pkg-config like mode.
618
619 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
624 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
631 Home Page
632 https://cmake.org
633
634 The primary starting point for learning about CMake.
635
636 Frequently Asked Questions
637 https://cmake.org/Wiki/CMake_FAQ
638
639 A Wiki is provided containing answers to frequently asked ques‐
640 tions.
641
642 Online Documentation
643 https://cmake.org/documentation
644
645 Links to available documentation may be found on this web page.
646
647 Mailing List
648 https://cmake.org/mailing-lists
649
650 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
658
659
660
661
6623.11.4 May 13, 2019 CMAKE(1)