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