1CMAKE(1)                             CMake                            CMAKE(1)
2
3
4

NAME

6       cmake - CMake Command-Line Reference
7

SYNOPSIS

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
14          Build a Project
15           cmake --build <dir> [<options>] [-- <build-tool-options>]
16
17          Install a Project
18           cmake --install <dir> [<options>]
19
20          Open a Project
21           cmake --open <dir>
22
23          Run a Script
24           cmake [{-D <var>=<value>}...] -P <cmake-script-file>
25
26          Run a Command-Line Tool
27           cmake -E <command> [<options>]
28
29          Run the Find-Package Tool
30           cmake --find-package [<options>]
31
32          View Help
33           cmake --help[-<topic>]
34

DESCRIPTION

36       The  cmake  executable is the command-line interface of the cross-plat‐
37       form buildsystem generator CMake.  The above Synopsis lists various ac‐
38       tions the tool can perform as described in sections below.
39
40       To build a software project with CMake, Generate a Project Buildsystem.
41       Optionally use cmake to Build a Project, Install a Project or just  run
42       the  corresponding  build tool (e.g. make) directly.  cmake can also be
43       used to View Help.
44
45       The other actions are meant for  use  by  software  developers  writing
46       scripts in the CMake language to support their builds.
47
48       For  graphical  user interfaces that may be used in place of cmake, see
49       ccmake and cmake-gui.  For command-line interfaces to the CMake testing
50       and packaging facilities, see ctest and cpack.
51
52       For  more  information on CMake at large, see also the links at the end
53       of this manual.
54

INTRODUCTION TO CMAKE BUILDSYSTEMS

56       A buildsystem describes how to build a project's  executables  and  li‐
57       braries  from  its  source  code  using  a  build  tool to automate the
58       process.  For example, a buildsystem may be a Makefile for use  with  a
59       command-line  make tool or a project file for an Integrated Development
60       Environment  (IDE).   In  order  to  avoid  maintaining  multiple  such
61       buildsystems,  a  project  may specify its buildsystem abstractly using
62       files written in the CMake language.  From these files CMake  generates
63       a  preferred buildsystem locally for each user through a backend called
64       a generator.
65
66       To generate a buildsystem with CMake, the following must be selected:
67
68       Source Tree
69              The top-level directory containing source files provided by  the
70              project.   The  project specifies its buildsystem using files as
71              described in  the  cmake-language(7)  manual,  starting  with  a
72              top-level  file named CMakeLists.txt.  These files specify build
73              targets   and   their   dependencies   as   described   in   the
74              cmake-buildsystem(7) manual.
75
76       Build Tree
77              The  top-level  directory  in  which buildsystem files and build
78              output artifacts (e.g. executables  and  libraries)  are  to  be
79              stored.   CMake will write a CMakeCache.txt file to identify the
80              directory as a build tree and store persistent information  such
81              as buildsystem configuration options.
82
83              To  maintain  a  pristine  source tree, perform an out-of-source
84              build by using a separate dedicated build  tree.   An  in-source
85              build in which the build tree is placed in the same directory as
86              the source tree is also supported, but discouraged.
87
88       Generator
89              This chooses the kind  of  buildsystem  to  generate.   See  the
90              cmake-generators(7)  manual for documentation of all generators.
91              Run cmake --help to see a list of generators available  locally.
92              Optionally  use  the  -G option below to specify a generator, or
93              simply accept the default CMake chooses for  the  current  plat‐
94              form.
95
96              When  using  one of the Command-Line Build Tool Generators CMake
97              expects that the environment needed by the compiler toolchain is
98              already  configured  in  the  shell.   When using one of the IDE
99              Build Tool Generators, no particular environment is needed.
100

GENERATE A PROJECT BUILDSYSTEM

102       Run CMake with one of the following command signatures to  specify  the
103       source and build trees and generate a buildsystem:
104
105       cmake [<options>] <path-to-source>
106              Uses  the  current  working  directory  as  the  build tree, and
107              <path-to-source> as the source tree.  The specified path may  be
108              absolute  or  relative  to  the  current working directory.  The
109              source tree must contain a CMakeLists.txt file and must not con‐
110              tain  a CMakeCache.txt file because the latter identifies an ex‐
111              isting build tree.  For example:
112
113                 $ mkdir build ; cd build
114                 $ cmake ../src
115
116       cmake [<options>] <path-to-existing-build>
117              Uses <path-to-existing-build> as the build tree, and  loads  the
118              path to the source tree from its CMakeCache.txt file, which must
119              have already been generated by a previous  run  of  CMake.   The
120              specified  path may be absolute or relative to the current work‐
121              ing directory.  For example:
122
123                 $ cd build
124                 $ cmake .
125
126       cmake [<options>] -S <path-to-source> -B <path-to-build>
127              Uses <path-to-build> as the build tree and  <path-to-source>  as
128              the  source  tree.  The specified paths may be absolute or rela‐
129              tive to the current working directory.   The  source  tree  must
130              contain  a  CMakeLists.txt file.  The build tree will be created
131              automatically if it does not already exist.  For example:
132
133                 $ cmake -S src -B build
134
135       In all cases the <options> may be zero or more of the Options below.
136
137       After generating a buildsystem one may  use  the  corresponding  native
138       build  tool  to  build  the project.  For example, after using the Unix
139       Makefiles generator one may run make directly:
140
141              $ make
142              $ make install
143
144       Alternatively, one may use cmake to Build a  Project  by  automatically
145       choosing and invoking the appropriate native build tool.
146
147   Options
148       -S <path-to-source>
149              Path to root directory of the CMake project to build.
150
151       -B <path-to-build>
152              Path  to directory which CMake will use as the root of build di‐
153              rectory.
154
155              If the directory doesn't already exist CMake will make it.
156
157       -C <initial-cache>
158              Pre-load a script to populate the cache.
159
160              When CMake is first run in an empty build  tree,  it  creates  a
161              CMakeCache.txt  file and populates it with customizable settings
162              for the project.  This option may be used to specify a file from
163              which  to  load  cache entries before the first pass through the
164              project's CMake listfiles.  The  loaded  entries  take  priority
165              over  the  project's default values.  The given file should be a
166              CMake script containing set() commands that use  the  CACHE  op‐
167              tion, not a cache-format file.
168
169              References  to  CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR within the
170              script evaluate to the top-level source and build tree.
171
172       -D <var>:<type>=<value>, -D <var>=<value>
173              Create or update a CMake CACHE entry.
174
175              When CMake is first run in an empty build  tree,  it  creates  a
176              CMakeCache.txt  file and populates it with customizable settings
177              for the project.  This option may be used to specify  a  setting
178              that  takes  priority over the project's default value.  The op‐
179              tion may be repeated for as many CACHE entries as desired.
180
181              If the :<type> portion is given it must  be  one  of  the  types
182              specified  by the set() command documentation for its CACHE sig‐
183              nature.  If the :<type> portion is omitted  the  entry  will  be
184              created  with  no type if it does not exist with a type already.
185              If a command in the project sets the type to  PATH  or  FILEPATH
186              then the <value> will be converted to an absolute path.
187
188              This   option   may   also   be  given  as  a  single  argument:
189              -D<var>:<type>=<value> or -D<var>=<value>.
190
191       -U <globbing_expr>
192              Remove matching entries from CMake CACHE.
193
194              This option may be used to remove one or more variables from the
195              CMakeCache.txt file, globbing expressions using * and ? are sup‐
196              ported.  The option may be repeated for as many CACHE entries as
197              desired.
198
199              Use with care, you can make your CMakeCache.txt non-working.
200
201       -G <generator-name>
202              Specify a build system generator.
203
204              CMake may support multiple native build systems on certain plat‐
205              forms.  A generator is responsible for generating  a  particular
206              build  system.   Possible  generator  names are specified in the
207              cmake-generators(7) manual.
208
209              If not specified, CMake checks the  CMAKE_GENERATOR  environment
210              variable  and  otherwise  falls back to a builtin default selec‐
211              tion.
212
213       -T <toolset-spec>
214              Toolset specification for the generator, if supported.
215
216              Some CMake generators support a toolset  specification  to  tell
217              the  native  build  system  how  to  choose a compiler.  See the
218              CMAKE_GENERATOR_TOOLSET variable for details.
219
220       -A <platform-name>
221              Specify platform name if supported by generator.
222
223              Some CMake generators support a platform name to be given to the
224              native  build  system  to  choose  a  compiler  or SDK.  See the
225              CMAKE_GENERATOR_PLATFORM variable for details.
226
227       --toolchain <path-to-file>
228              Specify the cross compiling toolchain file, equivalent  to  set‐
229              ting CMAKE_TOOLCHAIN_FILE variable.
230
231       --install-prefix <directory>
232              Specify  the  installation  directory,  used  by  the  CMAKE_IN‐
233              STALL_PREFIX variable. Must be an absolute path.
234
235       -Wno-dev
236              Suppress developer warnings.
237
238              Suppress warnings that are meant for the author  of  the  CMake‐
239              Lists.txt  files. By default this will also turn off deprecation
240              warnings.
241
242       -Wdev  Enable developer warnings.
243
244              Enable warnings that are meant for  the  author  of  the  CMake‐
245              Lists.txt  files.  By default this will also turn on deprecation
246              warnings.
247
248       -Werror=dev
249              Make developer warnings errors.
250
251              Make warnings that are  meant  for  the  author  of  the  CMake‐
252              Lists.txt files errors. By default this will also turn on depre‐
253              cated warnings as errors.
254
255       -Wno-error=dev
256              Make developer warnings not errors.
257
258              Make warnings that are  meant  for  the  author  of  the  CMake‐
259              Lists.txt  files  not errors. By default this will also turn off
260              deprecated warnings as errors.
261
262       -Wdeprecated
263              Enable deprecated functionality warnings.
264
265              Enable warnings for usage of deprecated functionality, that  are
266              meant for the author of the CMakeLists.txt files.
267
268       -Wno-deprecated
269              Suppress deprecated functionality warnings.
270
271              Suppress  warnings  for  usage of deprecated functionality, that
272              are meant for the author of the CMakeLists.txt files.
273
274       -Werror=deprecated
275              Make deprecated macro and function warnings errors.
276
277              Make warnings for usage of deprecated macros and functions, that
278              are meant for the author of the CMakeLists.txt files, errors.
279
280       -Wno-error=deprecated
281              Make deprecated macro and function warnings not errors.
282
283              Make warnings for usage of deprecated macros and functions, that
284              are meant for the author of the CMakeLists.txt  files,  not  er‐
285              rors.
286
287       -L[A][H]
288              List non-advanced cached variables.
289
290              List  CACHE  variables will run CMake and list all the variables
291              from the CMake CACHE that are not  marked  as  INTERNAL  or  AD‐
292              VANCED.   This  will effectively display current CMake settings,
293              which can then be changed with -D option.  Changing some of  the
294              variables  may  result in more variables being created.  If A is
295              specified, then it will display also advanced variables.   If  H
296              is specified, it will also display help for each variable.
297
298       -N     View mode only.
299
300              Only load the cache.  Do not actually run configure and generate
301              steps.
302
303       --graphviz=[file]
304              Generate graphviz of dependencies, see CMakeGraphVizOptions  for
305              more.
306
307              Generate a graphviz input file that will contain all the library
308              and executable dependencies in the project.  See the  documenta‐
309              tion for CMakeGraphVizOptions for more details.
310
311       --system-information [file]
312              Dump information about this system.
313
314              Dump  a  wide range of information about the current system.  If
315              run from the top of a binary tree for a CMake  project  it  will
316              dump additional information such as the cache, log files etc.
317
318       --log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>
319              Set the log level.
320
321              The message() command will only output messages of the specified
322              log level or higher.  The default log level is STATUS.
323
324              To make a log level persist between CMake runs,  set  CMAKE_MES‐
325              SAGE_LOG_LEVEL as a cache variable instead.  If both the command
326              line option and the variable are given, the command line  option
327              takes precedence.
328
329              For  backward compatibility reasons, --loglevel is also accepted
330              as a synonym for this option.
331
332       --log-context
333              Enable the message() command outputting context attached to each
334              message.
335
336              This  option  turns on showing context for the current CMake run
337              only.  To make showing the context persistent for all subsequent
338              CMake  runs,  set CMAKE_MESSAGE_CONTEXT_SHOW as a cache variable
339              instead.  When this command line  option  is  given,  CMAKE_MES‐
340              SAGE_CONTEXT_SHOW is ignored.
341
342       --debug-trycompile
343              Do  not delete the try_compile() build tree.  Only useful on one
344              try_compile() at a time.
345
346              Do not delete the files and  directories  created  for  try_com‐
347              pile()  calls.  This is useful in debugging failed try_compiles.
348              It may however change the results of  the  try-compiles  as  old
349              junk  from  a previous try-compile may cause a different test to
350              either pass or fail incorrectly.  This option is best  used  for
351              one try-compile at a time, and only when debugging.
352
353       --debug-output
354              Put cmake in a debug mode.
355
356              Print  extra  information during the cmake run like stack traces
357              with message(SEND_ERROR) calls.
358
359       --debug-find
360              Put cmake find commands in a debug mode.
361
362              Print extra find call information during the cmake run to  stan‐
363              dard error. Output is designed for human consumption and not for
364              parsing.  See also the CMAKE_FIND_DEBUG_MODE variable for debug‐
365              ging a more local part of the project.
366
367       --trace
368              Put cmake in trace mode.
369
370              Print a trace of all calls made and from where.
371
372       --trace-expand
373              Put cmake in trace mode.
374
375              Like --trace, but with variables expanded.
376
377       --trace-format=<format>
378              Put cmake in trace mode and sets the trace output format.
379
380              <format> can be one of the following values.
381
382                 human  Prints  each  trace  line  in a human-readable format.
383                        This is the default format.
384
385                 json-v1
386                        Prints each line as a  separate  JSON  document.  Each
387                        document is separated by a newline ( \n ). It is guar‐
388                        anteed that no newline characters will be present  in‐
389                        side a JSON document.
390
391                        JSON trace format:
392
393                            {
394                              "file": "/full/path/to/the/CMake/file.txt",
395                              "line": 0,
396                              "cmd": "add_executable",
397                              "args": ["foo", "bar"],
398                              "time": 1579512535.9687231,
399                              "frame": 2
400                            }
401
402                        The members are:
403
404                        file   The  full  path  to the CMake source file where
405                               the function was called.
406
407                        line   The line in file of the function call.
408
409                        defer  Optional member that is present when the  func‐
410                               tion  call  was  deferred by cmake_language(DE‐
411                               FER).  If present, its value is a  string  con‐
412                               taining the deferred call <id>.
413
414                        cmd    The name of the function that was called.
415
416                        args   A string list of all function parameters.
417
418                        time   Timestamp (seconds since epoch) of the function
419                               call.
420
421                        frame  Stack frame depth  of  the  function  that  was
422                               called.
423
424                        Additionally,  the  first JSON document outputted con‐
425                        tains the version key for the current major and  minor
426                        version of the
427
428                        JSON trace format:
429
430                            {
431                              "version": {
432                                "major": 1,
433                                "minor": 1
434                              }
435                            }
436
437                        The members are:
438
439                        version
440                               Indicates  the  version of the JSON format. The
441                               version has a major and minor  components  fol‐
442                               lowing semantic version conventions.
443
444       --trace-source=<file>
445              Put  cmake  in  trace mode, but output only lines of a specified
446              file.
447
448              Multiple options are allowed.
449
450       --trace-redirect=<file>
451              Put cmake in trace mode and redirect trace output to a file  in‐
452              stead of stderr.
453
454       --warn-uninitialized
455              Warn about uninitialized values.
456
457              Print a warning when an uninitialized variable is used.
458
459       --warn-unused-vars
460              Does  nothing.   In  CMake  versions  3.2 and below this enabled
461              warnings about unused variables.  In CMake versions 3.3  through
462              3.18  the option was broken.  In CMake 3.19 and above the option
463              has been removed.
464
465       --no-warn-unused-cli
466              Don't warn about command line options.
467
468              Don't find variables that are declared on the command line,  but
469              not used.
470
471       --check-system-vars
472              Find problems with variable usage in system files.
473
474              Normally,  unused  and  uninitialized variables are searched for
475              only in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR.  This flag  tells
476              CMake to warn about other files as well.
477
478       --profiling-output=<path>
479              Used in conjunction with --profiling-format to output to a given
480              path.
481
482       --profiling-format=<file>
483              Enable the output of profiling data of CMake script in the given
484              format.
485
486              This  can  aid  performance  analysis of CMake scripts executed.
487              Third party applications should be used to  process  the  output
488              into human readable format.
489
490              Currently  supported  values are: google-trace Outputs in Google
491              Trace Format, which can be parsed by the  about:tracing  tab  of
492              Google Chrome or using a plugin for a tool like Trace Compass.
493
494       --preset <preset>, --preset=<preset>
495              Reads   a  preset  from  <path-to-source>/CMakePresets.json  and
496              <path-to-source>/CMakeUserPresets.json. The preset  may  specify
497              the  generator  and the build directory, and a list of variables
498              and other arguments to pass to CMake. The current working direc‐
499              tory  must  contain  CMake  preset files. The CMake GUI can also
500              recognize CMakePresets.json and CMakeUserPresets.json files. For
501              full details on these files, see cmake-presets(7).
502
503              The  presets are read before all other command line options. The
504              options specified by the preset (variables, generator, etc.) can
505              all  be  overridden  by  manually specifying them on the command
506              line. For example, if the preset sets a variable called MYVAR to
507              1,  but the user sets it to 2 with a -D argument, the value 2 is
508              preferred.
509
510       --list-presets, --list-presets=<[configure | build | test | all]>
511              Lists the available presets. If no option is specified only con‐
512              figure  presets  will  be  listed. The current working directory
513              must contain CMake preset files.
514

BUILD A PROJECT

516       CMake provides a command-line signature to build  an  already-generated
517       project binary tree:
518
519          cmake --build <dir>             [<options>] [-- <build-tool-options>]
520          cmake --build --preset <preset> [<options>] [-- <build-tool-options>]
521
522       This  abstracts  a  native build tool's command-line interface with the
523       following options:
524
525       --build <dir>
526              Project binary directory to be built.  This is required  (unless
527              a preset is specified) and must be first.
528
529       --preset <preset>, --preset=<preset>
530              Use  a build preset to specify build options. The project binary
531              directory is inferred from the configurePreset key. The  current
532              working  directory  must contain CMake preset files.  See preset
533              for more details.
534
535       --list-presets
536              Lists the available build presets. The current working directory
537              must contain CMake preset files.
538
539       --parallel [<jobs>], -j [<jobs>]
540              The maximum number of concurrent processes to use when building.
541              If <jobs> is omitted the native build tool's default  number  is
542              used.
543
544              The  CMAKE_BUILD_PARALLEL_LEVEL  environment  variable,  if set,
545              specifies a default parallel  level  when  this  option  is  not
546              given.
547
548              Some  native  build  tools always build in parallel.  The use of
549              <jobs> value of 1 can be used to limit to a single job.
550
551       --target <tgt>..., -t <tgt>...
552              Build <tgt> instead of the default target.  Multiple targets may
553              be given, separated by spaces.
554
555       --config <cfg>
556              For multi-configuration tools, choose configuration <cfg>.
557
558       --clean-first
559              Build  target  clean  first,  then  build.   (To clean only, use
560              --target clean.)
561
562       --use-stderr
563              Ignored.  Behavior is default in CMake >= 3.0.
564
565       --verbose, -v
566              Enable verbose output - if supported - including the build  com‐
567              mands to be executed.
568
569              This  option  can  be omitted if VERBOSE environment variable or
570              CMAKE_VERBOSE_MAKEFILE cached variable is set.
571
572       --     Pass remaining options to the native tool.
573
574       Run cmake --build with no options for quick help.
575

INSTALL A PROJECT

577       CMake provides a command-line signature to install an already-generated
578       project binary tree:
579
580          cmake --install <dir> [<options>]
581
582       This  may  be used after building a project to run installation without
583       using the generated build system or the native build tool.  The options
584       are:
585
586       --install <dir>
587              Project  binary  directory to install. This is required and must
588              be first.
589
590       --config <cfg>
591              For multi-configuration generators, choose configuration <cfg>.
592
593       --component <comp>
594              Component-based install. Only install component <comp>.
595
596       --default-directory-permissions <permissions>
597              Default directory install  permissions.  Permissions  in  format
598              <u=rwx,g=rx,o=rx>.
599
600       --prefix <prefix>
601              Override the installation prefix, CMAKE_INSTALL_PREFIX.
602
603       --strip
604              Strip before installing.
605
606       -v, --verbose
607              Enable verbose output.
608
609              This  option  can  be omitted if VERBOSE environment variable is
610              set.
611
612       Run cmake --install with no options for quick help.
613

OPEN A PROJECT

615          cmake --open <dir>
616
617       Open the generated project in the associated application.  This is only
618       supported by some generators.
619

RUN A SCRIPT

621          cmake [{-D <var>=<value>}...] -P <cmake-script-file> [-- <unparsed-options>...]
622
623       Process the given cmake file as a script written in the CMake language.
624       No configure or generate step is performed and the cache is  not  modi‐
625       fied.   If variables are defined using -D, this must be done before the
626       -P argument.
627
628       Any options after -- are not parsed by CMake, but they  are  still  in‐
629       cluded  in the set of CMAKE_ARGV<n> variables passed to the script (in‐
630       cluding the -- itself).
631

RUN A COMMAND-LINE TOOL

633       CMake provides builtin command-line tools through the signature
634
635          cmake -E <command> [<options>]
636
637       Run cmake -E or cmake -E help for a  summary  of  commands.   Available
638       commands are:
639
640       capabilities
641              Report  cmake  capabilities in JSON format. The output is a JSON
642              object with the following keys:
643
644              version
645                     A JSON object with version information. Keys are:
646
647                     string The full version  string  as  displayed  by  cmake
648                            --version.
649
650                     major  The major version number in integer form.
651
652                     minor  The minor version number in integer form.
653
654                     patch  The patch level in integer form.
655
656                     suffix The cmake version suffix string.
657
658                     isDirty
659                            A  bool  that  is set if the cmake build is from a
660                            dirty tree.
661
662              generators
663                     A list available generators. Each generator is a JSON ob‐
664                     ject with the following keys:
665
666                     name   A string containing the name of the generator.
667
668                     toolsetSupport
669                            true  if the generator supports toolsets and false
670                            otherwise.
671
672                     platformSupport
673                            true if the generator supports platforms and false
674                            otherwise.
675
676                     supportedPlatforms
677                            New in version 3.21.
678
679
680                            Optional  member that may be present when the gen‐
681                            erator   supports   platform   specification   via
682                            CMAKE_GENERATOR_PLATFORM (-A ...).  The value is a
683                            list of platforms known to be supported.
684
685                     extraGenerators
686                            A list of strings with all  the  extra  generators
687                            compatible with the generator.
688
689              fileApi
690                     Optional    member    that    is    present    when   the
691                     cmake-file-api(7) is available.  The value is a JSON  ob‐
692                     ject with one member:
693
694                     requests
695                            A  JSON  array  containing  zero or more supported
696                            file-api requests.  Each request is a JSON  object
697                            with members:
698
699                            kind   Specifies one of the supported file-api ob‐
700                                   ject kinds.
701
702                            version
703                                   A JSON array whose elements are each a JSON
704                                   object  containing  major and minor members
705                                   specifying  non-negative  integer   version
706                                   components.
707
708              serverMode
709                     true  if  cmake supports server-mode and false otherwise.
710                     Always false since CMake 3.20.
711
712       cat <files>...
713              Concatenate files and print on the standard output.
714
715       chdir <dir> <cmd> [<arg>...]
716              Change the current working directory and run a command.
717
718       compare_files [--ignore-eol] <file1> <file2>
719              Check if <file1> is same as <file2>. If files are the same, then
720              returns  0,  if not it returns 1.  In case of invalid arguments,
721              it returns 2. The --ignore-eol option implies line-wise compari‐
722              son and ignores LF/CRLF differences.
723
724       copy <file>... <destination>
725              Copy files to <destination> (either file or directory).  If mul‐
726              tiple files are specified, the <destination> must  be  directory
727              and  it must exist. Wildcards are not supported.  copy does fol‐
728              low symlinks. That means it does  not  copy  symlinks,  but  the
729              files or directories it point to.
730
731       copy_directory <dir>... <destination>
732              Copy content of <dir>... directories to <destination> directory.
733              If <destination> directory does not exist it  will  be  created.
734              copy_directory does follow symlinks.
735
736       copy_if_different <file>... <destination>
737              Copy  files  to <destination> (either file or directory) if they
738              have changed.  If multiple files are  specified,  the  <destina‐
739              tion>  must  be  directory and it must exist.  copy_if_different
740              does follow symlinks.
741
742       create_symlink <old> <new>
743              Create a symbolic link <new> naming <old>.
744
745              NOTE:
746                 Path to where <new> symbolic link will be created has to  ex‐
747                 ist beforehand.
748
749       create_hardlink <old> <new>
750              Create a hard link <new> naming <old>.
751
752              NOTE:
753                 Path  to  where  <new> hard link will be created has to exist
754                 beforehand.  <old> has to exist beforehand.
755
756       echo [<string>...]
757              Displays arguments as text.
758
759       echo_append [<string>...]
760              Displays arguments as text but no new line.
761
762       env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...
763              Run command in a modified environment.
764
765       environment
766              Display the current environment variables.
767
768       false  Do nothing, with an exit code of 1.
769
770       make_directory <dir>...
771              Create <dir> directories.  If necessary, create parent  directo‐
772              ries too.  If a directory already exists it will be silently ig‐
773              nored.
774
775       md5sum <file>...
776              Create MD5 checksum of files in md5sum compatible format:
777
778                 351abe79cd3800b38cdfb25d45015a15  file1.txt
779                 052f86c15bbde68af55c7f7b340ab639  file2.txt
780
781       sha1sum <file>...
782              Create SHA1 checksum of files in sha1sum compatible format:
783
784                 4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
785                 1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt
786
787       sha224sum <file>...
788              Create SHA224 checksum of files in sha224sum compatible format:
789
790                 b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930  file1.txt
791                 6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24  file2.txt
792
793       sha256sum <file>...
794              Create SHA256 checksum of files in sha256sum compatible format:
795
796                 76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc  file1.txt
797                 15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea  file2.txt
798
799       sha384sum <file>...
800              Create SHA384 checksum of files in sha384sum compatible format:
801
802                 acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434  file1.txt
803                 668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d  file2.txt
804
805       sha512sum <file>...
806              Create SHA512 checksum of files in sha512sum compatible format:
807
808                 2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89  file1.txt
809                 7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d  file2.txt
810
811       remove [-f] <file>...
812              Deprecated since version 3.17.
813
814
815              Remove the file(s). The planned behavior was that if any of  the
816              listed  files  already  do  not  exist,  the  command  returns a
817              non-zero exit code, but no message  is  logged.  The  -f  option
818              changes  the  behavior to return a zero exit code (i.e. success)
819              in such situations instead.  remove does  not  follow  symlinks.
820              That means it remove only symlinks and not files it point to.
821
822              The implementation was buggy and always returned 0. It cannot be
823              fixed without breaking backwards compatibility. Use rm instead.
824
825       remove_directory <dir>...
826              Deprecated since version 3.17.
827
828
829              Remove <dir> directories and their contents. If a directory does
830              not exist it will be silently ignored.  If <dir> is a symlink to
831              a directory, just the symlink will be removed.  Use rm instead.
832
833       rename <oldname> <newname>
834              Rename a file or directory (on one volume).  If  file  with  the
835              <newname>  name  already  exists,  then  it will be silently re‐
836              placed.
837
838       rm [-rRf] <file> <dir>...
839              Remove the files <file> or directories dir.  Use -r or -R to re‐
840              move  directories and their contents recursively.  If any of the
841              listed files/directories do not exist,  the  command  returns  a
842              non-zero  exit  code,  but  no  message is logged. The -f option
843              changes the behavior to return a zero exit code  (i.e.  success)
844              in such situations instead.
845
846       server Launch cmake-server(7) mode.
847
848       sleep <number>...
849              Sleep for given number of seconds.
850
851       tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]
852              Create or extract a tar or zip archive.  Options are:
853
854              c      Create  a new archive containing the specified files.  If
855                     used, the <pathname>... argument is mandatory.
856
857              x      Extract to disk from the archive.  The <pathname>...  ar‐
858                     gument  could  be  used to extract only selected files or
859                     directories.  When extracting selected files or  directo‐
860                     ries,  you  must  provide their exact names including the
861                     path, as printed by list (-t).
862
863              t      List archive contents.  The <pathname>... argument  could
864                     be used to list only selected files or directories.
865
866              v      Produce verbose output.
867
868              z      Compress the resulting archive with gzip.
869
870              j      Compress the resulting archive with bzip2.
871
872              J      Compress the resulting archive with XZ.
873
874              --zstd Compress the resulting archive with Zstandard.
875
876              --files-from=<file>
877                     Read file names from the given file, one per line.  Blank
878                     lines are ignored.  Lines may not start in -  except  for
879                     --add-file=<name> to add files whose names start in -.
880
881              --format=<format>
882                     Specify  the  format  of the archive to be created.  Sup‐
883                     ported formats are: 7zip, gnutar, pax,  paxr  (restricted
884                     pax, default), and zip.
885
886              --mtime=<date>
887                     Specify modification time recorded in tarball entries.
888
889              --     Stop  interpreting  options and treat all remaining argu‐
890                     ments as file names, even if they start with -.
891
892       time <command> [<args>...]
893              Run command and display elapsed time.
894
895       touch <file>...
896              Creates <file> if file do not exist.  If <file>  exists,  it  is
897              changing <file> access and modification times.
898
899       touch_nocreate <file>...
900              Touch  a file if it exists but do not create it.  If a file does
901              not exist it will be silently ignored.
902
903       true   Do nothing, with an exit code of 0.
904
905   Windows-specific Command-Line Tools
906       The following cmake -E commands are available only on Windows:
907
908       delete_regv <key>
909              Delete Windows registry value.
910
911       env_vs8_wince <sdkname>
912              Displays a batch file which sets the environment  for  the  pro‐
913              vided Windows CE SDK installed in VS2005.
914
915       env_vs9_wince <sdkname>
916              Displays  a  batch  file which sets the environment for the pro‐
917              vided Windows CE SDK installed in VS2008.
918
919       write_regv <key> <value>
920              Write Windows registry value.
921

RUN THE FIND-PACKAGE TOOL

923       CMake provides a pkg-config like helper for Makefile-based projects:
924
925          cmake --find-package [<options>]
926
927       It searches a package using find_package()  and  prints  the  resulting
928       flags  to  stdout.   This can be used instead of pkg-config to find in‐
929       stalled libraries in plain Makefile-based projects or in autoconf-based
930       projects (via share/aclocal/cmake.m4).
931
932       NOTE:
933          This  mode  is not well-supported due to some technical limitations.
934          It is kept for compatibility but should not be used in new projects.
935

VIEW HELP

937       To print selected pages from the CMake documentation, use
938
939          cmake --help[-<topic>]
940
941       with one of the following options:
942
943       --help,-help,-usage,-h,-H,/?
944              Print usage information and exit.
945
946              Usage describes the basic command line  interface  and  its  op‐
947              tions.
948
949       --version,-version,/V [<f>]
950              Show program name/version banner and exit.
951
952              If  a  file  is  specified, the version is written into it.  The
953              help is printed to a named <f>ile if given.
954
955       --help-full [<f>]
956              Print all help manuals and exit.
957
958              All manuals are printed in a human-readable  text  format.   The
959              help is printed to a named <f>ile if given.
960
961       --help-manual <man> [<f>]
962              Print one help manual and exit.
963
964              The specified manual is printed in a human-readable text format.
965              The help is printed to a named <f>ile if given.
966
967       --help-manual-list [<f>]
968              List help manuals available and exit.
969
970              The list contains all manuals for which help may be obtained  by
971              using  the  --help-manual option followed by a manual name.  The
972              help is printed to a named <f>ile if given.
973
974       --help-command <cmd> [<f>]
975              Print help for one command and exit.
976
977              The cmake-commands(7) manual entry for <cmd> is printed in a hu‐
978              man-readable text format.  The help is printed to a named <f>ile
979              if given.
980
981       --help-command-list [<f>]
982              List commands with help available and exit.
983
984              The list contains all commands for which help may be obtained by
985              using the --help-command option followed by a command name.  The
986              help is printed to a named <f>ile if given.
987
988       --help-commands [<f>]
989              Print cmake-commands manual and exit.
990
991              The cmake-commands(7) manual is printed in a human-readable text
992              format.  The help is printed to a named <f>ile if given.
993
994       --help-module <mod> [<f>]
995              Print help for one module and exit.
996
997              The  cmake-modules(7) manual entry for <mod> is printed in a hu‐
998              man-readable text format.  The help is printed to a named <f>ile
999              if given.
1000
1001       --help-module-list [<f>]
1002              List modules with help available and exit.
1003
1004              The  list contains all modules for which help may be obtained by
1005              using the --help-module option followed by a module  name.   The
1006              help is printed to a named <f>ile if given.
1007
1008       --help-modules [<f>]
1009              Print cmake-modules manual and exit.
1010
1011              The  cmake-modules(7) manual is printed in a human-readable text
1012              format.  The help is printed to a named <f>ile if given.
1013
1014       --help-policy <cmp> [<f>]
1015              Print help for one policy and exit.
1016
1017              The cmake-policies(7) manual entry for <cmp> is printed in a hu‐
1018              man-readable text format.  The help is printed to a named <f>ile
1019              if given.
1020
1021       --help-policy-list [<f>]
1022              List policies with help available and exit.
1023
1024              The list contains all policies for which help may be obtained by
1025              using  the  --help-policy option followed by a policy name.  The
1026              help is printed to a named <f>ile if given.
1027
1028       --help-policies [<f>]
1029              Print cmake-policies manual and exit.
1030
1031              The cmake-policies(7) manual is printed in a human-readable text
1032              format.  The help is printed to a named <f>ile if given.
1033
1034       --help-property <prop> [<f>]
1035              Print help for one property and exit.
1036
1037              The cmake-properties(7) manual entries for <prop> are printed in
1038              a human-readable text format.  The help is printed  to  a  named
1039              <f>ile if given.
1040
1041       --help-property-list [<f>]
1042              List properties with help available and exit.
1043
1044              The  list contains all properties for which help may be obtained
1045              by using the --help-property option followed by a property name.
1046              The help is printed to a named <f>ile if given.
1047
1048       --help-properties [<f>]
1049              Print cmake-properties manual and exit.
1050
1051              The  cmake-properties(7)  manual  is printed in a human-readable
1052              text format.  The help is printed to a named <f>ile if given.
1053
1054       --help-variable <var> [<f>]
1055              Print help for one variable and exit.
1056
1057              The cmake-variables(7) manual entry for <var> is  printed  in  a
1058              human-readable  text  format.   The  help  is printed to a named
1059              <f>ile if given.
1060
1061       --help-variable-list [<f>]
1062              List variables with help available and exit.
1063
1064              The list contains all variables for which help may  be  obtained
1065              by using the --help-variable option followed by a variable name.
1066              The help is printed to a named <f>ile if given.
1067
1068       --help-variables [<f>]
1069              Print cmake-variables manual and exit.
1070
1071              The cmake-variables(7) manual is  printed  in  a  human-readable
1072              text format.  The help is printed to a named <f>ile if given.
1073
1074       To view the presets available for a project, use
1075
1076          cmake <source-dir> --list-presets
1077

SEE ALSO

1079       The following resources are available to get help using CMake:
1080
1081       Home Page
1082              https://cmake.org
1083
1084              The primary starting point for learning about CMake.
1085
1086       Online Documentation and Community Resources
1087              https://cmake.org/documentation
1088
1089              Links  to available documentation and community resources may be
1090              found on this web page.
1091
1092       Discourse Forum
1093              https://discourse.cmake.org
1094
1095              The Discourse Forum hosts discussion and questions about CMake.
1096
1098       2000-2022 Kitware, Inc. and Contributors
1099
1100
1101
1102
11033.22.2                           Jan 25, 2022                         CMAKE(1)
Impressum