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
 109 Generate a Project Buildsystem
 110 ==============================
 111
 112 Run CMake with one of the following command signatures to specify the
 113 source and build trees and generate a buildsystem:
 114
 115 ``cmake [<options>] <path-to-source>``
 116   Uses the current working directory as the build tree, and
 117   ``<path-to-source>`` as the source tree.  The specified path may
 118   be absolute or relative to the current working directory.
 119   The source tree must contain a ``CMakeLists.txt`` file and must
 120   *not* contain a ``CMakeCache.txt`` file because the latter
 121   identifies an existing build tree.  For example:
 122
 123   .. code-block:: console
 124
 125     $ mkdir build ; cd build
 126     $ cmake ../src
 127
 128 ``cmake [<options>] <path-to-existing-build>``
 129   Uses ``<path-to-existing-build>`` as the build tree, and loads the
 130   path to the source tree from its ``CMakeCache.txt`` file, which must
 131   have already been generated by a previous run of CMake.  The specified
 132   path may be absolute or relative to the current working directory.
 133   For example:
 134
 135   .. code-block:: console
 136
 137     $ cd build
 138     $ cmake .
 139
 140 ``cmake [<options>] -S <path-to-source> -B <path-to-build>``
 141   Uses ``<path-to-build>`` as the build tree and ``<path-to-source>``
 142   as the source tree.  The specified paths may be absolute or relative
 143   to the current working directory.  The source tree must contain a
 144   ``CMakeLists.txt`` file.  The build tree will be created automatically
 145   if it does not already exist.  For example:
 146
 147   .. code-block:: console
 148
 149     $ cmake -S src -B build
 150
 151 In all cases the ``<options>`` may be zero or more of the `Options`_ below.
 152
 153 After generating a buildsystem one may use the corresponding native
 154 build tool to build the project.  For example, after using the
 155 :generator:`Unix Makefiles` generator one may run ``make`` directly:
 156
 157   .. code-block:: console
 158
 159     $ make
 160     $ make install
 161
 162 Alternatively, one may use **cmake** to `Build a Project`_ by
 163 automatically choosing and invoking the appropriate native build tool.
 164
 165 .. _`CMake Options`:
 166
 167 Options
 168 -------
 169
 170 .. include:: OPTIONS_BUILD.txt
 171
 172 ``-L[A][H]``
 173  List non-advanced cached variables.
 174
 175  List ``CACHE`` variables will run CMake and list all the variables from
 176  the CMake ``CACHE`` that are not marked as ``INTERNAL`` or :prop_cache:`ADVANCED`.
 177  This will effectively display current CMake settings, which can then be
 178  changed with ``-D`` option.  Changing some of the variables may result
 179  in more variables being created.  If ``A`` is specified, then it will
 180  display also advanced variables.  If ``H`` is specified, it will also
 181  display help for each variable.
 182
 183 ``-N``
 184  View mode only.
 185
 186  Only load the cache.  Do not actually run configure and generate
 187  steps.
 188
 189 ``--graphviz=[file]``
 190  Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more.
 191
 192  Generate a graphviz input file that will contain all the library and
 193  executable dependencies in the project.  See the documentation for
 194  :module:`CMakeGraphVizOptions` for more details.
 195
 196 ``--system-information [file]``
 197  Dump information about this system.
 198
 199  Dump a wide range of information about the current system.  If run
 200  from the top of a binary tree for a CMake project it will dump
 201  additional information such as the cache, log files etc.
 202
 203 ``--log-level=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>``
 204  Set the log level.
 205
 206  The :command:`message` command will only output messages of the specified
 207  log level or higher.  The default log level is ``STATUS``.
 208
 209  To make a log level persist between CMake runs, set
 210  :variable:`CMAKE_MESSAGE_LOG_LEVEL` as a cache variable instead.
 211  If both the command line option and the variable are given, the command line
 212  option takes precedence.
 213
 214  For backward compatibility reasons, ``--loglevel`` is also accepted as a
 215  synonym for this option.
 216
 217 ``--log-context``
 218  Enable the :command:`message` command outputting context attached to each
 219  message.
 220
 221  This option turns on showing context for the current CMake run only.
 222  To make showing the context persistent for all subsequent CMake runs, set
 223  :variable:`CMAKE_MESSAGE_CONTEXT_SHOW` as a cache variable instead.
 224  When this command line option is given, :variable:`CMAKE_MESSAGE_CONTEXT_SHOW`
 225  is ignored.
 226
 227 ``--debug-trycompile``
 228  Do not delete the :command:`try_compile` build tree.
 229  Only useful on one :command:`try_compile` at a time.
 230
 231  Do not delete the files and directories created for :command:`try_compile`
 232  calls.  This is useful in debugging failed try_compiles.  It may
 233  however change the results of the try-compiles as old junk from a
 234  previous try-compile may cause a different test to either pass or
 235  fail incorrectly.  This option is best used for one try-compile at a
 236  time, and only when debugging.
 237
 238 ``--debug-output``
 239  Put cmake in a debug mode.
 240
 241  Print extra information during the cmake run like stack traces with
 242  :command:`message(SEND_ERROR)` calls.
 243
 244 ``--debug-find``
 245  Put cmake find commands in a debug mode.
 246
 247  Print extra find call information during the cmake run to standard
 248  error. Output is designed for human consumption and not for parsing.
 249  See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging
 250  a more local part of the project.
 251
 252 ``--trace``
 253  Put cmake in trace mode.
 254
 255  Print a trace of all calls made and from where.
 256
 257 ``--trace-expand``
 258  Put cmake in trace mode.
 259
 260  Like ``--trace``, but with variables expanded.
 261
 262 ``--trace-format=<format>``
 263  Put cmake in trace mode and sets the trace output format.
 264
 265  ``<format>`` can be one of the following values.
 266
 267    ``human``
 268      Prints each trace line in a human-readable format. This is the
 269      default format.
 270
 271    ``json-v1``
 272      Prints each line as a separate JSON document. Each document is
 273      separated by a newline ( ``\n`` ). It is guaranteed that no
 274      newline characters will be present inside a JSON document.
 275
 276      JSON trace format:
 277
 278      .. code-block:: json
 279
 280        {
 281          "file": "/full/path/to/the/CMake/file.txt",
 282          "line": 0,
 283          "cmd": "add_executable",
 284          "args": ["foo", "bar"],
 285          "time": 1579512535.9687231,
 286          "frame": 2
 287        }
 288
 289      The members are:
 290
 291      ``file``
 292        The full path to the CMake source file where the function
 293        was called.
 294
 295      ``line``
 296        The line in ``file`` of the function call.
 297
 298      ``cmd``
 299        The name of the function that was called.
 300
 301      ``args``
 302        A string list of all function parameters.
 303
 304      ``time``
 305        Timestamp (seconds since epoch) of the function call.
 306
 307      ``frame``
 308        Stack frame depth of the function that was called.
 309
 310      Additionally, the first JSON document outputted contains the
 311      ``version`` key for the current major and minor version of the
 312
 313      JSON trace format:
 314
 315      .. code-block:: json
 316
 317        {
 318          "version": {
 319            "major": 1,
 320            "minor": 0
 321          }
 322        }
 323
 324      The members are:
 325
 326      ``version``
 327        Indicates the version of the JSON format. The version has a
 328        major and minor components following semantic version conventions.
 329
 330 ``--trace-source=<file>``
 331  Put cmake in trace mode, but output only lines of a specified file.
 332
 333  Multiple options are allowed.
 334
 335 ``--trace-redirect=<file>``
 336  Put cmake in trace mode and redirect trace output to a file instead of stderr.
 337
 338 ``--warn-uninitialized``
 339  Warn about uninitialized values.
 340
 341  Print a warning when an uninitialized variable is used.
 342
 343 ``--warn-unused-vars``
 344  Warn about unused variables.
 345
 346  Find variables that are declared or set, but not used.
 347
 348 ``--no-warn-unused-cli``
 349  Don't warn about command line options.
 350
 351  Don't find variables that are declared on the command line, but not
 352  used.
 353
 354 ``--check-system-vars``
 355  Find problems with variable usage in system files.
 356
 357  Normally, unused and uninitialized variables are searched for only
 358  in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`.
 359  This flag tells CMake to warn about other files as well.
 360
 361 .. _`Build Tool Mode`:
 362
 363 Build a Project
 364 ===============
 365
 366 CMake provides a command-line signature to build an already-generated
 367 project binary tree:
 368
 369 .. code-block:: shell
 370
 371   cmake --build <dir> [<options>] [-- <build-tool-options>]
 372
 373 This abstracts a native build tool's command-line interface with the
 374 following options:
 375
 376 ``--build <dir>``
 377   Project binary directory to be built.  This is required and must be first.
 378
 379 ``--parallel [<jobs>], -j [<jobs>]``
 380   The maximum number of concurrent processes to use when building.
 381   If ``<jobs>`` is omitted the native build tool's default number is used.
 382
 383   The :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment variable, if set,
 384   specifies a default parallel level when this option is not given.
 385
 386   Some native build tools always build in parallel.  The use of ``<jobs>``
 387   value of ``1`` can be used to limit to a single job.
 388
 389 ``--target <tgt>..., -t <tgt>...``
 390   Build ``<tgt>`` instead of the default target.  Multiple targets may be
 391   given, separated by spaces.
 392
 393 ``--config <cfg>``
 394   For multi-configuration tools, choose configuration ``<cfg>``.
 395
 396 ``--clean-first``
 397   Build target ``clean`` first, then build.
 398   (To clean only, use ``--target clean``.)
 399
 400 ``--use-stderr``
 401   Ignored.  Behavior is default in CMake >= 3.0.
 402
 403 ``--verbose, -v``
 404   Enable verbose output - if supported - including the build commands to be
 405   executed.
 406
 407   This option can be omitted if :envvar:`VERBOSE` environment variable or
 408   :variable:`CMAKE_VERBOSE_MAKEFILE` cached variable is set.
 409
 410
 411 ``--``
 412   Pass remaining options to the native tool.
 413
 414 Run ``cmake --build`` with no options for quick help.
 415
 416 Install a Project
 417 =================
 418
 419 CMake provides a command-line signature to install an already-generated
 420 project binary tree:
 421
 422 .. code-block:: shell
 423
 424   cmake --install <dir> [<options>]
 425
 426 This may be used after building a project to run installation without
 427 using the generated build system or the native build tool.
 428 The options are:
 429
 430 ``--install <dir>``
 431   Project binary directory to install. This is required and must be first.
 432
 433 ``--config <cfg>``
 434   For multi-configuration generators, choose configuration ``<cfg>``.
 435
 436 ``--component <comp>``
 437   Component-based install. Only install component ``<comp>``.
 438
 439 ``--prefix <prefix>``
 440   Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`.
 441
 442 ``--strip``
 443   Strip before installing.
 444
 445 ``-v, --verbose``
 446   Enable verbose output.
 447
 448   This option can be omitted if :envvar:`VERBOSE` environment variable is set.
 449
 450 Run ``cmake --install`` with no options for quick help.
 451
 452 Open a Project
 453 ==============
 454
 455 .. code-block:: shell
 456
 457   cmake --open <dir>
 458
 459 Open the generated project in the associated application.  This is only
 460 supported by some generators.
 461
 462
 463 .. _`Script Processing Mode`:
 464
 465 Run a Script
 466 ============
 467
 468 .. code-block:: shell
 469
 470   cmake [{-D <var>=<value>}...] -P <cmake-script-file>
 471
 472 Process the given cmake file as a script written in the CMake
 473 language.  No configure or generate step is performed and the cache
 474 is not modified.  If variables are defined using ``-D``, this must be
 475 done before the ``-P`` argument.
 476
 477
 478 Run a Command-Line Tool
 479 =======================
 480
 481 CMake provides builtin command-line tools through the signature
 482
 483 .. code-block:: shell
 484
 485   cmake -E <command> [<options>]
 486
 487 Run ``cmake -E`` or ``cmake -E help`` for a summary of commands.
 488 Available commands are:
 489
 490 ``capabilities``
 491   Report cmake capabilities in JSON format. The output is a JSON object
 492   with the following keys:
 493
 494   ``version``
 495     A JSON object with version information. Keys are:
 496
 497     ``string``
 498       The full version string as displayed by cmake ``--version``.
 499     ``major``
 500       The major version number in integer form.
 501     ``minor``
 502       The minor version number in integer form.
 503     ``patch``
 504       The patch level in integer form.
 505     ``suffix``
 506       The cmake version suffix string.
 507     ``isDirty``
 508       A bool that is set if the cmake build is from a dirty tree.
 509
 510   ``generators``
 511     A list available generators. Each generator is a JSON object with the
 512     following keys:
 513
 514     ``name``
 515       A string containing the name of the generator.
 516     ``toolsetSupport``
 517       ``true`` if the generator supports toolsets and ``false`` otherwise.
 518     ``platformSupport``
 519       ``true`` if the generator supports platforms and ``false`` otherwise.
 520     ``extraGenerators``
 521       A list of strings with all the extra generators compatible with
 522       the generator.
 523
 524   ``fileApi``
 525     Optional member that is present when the :manual:`cmake-file-api(7)`
 526     is available.  The value is a JSON object with one member:
 527
 528     ``requests``
 529       A JSON array containing zero or more supported file-api requests.
 530       Each request is a JSON object with members:
 531
 532       ``kind``
 533         Specifies one of the supported :ref:`file-api object kinds`.
 534
 535       ``version``
 536         A JSON array whose elements are each a JSON object containing
 537         ``major`` and ``minor`` members specifying non-negative integer
 538         version components.
 539
 540   ``serverMode``
 541     ``true`` if cmake supports server-mode and ``false`` otherwise.
 542
 543 ``chdir <dir> <cmd> [<arg>...]``
 544   Change the current working directory and run a command.
 545
 546 ``compare_files [--ignore-eol] <file1> <file2>``
 547   Check if ``<file1>`` is same as ``<file2>``. If files are the same,
 548   then returns ``0``, if not it returns ``1``.  The ``--ignore-eol`` option
 549   implies line-wise comparison and ignores LF/CRLF differences.
 550
 551 ``copy <file>... <destination>``
 552   Copy files to ``<destination>`` (either file or directory).
 553   If multiple files are specified, the ``<destination>`` must be
 554   directory and it must exist. Wildcards are not supported.
 555   ``copy`` does follow symlinks. That means it does not copy symlinks,
 556   but the files or directories it point to.
 557
 558 ``copy_directory <dir>... <destination>``
 559   Copy content of ``<dir>...`` directories to ``<destination>`` directory.
 560   If ``<destination>`` directory does not exist it will be created.
 561   ``copy_directory`` does follow symlinks.
 562
 563 ``copy_if_different <file>... <destination>``
 564   Copy files to ``<destination>`` (either file or directory) if
 565   they have changed.
 566   If multiple files are specified, the ``<destination>`` must be
 567   directory and it must exist.
 568   ``copy_if_different`` does follow symlinks.
 569
 570 ``create_symlink <old> <new>``
 571   Create a symbolic link ``<new>`` naming ``<old>``.
 572
 573   .. note::
 574     Path to where ``<new>`` symbolic link will be created has to exist beforehand.
 575
 576 ``echo [<string>...]``
 577   Displays arguments as text.
 578
 579 ``echo_append [<string>...]``
 580   Displays arguments as text but no new line.
 581
 582 ``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...``
 583   Run command in a modified environment.
 584
 585 ``environment``
 586   Display the current environment variables.
 587
 588 ``false``
 589   Do nothing, with an exit code of 1.
 590
 591 ``make_directory <dir>...``
 592   Create ``<dir>`` directories.  If necessary, create parent
 593   directories too.  If a directory already exists it will be
 594   silently ignored.
 595
 596 ``md5sum <file>...``
 597   Create MD5 checksum of files in ``md5sum`` compatible format::
 598
 599      351abe79cd3800b38cdfb25d45015a15  file1.txt
 600      052f86c15bbde68af55c7f7b340ab639  file2.txt
 601
 602 ``sha1sum <file>...``
 603   Create SHA1 checksum of files in ``sha1sum`` compatible format::
 604
 605      4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
 606      1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt
 607
 608 ``sha224sum <file>...``
 609   Create SHA224 checksum of files in ``sha224sum`` compatible format::
 610
 611      b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930  file1.txt
 612      6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24  file2.txt
 613
 614 ``sha256sum <file>...``
 615   Create SHA256 checksum of files in ``sha256sum`` compatible format::
 616
 617      76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc  file1.txt
 618      15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea  file2.txt
 619
 620 ``sha384sum <file>...``
 621   Create SHA384 checksum of files in ``sha384sum`` compatible format::
 622
 623      acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434  file1.txt
 624      668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d  file2.txt
 625
 626 ``sha512sum <file>...``
 627   Create SHA512 checksum of files in ``sha512sum`` compatible format::
 628
 629      2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89  file1.txt
 630      7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d  file2.txt
 631
 632 ``remove [-f] <file>...``
 633   .. deprecated:: 3.17
 634
 635   Remove the file(s). The planned behaviour was that if any of the
 636   listed files already do not exist, the command returns a non-zero exit code,
 637   but no message is logged. The ``-f`` option changes the behavior to return a
 638   zero exit code (i.e. success) in such situations instead.
 639   ``remove`` does not follow symlinks. That means it remove only symlinks
 640   and not files it point to.
 641
 642   The implementation was buggy and always returned 0. It cannot be fixed without
 643   breaking backwards compatibility. Use ``rm`` instead.
 644
 645 ``remove_directory <dir>...``
 646   .. deprecated:: 3.17
 647
 648   Remove ``<dir>`` directories and their contents. If a directory does
 649   not exist it will be silently ignored.  If ``<dir>`` is a symlink to
 650   a directory, just the symlink will be removed.
 651   Use ``rm`` instead.
 652
 653 ``rename <oldname> <newname>``
 654   Rename a file or directory (on one volume). If file with the ``<newname>`` name
 655   already exists, then it will be silently replaced.
 656
 657 ``rm [-rRf] <file> <dir>...``
 658   Remove the files ``<file>`` or directories ``dir``.
 659   Use ``-r`` or ``-R`` to remove directories and their contents recursively.
 660   If any of the listed files/directories do not exist, the command returns a
 661   non-zero exit code, but no message is logged. The ``-f`` option changes
 662   the behavior to return a zero exit code (i.e. success) in such
 663   situations instead.
 664
 665 ``server``
 666   Launch :manual:`cmake-server(7)` mode.
 667
 668 ``sleep <number>...``
 669   Sleep for given number of seconds.
 670
 671 ``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]``
 672   Create or extract a tar or zip archive.  Options are:
 673
 674   ``c``
 675     Create a new archive containing the specified files.
 676     If used, the ``<pathname>...`` argument is mandatory.
 677   ``x``
 678     Extract to disk from the archive.
 679     The ``<pathname>...`` argument could be used to extract only selected files
 680     or directories.
 681     When extracting selected files or directories, you must provide their exact
 682     names including the path, as printed by list (``-t``).
 683   ``t``
 684     List archive contents.
 685     The ``<pathname>...`` argument could be used to list only selected files
 686     or directories.
 687   ``v``
 688     Produce verbose output.
 689   ``z``
 690     Compress the resulting archive with gzip.
 691   ``j``
 692     Compress the resulting archive with bzip2.
 693   ``J``
 694     Compress the resulting archive with XZ.
 695   ``--zstd``
 696     Compress the resulting archive with Zstandard.
 697   ``--files-from=<file>``
 698     Read file names from the given file, one per line.
 699     Blank lines are ignored.  Lines may not start in ``-``
 700     except for ``--add-file=<name>`` to add files whose
 701     names start in ``-``.
 702   ``--format=<format>``
 703     Specify the format of the archive to be created.
 704     Supported formats are: ``7zip``, ``gnutar``, ``pax``,
 705     ``paxr`` (restricted pax, default), and ``zip``.
 706   ``--mtime=<date>``
 707     Specify modification time recorded in tarball entries.
 708   ``--``
 709     Stop interpreting options and treat all remaining arguments
 710     as file names, even if they start with ``-``.
 711
 712
 713 ``time <command> [<args>...]``
 714   Run command and display elapsed time.
 715
 716 ``touch <file>...``
 717   Creates ``<file>`` if file do not exist.
 718   If ``<file>`` exists, it is changing ``<file>`` access and modification times.
 719
 720 ``touch_nocreate <file>...``
 721   Touch a file if it exists but do not create it.  If a file does
 722   not exist it will be silently ignored.
 723
 724 ``true``
 725   Do nothing, with an exit code of 0.
 726
 727 Windows-specific Command-Line Tools
 728 -----------------------------------
 729
 730 The following ``cmake -E`` commands are available only on Windows:
 731
 732 ``delete_regv <key>``
 733   Delete Windows registry value.
 734
 735 ``env_vs8_wince <sdkname>``
 736   Displays a batch file which sets the environment for the provided
 737   Windows CE SDK installed in VS2005.
 738
 739 ``env_vs9_wince <sdkname>``
 740   Displays a batch file which sets the environment for the provided
 741   Windows CE SDK installed in VS2008.
 742
 743 ``write_regv <key> <value>``
 744   Write Windows registry value.
 745
 746
 747 Run the Find-Package Tool
 748 =========================
 749
 750 CMake provides a pkg-config like helper for Makefile-based projects:
 751
 752 .. code-block:: shell
 753
 754   cmake --find-package [<options>]
 755
 756 It searches a package using :command:`find_package()` and prints the
 757 resulting flags to stdout.  This can be used instead of pkg-config
 758 to find installed libraries in plain Makefile-based projects or in
 759 autoconf-based projects (via ``share/aclocal/cmake.m4``).
 760
 761 .. note::
 762   This mode is not well-supported due to some technical limitations.
 763   It is kept for compatibility but should not be used in new projects.
 764
 765
 766 View Help
 767 =========
 768
 769 To print selected pages from the CMake documentation, use
 770
 771 .. code-block:: shell
 772
 773   cmake --help[-<topic>]
 774
 775 with one of the following options:
 776
 777 .. include:: OPTIONS_HELP.txt
 778
 779
 780 See Also
 781 ========
 782
 783 .. include:: LINKS.txt