Help/manual/cmake.1.rst

   1 .. cmake-manual-description: CMake Command-Line Reference
   2
   3 cmake(1)
   4 ********
   5
   6 Synopsis
   7 ========
   8
   9 .. parsed-literal::
  10
  11  `Generate a Project Buildsystem`_
  12   cmake [<options>] <path-to-source>
  13   cmake [<options>] <path-to-existing-build>
  14   cmake [<options>] -S <path-to-source> -B <path-to-build>
  15
  16  `Build a Project`_
  17   cmake --build <dir> [<options>] [-- <build-tool-options>]
  18
  19  `Install a Project`_
  20   cmake --install <dir> [<options>]
  21
  22  `Open a Project`_
  23   cmake --open <dir>
  24
  25  `Run a Script`_
  26   cmake [{-D <var>=<value>}...] -P <cmake-script-file>
  27
  28  `Run a Command-Line Tool`_
  29   cmake -E <command> [<options>]
  30
  31  `Run the Find-Package Tool`_
  32   cmake --find-package [<options>]
  33
  34  `View Help`_
  35   cmake --help[-<topic>]
  36
  37 Description
  38 ===========
  39
  40 The **cmake** executable is the command-line interface of the cross-platform
  41 buildsystem generator CMake.  The above `Synopsis`_ lists various actions
  42 the tool can perform as described in sections below.
  43
  44 To build a software project with CMake, `Generate a Project Buildsystem`_.
  45 Optionally use **cmake** to `Build a Project`_, `Install a Project`_ or just
  46 run the corresponding build tool (e.g. ``make``) directly.  **cmake** can also
  47 be used to `View Help`_.
  48
  49 The other actions are meant for use by software developers writing
  50 scripts in the :manual:`CMake language <cmake-language(7)>` to support
  51 their builds.
  52
  53 For graphical user interfaces that may be used in place of **cmake**,
  54 see :manual:`ccmake <ccmake(1)>` and :manual:`cmake-gui <cmake-gui(1)>`.
  55 For command-line interfaces to the CMake testing and packaging facilities,
  56 see :manual:`ctest <ctest(1)>` and :manual:`cpack <cpack(1)>`.
  57
  58 For more information on CMake at large, `see also`_ the links at the end
  59 of this manual.
  60
  61
  62 Introduction to CMake Buildsystems
  63 ==================================
  64
  65 A *buildsystem* describes how to build a project's executables and libraries
  66 from its source code using a *build tool* to automate the process.  For
  67 example, a buildsystem may be a ``Makefile`` for use with a command-line
  68 ``make`` tool or a project file for an Integrated Development Environment
  69 (IDE).  In order to avoid maintaining multiple such buildsystems, a project
  70 may specify its buildsystem abstractly using files written in the
  71 :manual:`CMake language <cmake-language(7)>`.  From these files CMake
  72 generates a preferred buildsystem locally for each user through a backend
  73 called a *generator*.
  74
  75 To generate a buildsystem with CMake, the following must be selected:
  76
  77 Source Tree
  78   The top-level directory containing source files provided by the project.
  79   The project specifies its buildsystem using files as described in the
  80   :manual:`cmake-language(7)` manual, starting with a top-level file named
  81   ``CMakeLists.txt``.  These files specify build targets and their
  82   dependencies as described in the :manual:`cmake-buildsystem(7)` manual.
  83
  84 Build Tree
  85   The top-level directory in which buildsystem files and build output
  86   artifacts (e.g. executables and libraries) are to be stored.
  87   CMake will write a ``CMakeCache.txt`` file to identify the directory
  88   as a build tree and store persistent information such as buildsystem
  89   configuration options.
  90
  91   To maintain a pristine source tree, perform an *out-of-source* build
  92   by using a separate dedicated build tree.  An *in-source* build in
  93   which the build tree is placed in the same directory as the source
  94   tree is also supported, but discouraged.
  95
  96 Generator
  97   This chooses the kind of buildsystem to generate.  See the
  98   :manual:`cmake-generators(7)` manual for documentation of all generators.
  99   Run ``cmake --help`` to see a list of generators available locally.
 100   Optionally use the ``-G`` option below to specify a generator, or simply
 101   accept the default CMake chooses for the current platform.
 102
 103   When using one of the :ref:`Command-Line Build Tool Generators`
 104   CMake expects that the environment needed by the compiler toolchain
 105   is already configured in the shell.  When using one of the
 106   :ref:`IDE Build Tool Generators`, no particular environment is needed.
 107
 108 .. _`Generate a Project Buildsystem`:
 109
 110 Generate a Project Buildsystem
 111 ==============================
 112
 113 Run CMake with one of the following command signatures to specify the
 114 source and build trees and generate a buildsystem:
 115
 116 ``cmake [<options>] <path-to-source>``
 117   Uses the current working directory as the build tree, and
 118   ``<path-to-source>`` as the source tree.  The specified path may
 119   be absolute or relative to the current working directory.
 120   The source tree must contain a ``CMakeLists.txt`` file and must
 121   *not* contain a ``CMakeCache.txt`` file because the latter
 122   identifies an existing build tree.  For example:
 123
 124   .. code-block:: console
 125
 126     $ mkdir build ; cd build
 127     $ cmake ../src
 128
 129 ``cmake [<options>] <path-to-existing-build>``
 130   Uses ``<path-to-existing-build>`` as the build tree, and loads the
 131   path to the source tree from its ``CMakeCache.txt`` file, which must
 132   have already been generated by a previous run of CMake.  The specified
 133   path may be absolute or relative to the current working directory.
 134   For example:
 135
 136   .. code-block:: console
 137
 138     $ cd build
 139     $ cmake .
 140
 141 ``cmake [<options>] -S <path-to-source> -B <path-to-build>``
 142   Uses ``<path-to-build>`` as the build tree and ``<path-to-source>``
 143   as the source tree.  The specified paths may be absolute or relative
 144   to the current working directory.  The source tree must contain a
 145   ``CMakeLists.txt`` file.  The build tree will be created automatically
 146   if it does not already exist.  For example:
 147
 148   .. code-block:: console
 149
 150     $ cmake -S src -B build
 151
 152 In all cases the ``<options>`` may be zero or more of the `Options`_ below.
 153
 154 The above styles for specifying the source and build trees may be mixed.
 155 Paths specified with ``-S`` or ``-B`` are always classified as source or
 156 build trees, respectively.  Paths specified with plain arguments are
 157 classified based on their content and the types of paths given earlier.
 158 If only one type of path is given, the current working directory (cwd)
 159 is used for the other.  For example:
 160
 161 ============================== ============ ===========
 162  Command Line                   Source Dir   Build Dir
 163 ============================== ============ ===========
 164  ``cmake src``                  ``src``      `cwd`
 165  ``cmake build`` (existing)     `loaded`     ``build``
 166  ``cmake -S src``               ``src``      `cwd`
 167  ``cmake -S src build``         ``src``      ``build``
 168  ``cmake -S src -B build``      ``src``      ``build``
 169  ``cmake -B build``             `cwd`        ``build``
 170  ``cmake -B build src``         ``src``      ``build``
 171  ``cmake -B build -S src``      ``src``      ``build``
 172 ============================== ============ ===========
 173
 174 .. versionchanged:: 3.23
 175
 176   CMake warns when multiple source paths are specified.  This has never
 177   been officially documented or supported, but older versions accidentally
 178   accepted multiple source paths and used the last path specified.
 179   Avoid passing multiple source path arguments.
 180
 181 After generating a buildsystem one may use the corresponding native
 182 build tool to build the project.  For example, after using the
 183 :generator:`Unix Makefiles` generator one may run ``make`` directly:
 184
 185   .. code-block:: console
 186
 187     $ make
 188     $ make install
 189
 190 Alternatively, one may use **cmake** to `Build a Project`_ by
 191 automatically choosing and invoking the appropriate native build tool.
 192
 193 .. _`CMake Options`:
 194
 195 Options
 196 -------
 197
 198 .. include:: OPTIONS_BUILD.txt
 199
 200 ``--fresh``
 201  .. versionadded:: 3.24
 202
 203  Perform a fresh configuration of the build tree.
 204  This removes any existing ``CMakeCache.txt`` file and associated
 205  ``CMakeFiles/`` directory, and recreates them from scratch.
 206
 207 ``-L[A][H]``
 208  List non-advanced cached variables.
 209
 210  List ``CACHE`` variables will run CMake and list all the variables from
 211  the CMake ``CACHE`` that are not marked as ``INTERNAL`` or :prop_cache:`ADVANCED`.
 212  This will effectively display current CMake settings, which can then be
 213  changed with ``-D`` option.  Changing some of the variables may result
 214  in more variables being created.  If ``A`` is specified, then it will
 215  display also advanced variables.  If ``H`` is specified, it will also
 216  display help for each variable.
 217
 218 ``-N``
 219  View mode only.
 220
 221  Only load the cache.  Do not actually run configure and generate
 222  steps.
 223
 224 ``--graphviz=[file]``
 225  Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more.
 226
 227  Generate a graphviz input file that will contain all the library and
 228  executable dependencies in the project.  See the documentation for
 229  :module:`CMakeGraphVizOptions` for more details.
 230
 231 ``--system-information [file]``
 232  Dump information about this system.
 233
 234  Dump a wide range of information about the current system.  If run
 235  from the top of a binary tree for a CMake project it will dump
 236  additional information such as the cache, log files etc.
 237
 238 ``--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>``
 239  Set the log level.
 240
 241  The :command:`message` command will only output messages of the specified
 242  log level or higher.  The default log level is ``STATUS``.
 243
 244  To make a log level persist between CMake runs, set
 245  :variable:`CMAKE_MESSAGE_LOG_LEVEL` as a cache variable instead.
 246  If both the command line option and the variable are given, the command line
 247  option takes precedence.
 248
 249  For backward compatibility reasons, ``--loglevel`` is also accepted as a
 250  synonym for this option.
 251
 252 ``--log-context``
 253  Enable the :command:`message` command outputting context attached to each
 254  message.
 255
 256  This option turns on showing context for the current CMake run only.
 257  To make showing the context persistent for all subsequent CMake runs, set
 258  :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` as a cache variable instead.
 259  When this command line option is given, :variable:`CMAKE_MESSAGE_CONTEXT_SHOW`
 260  is ignored.
 261
 262 ``--debug-trycompile``
 263  Do not delete the :command:`try_compile` build tree.
 264  Only useful on one :command:`try_compile` at a time.
 265
 266  Do not delete the files and directories created for :command:`try_compile`
 267  calls.  This is useful in debugging failed try_compiles.  It may
 268  however change the results of the try-compiles as old junk from a
 269  previous try-compile may cause a different test to either pass or
 270  fail incorrectly.  This option is best used for one try-compile at a
 271  time, and only when debugging.
 272
 273 ``--debug-output``
 274  Put cmake in a debug mode.
 275
 276  Print extra information during the cmake run like stack traces with
 277  :command:`message(SEND_ERROR)` calls.
 278
 279 ``--debug-find``
 280  Put cmake find commands in a debug mode.
 281
 282  Print extra find call information during the cmake run to standard
 283  error. Output is designed for human consumption and not for parsing.
 284  See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging
 285  a more local part of the project.
 286
 287 ``--debug-find-pkg=<pkg>[,...]``
 288  Put cmake find commands in a debug mode when running under calls
 289  to :command:`find_package(\<pkg\>) <find_package>`, where ``<pkg>``
 290  is an entry in the given comma-separated list of case-sensitive package
 291  names.
 292
 293  Like ``--debug-find``, but limiting scope to the specified packages.
 294
 295 ``--debug-find-var=<var>[,...]``
 296  Put cmake find commands in a debug mode when called with ``<var>``
 297  as the result variable, where ``<var>`` is an entry in the given
 298  comma-separated list.
 299
 300  Like ``--debug-find``, but limiting scope to the specified variable names.
 301
 302 ``--trace``
 303  Put cmake in trace mode.
 304
 305  Print a trace of all calls made and from where.
 306
 307 ``--trace-expand``
 308  Put cmake in trace mode.
 309
 310  Like ``--trace``, but with variables expanded.
 311
 312 ``--trace-format=<format>``
 313  Put cmake in trace mode and sets the trace output format.
 314
 315  ``<format>`` can be one of the following values.
 316
 317    ``human``
 318      Prints each trace line in a human-readable format. This is the
 319      default format.
 320
 321    ``json-v1``
 322      Prints each line as a separate JSON document. Each document is
 323      separated by a newline ( ``\n`` ). It is guaranteed that no
 324      newline characters will be present inside a JSON document.
 325
 326      JSON trace format:
 327
 328      .. code-block:: json
 329
 330        {
 331          "file": "/full/path/to/the/CMake/file.txt",
 332          "line": 0,
 333          "cmd": "add_executable",
 334          "args": ["foo", "bar"],
 335          "time": 1579512535.9687231,
 336          "frame": 2,
 337          "global_frame": 4
 338        }
 339
 340      The members are:
 341
 342      ``file``
 343        The full path to the CMake source file where the function
 344        was called.
 345
 346      ``line``
 347        The line in ``file`` where the function call begins.
 348
 349      ``line_end``
 350        If the function call spans multiple lines, this field will
 351        be set to the line where the function call ends. If the function
 352        calls spans a single line, this field will be unset. This field
 353        was added in minor version 2 of the ``json-v1`` format.
 354
 355      ``defer``
 356        Optional member that is present when the function call was deferred
 357        by :command:`cmake_language(DEFER)`.  If present, its value is a
 358        string containing the deferred call ``<id>``.
 359
 360      ``cmd``
 361        The name of the function that was called.
 362
 363      ``args``
 364        A string list of all function parameters.
 365
 366      ``time``
 367        Timestamp (seconds since epoch) of the function call.
 368
 369      ``frame``
 370        Stack frame depth of the function that was called, within the
 371        context of the  ``CMakeLists.txt`` being processed currently.
 372
 373      ``global_frame``
 374        Stack frame depth of the function that was called, tracked globally
 375        across all ``CMakeLists.txt`` files involved in the trace. This field
 376        was added in minor version 2 of the ``json-v1`` format.
 377
 378      Additionally, the first JSON document outputted contains the
 379      ``version`` key for the current major and minor version of the
 380
 381      JSON trace format:
 382
 383      .. code-block:: json
 384
 385        {
 386          "version": {
 387            "major": 1,
 388            "minor": 2
 389          }
 390        }
 391
 392      The members are:
 393
 394      ``version``
 395        Indicates the version of the JSON format. The version has a
 396        major and minor components following semantic version conventions.
 397
 398 ``--trace-source=<file>``
 399  Put cmake in trace mode, but output only lines of a specified file.
 400
 401  Multiple options are allowed.
 402
 403 ``--trace-redirect=<file>``
 404  Put cmake in trace mode and redirect trace output to a file instead of stderr.
 405
 406 ``--warn-uninitialized``
 407  Warn about uninitialized values.
 408
 409  Print a warning when an uninitialized variable is used.
 410
 411 ``--warn-unused-vars``
 412  Does nothing.  In CMake versions 3.2 and below this enabled warnings about
 413  unused variables.  In CMake versions 3.3 through 3.18 the option was broken.
 414  In CMake 3.19 and above the option has been removed.
 415
 416 ``--no-warn-unused-cli``
 417  Don't warn about command line options.
 418
 419  Don't find variables that are declared on the command line, but not
 420  used.
 421
 422 ``--check-system-vars``
 423  Find problems with variable usage in system files.
 424
 425  Normally, unused and uninitialized variables are searched for only
 426  in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`.
 427  This flag tells CMake to warn about other files as well.
 428
 429 ``--compile-no-warning-as-error``
 430  Ignore target property :prop_tgt:`COMPILE_WARNING_AS_ERROR` and variable
 431  :variable:`CMAKE_COMPILE_WARNING_AS_ERROR`, preventing warnings from being
 432  treated as errors on compile.
 433
 434 ``--profiling-output=<path>``
 435  Used in conjunction with ``--profiling-format`` to output to a given path.
 436
 437 ``--profiling-format=<file>``
 438  Enable the output of profiling data of CMake script in the given format.
 439
 440  This can aid performance analysis of CMake scripts executed. Third party
 441  applications should be used to process the output into human readable format.
 442
 443  Currently supported values are:
 444  ``google-trace`` Outputs in Google Trace Format, which can be parsed by the
 445  about:tracing tab of Google Chrome or using a plugin for a tool like Trace
 446  Compass.
 447
 448 ``--preset <preset>``, ``--preset=<preset>``
 449  Reads a :manual:`preset <cmake-presets(7)>` from
 450  ``<path-to-source>/CMakePresets.json`` and
 451  ``<path-to-source>/CMakeUserPresets.json``. The preset may specify the
 452  generator and the build directory, and a list of variables and other
 453  arguments to pass to CMake. The current working directory must contain
 454  CMake preset files. The :manual:`CMake GUI <cmake-gui(1)>` can
 455  also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For
 456  full details on these files, see :manual:`cmake-presets(7)`.
 457
 458  The presets are read before all other command line options. The options
 459  specified by the preset (variables, generator, etc.) can all be overridden by
 460  manually specifying them on the command line. For example, if the preset sets
 461  a variable called ``MYVAR`` to ``1``, but the user sets it to ``2`` with a
 462  ``-D`` argument, the value ``2`` is preferred.
 463
 464 ``--list-presets, --list-presets=<[configure | build | test | all]>``
 465  Lists the available presets. If no option is specified only configure presets
 466  will be listed. The current working directory must contain CMake preset files.
 467
 468 .. _`Build Tool Mode`:
 469
 470 Build a Project
 471 ===============
 472
 473 CMake provides a command-line signature to build an already-generated
 474 project binary tree:
 475
 476 .. code-block:: shell
 477
 478   cmake --build <dir>             [<options>] [-- <build-tool-options>]
 479   cmake --build --preset <preset> [<options>] [-- <build-tool-options>]
 480
 481 This abstracts a native build tool's command-line interface with the
 482 following options:
 483
 484 ``--build <dir>``
 485   Project binary directory to be built.  This is required (unless a preset
 486   is specified) and must be first.
 487
 488 ``--preset <preset>``, ``--preset=<preset>``
 489   Use a build preset to specify build options. The project binary directory
 490   is inferred from the ``configurePreset`` key. The current working directory
 491   must contain CMake preset files.
 492   See :manual:`preset <cmake-presets(7)>` for more details.
 493
 494 ``--list-presets``
 495   Lists the available build presets. The current working directory must
 496   contain CMake preset files.
 497
 498 ``--parallel [<jobs>], -j [<jobs>]``
 499   The maximum number of concurrent processes to use when building.
 500   If ``<jobs>`` is omitted the native build tool's default number is used.
 501
 502   The :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment variable, if set,
 503   specifies a default parallel level when this option is not given.
 504
 505   Some native build tools always build in parallel.  The use of ``<jobs>``
 506   value of ``1`` can be used to limit to a single job.
 507
 508 ``--target <tgt>..., -t <tgt>...``
 509   Build ``<tgt>`` instead of the default target.  Multiple targets may be
 510   given, separated by spaces.
 511
 512 ``--config <cfg>``
 513   For multi-configuration tools, choose configuration ``<cfg>``.
 514
 515 ``--clean-first``
 516   Build target ``clean`` first, then build.
 517   (To clean only, use ``--target clean``.)
 518
 519 ``--resolve-package-references=<on|off|only>``
 520   .. versionadded:: 3.23
 521
 522   Resolve remote package references from external package managers (e.g. NuGet)
 523   before build. When set to ``on`` (default), packages will be restored before
 524   building a target. When set to ``only``, the packages will be restored, but no
 525   build will be performed. When set to ``off``, no packages will be restored.
 526
 527   If the target does not define any package references, this option does nothing.
 528
 529   This setting can be specified in a build preset (using
 530   ``resolvePackageReferences``). The preset setting will be ignored, if this
 531   command line option is specified.
 532
 533   If no command line parameter or preset option are provided, an environment-
 534   specific cache variable will be evaluated to decide, if package restoration
 535   should be performed.
 536
 537   When using the Visual Studio generator, package references are defined
 538   using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references
 539   are restored using NuGet. It can be disabled by setting the
 540   ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``.
 541
 542 ``--use-stderr``
 543   Ignored.  Behavior is default in CMake >= 3.0.
 544
 545 ``--verbose, -v``
 546   Enable verbose output - if supported - including the build commands to be
 547   executed.
 548
 549   This option can be omitted if :envvar:`VERBOSE` environment variable or
 550   :variable:`CMAKE_VERBOSE_MAKEFILE` cached variable is set.
 551
 552
 553 ``--``
 554   Pass remaining options to the native tool.
 555
 556 Run ``cmake --build`` with no options for quick help.
 557
 558 Install a Project
 559 =================
 560
 561 CMake provides a command-line signature to install an already-generated
 562 project binary tree:
 563
 564 .. code-block:: shell
 565
 566   cmake --install <dir> [<options>]
 567
 568 This may be used after building a project to run installation without
 569 using the generated build system or the native build tool.
 570 The options are:
 571
 572 ``--install <dir>``
 573   Project binary directory to install. This is required and must be first.
 574
 575 ``--config <cfg>``
 576   For multi-configuration generators, choose configuration ``<cfg>``.
 577
 578 ``--component <comp>``
 579   Component-based install. Only install component ``<comp>``.
 580
 581 ``--default-directory-permissions <permissions>``
 582   Default directory install permissions. Permissions in format ``<u=rwx,g=rx,o=rx>``.
 583
 584 ``--prefix <prefix>``
 585   Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`.
 586
 587 ``--strip``
 588   Strip before installing.
 589
 590 ``-v, --verbose``
 591   Enable verbose output.
 592
 593   This option can be omitted if :envvar:`VERBOSE` environment variable is set.
 594
 595 Run ``cmake --install`` with no options for quick help.
 596
 597 Open a Project
 598 ==============
 599
 600 .. code-block:: shell
 601
 602   cmake --open <dir>
 603
 604 Open the generated project in the associated application.  This is only
 605 supported by some generators.
 606
 607
 608 .. _`Script Processing Mode`:
 609
 610 Run a Script
 611 ============
 612
 613 .. code-block:: shell
 614
 615   cmake [{-D <var>=<value>}...] -P <cmake-script-file> [-- <unparsed-options>...]
 616
 617 Process the given cmake file as a script written in the CMake
 618 language.  No configure or generate step is performed and the cache
 619 is not modified.  If variables are defined using ``-D``, this must be
 620 done before the ``-P`` argument.
 621
 622 Any options after ``--`` are not parsed by CMake, but they are still included
 623 in the set of :variable:`CMAKE_ARGV<n> <CMAKE_ARGV0>` variables passed to the
 624 script (including the ``--`` itself).
 625
 626
 627 .. _`Run a Command-Line Tool`:
 628
 629 Run a Command-Line Tool
 630 =======================
 631
 632 CMake provides builtin command-line tools through the signature
 633
 634 .. code-block:: shell
 635
 636   cmake -E <command> [<options>]
 637
 638 Run ``cmake -E`` or ``cmake -E help`` for a summary of commands.
 639 Available commands are:
 640
 641 ``capabilities``
 642   .. versionadded:: 3.7
 643
 644   Report cmake capabilities in JSON format. The output is a JSON object
 645   with the following keys:
 646
 647   ``version``
 648     A JSON object with version information. Keys are:
 649
 650     ``string``
 651       The full version string as displayed by cmake ``--version``.
 652     ``major``
 653       The major version number in integer form.
 654     ``minor``
 655       The minor version number in integer form.
 656     ``patch``
 657       The patch level in integer form.
 658     ``suffix``
 659       The cmake version suffix string.
 660     ``isDirty``
 661       A bool that is set if the cmake build is from a dirty tree.
 662
 663   ``generators``
 664     A list available generators. Each generator is a JSON object with the
 665     following keys:
 666
 667     ``name``
 668       A string containing the name of the generator.
 669     ``toolsetSupport``
 670       ``true`` if the generator supports toolsets and ``false`` otherwise.
 671     ``platformSupport``
 672       ``true`` if the generator supports platforms and ``false`` otherwise.
 673     ``supportedPlatforms``
 674       .. versionadded:: 3.21
 675
 676       Optional member that may be present when the generator supports
 677       platform specification via :variable:`CMAKE_GENERATOR_PLATFORM`
 678       (``-A ...``).  The value is a list of platforms known to be supported.
 679     ``extraGenerators``
 680       A list of strings with all the extra generators compatible with
 681       the generator.
 682
 683   ``fileApi``
 684     Optional member that is present when the :manual:`cmake-file-api(7)`
 685     is available.  The value is a JSON object with one member:
 686
 687     ``requests``
 688       A JSON array containing zero or more supported file-api requests.
 689       Each request is a JSON object with members:
 690
 691       ``kind``
 692         Specifies one of the supported :ref:`file-api object kinds`.
 693
 694       ``version``
 695         A JSON array whose elements are each a JSON object containing
 696         ``major`` and ``minor`` members specifying non-negative integer
 697         version components.
 698
 699   ``serverMode``
 700     ``true`` if cmake supports server-mode and ``false`` otherwise.
 701     Always false since CMake 3.20.
 702
 703 ``cat [--] <files>...``
 704   .. versionadded:: 3.18
 705
 706   Concatenate files and print on the standard output.
 707
 708   .. versionadded:: 3.24
 709     Added support for the double dash argument ``--``. This basic implementation
 710     of ``cat`` does not support any options, so using a option starting with
 711     ``-`` will result in an error. Use ``--`` to indicate the end of options, in
 712     case a file starts with ``-``.
 713
 714 ``chdir <dir> <cmd> [<arg>...]``
 715   Change the current working directory and run a command.
 716
 717 ``compare_files [--ignore-eol] <file1> <file2>``
 718   Check if ``<file1>`` is same as ``<file2>``. If files are the same,
 719   then returns ``0``, if not it returns ``1``.  In case of invalid
 720   arguments, it returns 2.
 721
 722   .. versionadded:: 3.14
 723     The ``--ignore-eol`` option implies line-wise comparison and ignores
 724     LF/CRLF differences.
 725
 726 ``copy <file>... <destination>``
 727   Copy files to ``<destination>`` (either file or directory).
 728   If multiple files are specified, the ``<destination>`` must be
 729   directory and it must exist. Wildcards are not supported.
 730   ``copy`` does follow symlinks. That means it does not copy symlinks,
 731   but the files or directories it point to.
 732
 733   .. versionadded:: 3.5
 734     Support for multiple input files.
 735
 736 ``copy_directory <dir>... <destination>``
 737   Copy content of ``<dir>...`` directories to ``<destination>`` directory.
 738   If ``<destination>`` directory does not exist it will be created.
 739   ``copy_directory`` does follow symlinks.
 740
 741   .. versionadded:: 3.5
 742     Support for multiple input directories.
 743
 744   .. versionadded:: 3.15
 745     The command now fails when the source directory does not exist.
 746     Previously it succeeded by creating an empty destination directory.
 747
 748 ``copy_if_different <file>... <destination>``
 749   Copy files to ``<destination>`` (either file or directory) if
 750   they have changed.
 751   If multiple files are specified, the ``<destination>`` must be
 752   directory and it must exist.
 753   ``copy_if_different`` does follow symlinks.
 754
 755   .. versionadded:: 3.5
 756     Support for multiple input files.
 757
 758 ``create_symlink <old> <new>``
 759   Create a symbolic link ``<new>`` naming ``<old>``.
 760
 761   .. versionadded:: 3.13
 762     Support for creating symlinks on Windows.
 763
 764   .. note::
 765     Path to where ``<new>`` symbolic link will be created has to exist beforehand.
 766
 767 ``create_hardlink <old> <new>``
 768   .. versionadded:: 3.19
 769
 770   Create a hard link ``<new>`` naming ``<old>``.
 771
 772   .. note::
 773     Path to where ``<new>`` hard link will be created has to exist beforehand.
 774     ``<old>`` has to exist beforehand.
 775
 776 ``echo [<string>...]``
 777   Displays arguments as text.
 778
 779 ``echo_append [<string>...]``
 780   Displays arguments as text but no new line.
 781
 782 ``env [--unset=NAME ...] [NAME=VALUE ...] [--] <command> [<arg>...]``
 783   .. versionadded:: 3.1
 784
 785   Run command in a modified environment.
 786
 787   .. versionadded:: 3.24
 788     Added support for the double dash argument ``--``. Use ``--`` to stop
 789     interpreting options/environment variables and treat the next argument as
 790     the command, even if it start with ``-`` or contains a ``=``.
 791
 792 ``environment``
 793   Display the current environment variables.
 794
 795 ``false``
 796   .. versionadded:: 3.16
 797
 798   Do nothing, with an exit code of 1.
 799
 800 ``make_directory <dir>...``
 801   Create ``<dir>`` directories.  If necessary, create parent
 802   directories too.  If a directory already exists it will be
 803   silently ignored.
 804
 805   .. versionadded:: 3.5
 806     Support for multiple input directories.
 807
 808 ``md5sum <file>...``
 809   Create MD5 checksum of files in ``md5sum`` compatible format::
 810
 811      351abe79cd3800b38cdfb25d45015a15  file1.txt
 812      052f86c15bbde68af55c7f7b340ab639  file2.txt
 813
 814 ``sha1sum <file>...``
 815   .. versionadded:: 3.10
 816
 817   Create SHA1 checksum of files in ``sha1sum`` compatible format::
 818
 819      4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
 820      1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt
 821
 822 ``sha224sum <file>...``
 823   .. versionadded:: 3.10
 824
 825   Create SHA224 checksum of files in ``sha224sum`` compatible format::
 826
 827      b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930  file1.txt
 828      6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24  file2.txt
 829
 830 ``sha256sum <file>...``
 831   .. versionadded:: 3.10
 832
 833   Create SHA256 checksum of files in ``sha256sum`` compatible format::
 834
 835      76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc  file1.txt
 836      15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea  file2.txt
 837
 838 ``sha384sum <file>...``
 839   .. versionadded:: 3.10
 840
 841   Create SHA384 checksum of files in ``sha384sum`` compatible format::
 842
 843      acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434  file1.txt
 844      668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d  file2.txt
 845
 846 ``sha512sum <file>...``
 847   .. versionadded:: 3.10
 848
 849   Create SHA512 checksum of files in ``sha512sum`` compatible format::
 850
 851      2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89  file1.txt
 852      7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d  file2.txt
 853
 854 ``remove [-f] <file>...``
 855   .. deprecated:: 3.17
 856
 857   Remove the file(s). The planned behavior was that if any of the
 858   listed files already do not exist, the command returns a non-zero exit code,
 859   but no message is logged. The ``-f`` option changes the behavior to return a
 860   zero exit code (i.e. success) in such situations instead.
 861   ``remove`` does not follow symlinks. That means it remove only symlinks
 862   and not files it point to.
 863
 864   The implementation was buggy and always returned 0. It cannot be fixed without
 865   breaking backwards compatibility. Use ``rm`` instead.
 866
 867 ``remove_directory <dir>...``
 868   .. deprecated:: 3.17
 869
 870   Remove ``<dir>`` directories and their contents. If a directory does
 871   not exist it will be silently ignored.
 872   Use ``rm`` instead.
 873
 874   .. versionadded:: 3.15
 875     Support for multiple directories.
 876
 877   .. versionadded:: 3.16
 878     If ``<dir>`` is a symlink to a directory, just the symlink will be removed.
 879
 880 ``rename <oldname> <newname>``
 881   Rename a file or directory (on one volume). If file with the ``<newname>`` name
 882   already exists, then it will be silently replaced.
 883
 884 ``rm [-rRf] [--] <file|dir>...``
 885   .. versionadded:: 3.17
 886
 887   Remove the files ``<file>`` or directories ``<dir>``.
 888   Use ``-r`` or ``-R`` to remove directories and their contents recursively.
 889   If any of the listed files/directories do not exist, the command returns a
 890   non-zero exit code, but no message is logged. The ``-f`` option changes
 891   the behavior to return a zero exit code (i.e. success) in such
 892   situations instead. Use ``--`` to stop interpreting options and treat all
 893   remaining arguments as paths, even if they start with ``-``.
 894
 895 ``server``
 896   Launch :manual:`cmake-server(7)` mode.
 897
 898 ``sleep <number>...``
 899   .. versionadded:: 3.0
 900
 901   Sleep for given number of seconds.
 902
 903 ``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]``
 904   Create or extract a tar or zip archive.  Options are:
 905
 906   ``c``
 907     Create a new archive containing the specified files.
 908     If used, the ``<pathname>...`` argument is mandatory.
 909
 910   ``x``
 911     Extract to disk from the archive.
 912
 913     .. versionadded:: 3.15
 914       The ``<pathname>...`` argument could be used to extract only selected files
 915       or directories.
 916       When extracting selected files or directories, you must provide their exact
 917       names including the path, as printed by list (``-t``).
 918
 919   ``t``
 920     List archive contents.
 921
 922     .. versionadded:: 3.15
 923       The ``<pathname>...`` argument could be used to list only selected files
 924       or directories.
 925
 926   ``v``
 927     Produce verbose output.
 928
 929   ``z``
 930     Compress the resulting archive with gzip.
 931
 932   ``j``
 933     Compress the resulting archive with bzip2.
 934
 935   ``J``
 936     .. versionadded:: 3.1
 937
 938     Compress the resulting archive with XZ.
 939
 940   ``--zstd``
 941     .. versionadded:: 3.15
 942
 943     Compress the resulting archive with Zstandard.
 944
 945   ``--files-from=<file>``
 946     .. versionadded:: 3.1
 947
 948     Read file names from the given file, one per line.
 949     Blank lines are ignored.  Lines may not start in ``-``
 950     except for ``--add-file=<name>`` to add files whose
 951     names start in ``-``.
 952
 953   ``--format=<format>``
 954     .. versionadded:: 3.3
 955
 956     Specify the format of the archive to be created.
 957     Supported formats are: ``7zip``, ``gnutar``, ``pax``,
 958     ``paxr`` (restricted pax, default), and ``zip``.
 959
 960   ``--mtime=<date>``
 961     .. versionadded:: 3.1
 962
 963     Specify modification time recorded in tarball entries.
 964
 965   ``--touch``
 966     .. versionadded:: 3.24
 967
 968     Use current local timestamp instead of extracting file timestamps
 969     from the archive.
 970
 971   ``--``
 972     .. versionadded:: 3.1
 973
 974     Stop interpreting options and treat all remaining arguments
 975     as file names, even if they start with ``-``.
 976
 977   .. versionadded:: 3.1
 978     LZMA (7zip) support.
 979
 980   .. versionadded:: 3.15
 981     The command now continues adding files to an archive even if some of the
 982     files are not readable.  This behavior is more consistent with the classic
 983     ``tar`` tool. The command now also parses all flags, and if an invalid flag
 984     was provided, a warning is issued.
 985
 986 ``time <command> [<args>...]``
 987   Run command and display elapsed time.
 988
 989   .. versionadded:: 3.5
 990     The command now properly passes arguments with spaces or special characters
 991     through to the child process. This may break scripts that worked around the
 992     bug with their own extra quoting or escaping.
 993
 994 ``touch <file>...``
 995   Creates ``<file>`` if file do not exist.
 996   If ``<file>`` exists, it is changing ``<file>`` access and modification times.
 997
 998 ``touch_nocreate <file>...``
 999   Touch a file if it exists but do not create it.  If a file does
1000   not exist it will be silently ignored.
1001
1002 ``true``
1003   .. versionadded:: 3.16
1004
1005   Do nothing, with an exit code of 0.
1006
1007 Windows-specific Command-Line Tools
1008 -----------------------------------
1009
1010 The following ``cmake -E`` commands are available only on Windows:
1011
1012 ``delete_regv <key>``
1013   Delete Windows registry value.
1014
1015 ``env_vs8_wince <sdkname>``
1016   .. versionadded:: 3.2
1017
1018   Displays a batch file which sets the environment for the provided
1019   Windows CE SDK installed in VS2005.
1020
1021 ``env_vs9_wince <sdkname>``
1022   .. versionadded:: 3.2
1023
1024   Displays a batch file which sets the environment for the provided
1025   Windows CE SDK installed in VS2008.
1026
1027 ``write_regv <key> <value>``
1028   Write Windows registry value.
1029
1030
1031 Run the Find-Package Tool
1032 =========================
1033
1034 CMake provides a pkg-config like helper for Makefile-based projects:
1035
1036 .. code-block:: shell
1037
1038   cmake --find-package [<options>]
1039
1040 It searches a package using :command:`find_package()` and prints the
1041 resulting flags to stdout.  This can be used instead of pkg-config
1042 to find installed libraries in plain Makefile-based projects or in
1043 autoconf-based projects (via ``share/aclocal/cmake.m4``).
1044
1045 .. note::
1046   This mode is not well-supported due to some technical limitations.
1047   It is kept for compatibility but should not be used in new projects.
1048
1049
1050 View Help
1051 =========
1052
1053 To print selected pages from the CMake documentation, use
1054
1055 .. code-block:: shell
1056
1057   cmake --help[-<topic>]
1058
1059 with one of the following options:
1060
1061 .. include:: OPTIONS_HELP.txt
1062
1063 To view the presets available for a project, use
1064
1065 .. code-block:: shell
1066
1067   cmake <source-dir> --list-presets
1068
1069
1070 .. _`CMake Exit Code`:
1071
1072 Return Value (Exit Code)
1073 ========================
1074
1075 Upon regular termination, the ``cmake`` executable returns the exit code ``0``.
1076
1077 If termination is caused by the command :command:`message(FATAL_ERROR)`,
1078 or another error condition, then a non-zero exit code is returned.
1079
1080
1081 See Also
1082 ========
1083
1084 .. include:: LINKS.txt