cmake.1.rst 21.2 KB
Newer Older
1 2
.. cmake-manual-description: CMake Command-Line Reference

3 4 5
cmake(1)
********

6 7
Synopsis
========
8

9
.. parsed-literal::
10

11
 `Generate a Project Buildsystem`_
12 13
  cmake [<options>] <path-to-source>
  cmake [<options>] <path-to-existing-build>
14 15 16 17 18
  cmake [<options>] -S <path-to-source> -B <path-to-build>

 `Build a Project`_
  cmake --build <dir> [<options>] [-- <build-tool-options>]

19 20 21
 `Install a Project`_
  cmake --install <dir> [<options>]

22 23 24 25 26 27 28 29 30 31 32 33 34 35
 `Open a Project`_
  cmake --open <dir>

 `Run a Script`_
  cmake [{-D <var>=<value>}...] -P <cmake-script-file>

 `Run a Command-Line Tool`_
  cmake -E <command> [<options>]

 `Run the Find-Package Tool`_
  cmake --find-package [<options>]

 `View Help`_
  cmake --help[-<topic>]
36

37 38 39
Description
===========

40 41 42 43 44
The **cmake** executable is the command-line interface of the cross-platform
buildsystem generator CMake.  The above `Synopsis`_ lists various actions
the tool can perform as described in sections below.

To build a software project with CMake, `Generate a Project Buildsystem`_.
45 46
Optionally use **cmake** to `Build a Project`_, `Install a Project`_ or just
run the corresponding build tool (e.g. ``make``) directly.  **cmake** can also
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106
be used to `View Help`_.

The other actions are meant for use by software developers writing
scripts in the :manual:`CMake language <cmake-language(7)>` to support
their builds.

For graphical user interfaces that may be used in place of **cmake**,
see :manual:`ccmake <ccmake(1)>` and :manual:`cmake-gui <cmake-gui(1)>`.
For command-line interfaces to the CMake testing and packaging facilities,
see :manual:`ctest <ctest(1)>` and :manual:`cpack <cpack(1)>`.

For more information on CMake at large, `see also`_ the links at the end
of this manual.


Introduction to CMake Buildsystems
==================================

A *buildsystem* describes how to build a project's executables and libraries
from its source code using a *build tool* to automate the process.  For
example, a buildsystem may be a ``Makefile`` for use with a command-line
``make`` tool or a project file for an Integrated Development Environment
(IDE).  In order to avoid maintaining multiple such buildsystems, a project
may specify its buildsystem abstractly using files written in the
:manual:`CMake language <cmake-language(7)>`.  From these files CMake
generates a preferred buildsystem locally for each user through a backend
called a *generator*.

To generate a buildsystem with CMake, the following must be selected:

Source Tree
  The top-level directory containing source files provided by the project.
  The project specifies its buildsystem using files as described in the
  :manual:`cmake-language(7)` manual, starting with a top-level file named
  ``CMakeLists.txt``.  These files specify build targets and their
  dependencies as described in the :manual:`cmake-buildsystem(7)` manual.

Build Tree
  The top-level directory in which buildsystem files and build output
  artifacts (e.g. executables and libraries) are to be stored.
  CMake will write a ``CMakeCache.txt`` file to identify the directory
  as a build tree and store persistent information such as buildsystem
  configuration options.

  To maintain a pristine source tree, perform an *out-of-source* build
  by using a separate dedicated build tree.  An *in-source* build in
  which the build tree is placed in the same directory as the source
  tree is also supported, but discouraged.

Generator
  This chooses the kind of buildsystem to generate.  See the
  :manual:`cmake-generators(7)` manual for documentation of all generators.
  Run ``cmake --help`` to see a list of generators available locally.
  Optionally use the ``-G`` option below to specify a generator, or simply
  accept the default CMake chooses for the current platform.

  When using one of the :ref:`Command-Line Build Tool Generators`
  CMake expects that the environment needed by the compiler toolchain
  is already configured in the shell.  When using one of the
  :ref:`IDE Build Tool Generators`, no particular environment is needed.
107

108 109 110 111

Generate a Project Buildsystem
==============================

112 113
Run CMake with one of the following command signatures to specify the
source and build trees and generate a buildsystem:
114

115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135
``cmake [<options>] <path-to-source>``
  Uses the current working directory as the build tree, and
  ``<path-to-source>`` as the source tree.  The specified path may
  be absolute or relative to the current working directory.
  The source tree must contain a ``CMakeLists.txt`` file and must
  *not* contain a ``CMakeCache.txt`` file because the latter
  identifies an existing build tree.  For example:

  .. code-block:: console

    $ mkdir build ; cd build
    $ cmake ../src

``cmake [<options>] <path-to-existing-build>``
  Uses ``<path-to-existing-build>`` as the build tree, and loads the
  path to the source tree from its ``CMakeCache.txt`` file, which must
  have already been generated by a previous run of CMake.  The specified
  path may be absolute or relative to the current working directory.
  For example:

  .. code-block:: console
136

137 138
    $ cd build
    $ cmake .
139

140 141 142 143 144 145 146 147 148 149
``cmake [<options>] -S <path-to-source> -B <path-to-build>``
  Uses ``<path-to-build>`` as the build tree and ``<path-to-source>``
  as the source tree.  The specified paths may be absolute or relative
  to the current working directory.  The source tree must contain a
  ``CMakeLists.txt`` file.  The build tree will be created automatically
  if it does not already exist.  For example:

  .. code-block:: console

    $ cmake -S src -B build
150 151 152

In all cases the ``<options>`` may be zero or more of the `Options`_ below.

153 154 155 156 157 158 159 160 161 162 163 164
After generating a buildsystem one may use the corresponding native
build tool to build the project.  For example, after using the
:generator:`Unix Makefiles` generator one may run ``make`` directly:

  .. code-block:: console

    $ make
    $ make install

Alternatively, one may use **cmake** to `Build a Project`_ by
automatically choosing and invoking the appropriate native build tool.

165 166
.. _`CMake Options`:

167
Options
168
-------
169

170
.. include:: OPTIONS_BUILD.txt
171

172 173
``-L[A][H]``
 List non-advanced cached variables.
174

175 176 177 178 179 180
 List ``CACHE`` variables will run CMake and list all the variables from
 the CMake ``CACHE`` that are not marked as ``INTERNAL`` or :prop_cache:`ADVANCED`.
 This will effectively display current CMake settings, which can then be
 changed with ``-D`` option.  Changing some of the variables may result
 in more variables being created.  If ``A`` is specified, then it will
 display also advanced variables.  If ``H`` is specified, it will also
181
 display help for each variable.
182

183 184
``-N``
 View mode only.
185

186 187
 Only load the cache.  Do not actually run configure and generate
 steps.
188

189
``--graphviz=[file]``
190
 Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more.
191

192 193
 Generate a graphviz input file that will contain all the library and
 executable dependencies in the project.  See the documentation for
194
 :module:`CMakeGraphVizOptions` for more details.
195

196 197
``--system-information [file]``
 Dump information about this system.
198

199 200 201
 Dump a wide range of information about the current system.  If run
 from the top of a binary tree for a CMake project it will dump
 additional information such as the cache, log files etc.
202

203 204 205 206 207 208
``--loglevel=<error|warning|notice|status|verbose|debug|trace>``
 Set the log level.

 The :command:`message` command will only output messages of the specified
 log level or higher.  The default log level is ``status``.

209
``--debug-trycompile``
210 211
 Do not delete the :command:`try_compile` build tree.
 Only useful on one :command:`try_compile` at a time.
212

213
 Do not delete the files and directories created for :command:`try_compile`
214 215 216 217 218
 calls.  This is useful in debugging failed try_compiles.  It may
 however change the results of the try-compiles as old junk from a
 previous try-compile may cause a different test to either pass or
 fail incorrectly.  This option is best used for one try-compile at a
 time, and only when debugging.
219

220 221
``--debug-output``
 Put cmake in a debug mode.
222

223
 Print extra information during the cmake run like stack traces with
224
 :command:`message(SEND_ERROR)` calls.
225

226 227
``--trace``
 Put cmake in trace mode.
228

229 230 231 232 233 234
 Print a trace of all calls made and from where.

``--trace-expand``
 Put cmake in trace mode.

 Like ``--trace``, but with variables expanded.
235

236 237 238 239 240
``--trace-source=<file>``
 Put cmake in trace mode, but output only lines of a specified file.

 Multiple options are allowed.

241 242
``--warn-uninitialized``
 Warn about uninitialized values.
243

244
 Print a warning when an uninitialized variable is used.
245

246 247
``--warn-unused-vars``
 Warn about unused variables.
248

249
 Find variables that are declared or set, but not used.
250

251 252
``--no-warn-unused-cli``
 Don't warn about command line options.
253

254 255
 Don't find variables that are declared on the command line, but not
 used.
256

257 258
``--check-system-vars``
 Find problems with variable usage in system files.
259

260
 Normally, unused and uninitialized variables are searched for only
261 262
 in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`.
 This flag tells CMake to warn about other files as well.
263

264 265
.. _`Build Tool Mode`:

266
Build a Project
267 268 269
===============

CMake provides a command-line signature to build an already-generated
270 271 272
project binary tree:

.. code-block:: shell
273

274
  cmake --build <dir> [<options>] [-- <build-tool-options>]
275 276 277 278 279 280 281

This abstracts a native build tool's command-line interface with the
following options:

``--build <dir>``
  Project binary directory to be built.  This is required and must be first.

282
``--parallel [<jobs>], -j [<jobs>]``
283 284 285 286 287 288
  The maximum number of concurrent processes to use when building.
  If ``<jobs>`` is omitted the native build tool's default number is used.

  The :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` environment variable, if set,
  specifies a default parallel level when this option is not given.

289 290 291
  Some native build tools always build in parallel.  The use of ``<jobs>``
  value of ``1`` can be used to limit to a single job.

292
``--target <tgt>..., -t <tgt>...``
293
  Build ``<tgt>`` instead of default targets.  May be specified multiple times.
294 295 296 297 298 299 300 301 302 303 304

``--config <cfg>``
  For multi-configuration tools, choose configuration ``<cfg>``.

``--clean-first``
  Build target ``clean`` first, then build.
  (To clean only, use ``--target clean``.)

``--use-stderr``
  Ignored.  Behavior is default in CMake >= 3.0.

305
``--verbose, -v``
306 307 308 309 310 311 312
  Enable verbose output - if supported - including the build commands to be
  executed.

  This option can be omitted if :envvar:`VERBOSE` environment variable or
  :variable:`CMAKE_VERBOSE_MAKEFILE` cached variable is set.


313 314 315 316 317
``--``
  Pass remaining options to the native tool.

Run ``cmake --build`` with no options for quick help.

318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341
Install a Project
=================

CMake provides a command-line signature to install an already-generated
project binary tree:

.. code-block:: shell

  cmake --install <dir> [<options>]

This may be used after building a project to run installation without
using the generated build system or the native build tool.
The options are:

``--install <dir>``
  Project binary directory to install. This is required and must be first.

``--config <cfg>``
  For multi-configuration tools, choose configuration ``<cfg>``.

``--component <comp>``
  Component-based install. Only install component ``<comp>``.

``--prefix <prefix>``
342
  The installation prefix :variable:`CMAKE_INSTALL_PREFIX`.
343 344

``--strip``
345
  Strip before installing by setting ``CMAKE_INSTALL_DO_STRIP``.
346 347 348 349 350 351 352

``-v, --verbose``
  Enable verbose output.

  This option can be omitted if :envvar:`VERBOSE` environment variable is set.

Run ``cmake --install`` with no options for quick help.
353

354 355
Open a Project
==============
356

357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375
.. code-block:: shell

  cmake --open <dir>

Open the generated project in the associated application.  This is only
supported by some generators.


.. _`Script Processing Mode`:

Run a Script
============

.. code-block:: shell

  cmake [{-D <var>=<value>}...] -P <cmake-script-file>

Process the given cmake file as a script written in the CMake
language.  No configure or generate step is performed and the cache
376 377
is not modified.  If variables are defined using ``-D``, this must be
done before the ``-P`` argument.
378 379 380 381 382 383 384 385 386 387


Run a Command-Line Tool
=======================

CMake provides builtin command-line tools through the signature

.. code-block:: shell

  cmake -E <command> [<options>]
388 389 390 391

Run ``cmake -E`` or ``cmake -E help`` for a summary of commands.
Available commands are:

392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425
``capabilities``
  Report cmake capabilities in JSON format. The output is a JSON object
  with the following keys:

  ``version``
    A JSON object with version information. Keys are:

    ``string``
      The full version string as displayed by cmake ``--version``.
    ``major``
      The major version number in integer form.
    ``minor``
      The minor version number in integer form.
    ``patch``
      The patch level in integer form.
    ``suffix``
      The cmake version suffix string.
    ``isDirty``
      A bool that is set if the cmake build is from a dirty tree.

  ``generators``
    A list available generators. Each generator is a JSON object with the
    following keys:

    ``name``
      A string containing the name of the generator.
    ``toolsetSupport``
      ``true`` if the generator supports toolsets and ``false`` otherwise.
    ``platformSupport``
      ``true`` if the generator supports platforms and ``false`` otherwise.
    ``extraGenerators``
      A list of strings with all the extra generators compatible with
      the generator.

426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441
  ``fileApi``
    Optional member that is present when the :manual:`cmake-file-api(7)`
    is available.  The value is a JSON object with one member:

    ``requests``
      A JSON array containing zero or more supported file-api requests.
      Each request is a JSON object with members:

      ``kind``
        Specifies one of the supported :ref:`file-api object kinds`.

      ``version``
        A JSON array whose elements are each a JSON object containing
        ``major`` and ``minor`` members specifying non-negative integer
        version components.

442 443 444
  ``serverMode``
    ``true`` if cmake supports server-mode and ``false`` otherwise.

445 446 447
``chdir <dir> <cmd> [<arg>...]``
  Change the current working directory and run a command.

448
``compare_files [--ignore-eol] <file1> <file2>``
449
  Check if ``<file1>`` is same as ``<file2>``. If files are the same,
450
  then returns ``0``, if not it returns ``1``.  The ``--ignore-eol`` option
451
  implies line-wise comparison and ignores LF/CRLF differences.
452

453
``copy <file>... <destination>``
454 455
  Copy files to ``<destination>`` (either file or directory).
  If multiple files are specified, the ``<destination>`` must be
456
  directory and it must exist. Wildcards are not supported.
457 458
  ``copy`` does follow symlinks. That means it does not copy symlinks,
  but the files or directories it point to.
459

460 461 462
``copy_directory <dir>... <destination>``
  Copy directories to ``<destination>`` directory.
  If ``<destination>`` directory does not exist it will be created.
463
  ``copy_directory`` does follow symlinks.
464

465
``copy_if_different <file>... <destination>``
466 467 468 469
  Copy files to ``<destination>`` (either file or directory) if
  they have changed.
  If multiple files are specified, the ``<destination>`` must be
  directory and it must exist.
470
  ``copy_if_different`` does follow symlinks.
471 472 473 474 475 476 477 478 479 480 481

``echo [<string>...]``
  Displays arguments as text.

``echo_append [<string>...]``
  Displays arguments as text but no new line.

``env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...``
  Run command in a modified environment.

``environment``
482
  Display the current environment variables.
483

484 485
``make_directory <dir>...``
  Create ``<dir>`` directories.  If necessary, create parent
486 487
  directories too.  If a directory already exists it will be
  silently ignored.
488

489
``md5sum <file>...``
490 491 492 493
  Create MD5 checksum of files in ``md5sum`` compatible format::

     351abe79cd3800b38cdfb25d45015a15  file1.txt
     052f86c15bbde68af55c7f7b340ab639  file2.txt
494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523

``sha1sum <file>...``
  Create SHA1 checksum of files in ``sha1sum`` compatible format::

     4bb7932a29e6f73c97bb9272f2bdc393122f86e0  file1.txt
     1df4c8f318665f9a5f2ed38f55adadb7ef9f559c  file2.txt

``sha224sum <file>...``
  Create SHA224 checksum of files in ``sha224sum`` compatible format::

     b9b9346bc8437bbda630b0b7ddfc5ea9ca157546dbbf4c613192f930  file1.txt
     6dfbe55f4d2edc5fe5c9197bca51ceaaf824e48eba0cc453088aee24  file2.txt

``sha256sum <file>...``
  Create SHA256 checksum of files in ``sha256sum`` compatible format::

     76713b23615d31680afeb0e9efe94d47d3d4229191198bb46d7485f9cb191acc  file1.txt
     15b682ead6c12dedb1baf91231e1e89cfc7974b3787c1e2e01b986bffadae0ea  file2.txt

``sha384sum <file>...``
  Create SHA384 checksum of files in ``sha384sum`` compatible format::

     acc049fedc091a22f5f2ce39a43b9057fd93c910e9afd76a6411a28a8f2b8a12c73d7129e292f94fc0329c309df49434  file1.txt
     668ddeb108710d271ee21c0f3acbd6a7517e2b78f9181c6a2ff3b8943af92b0195dcb7cce48aa3e17893173c0a39e23d  file2.txt

``sha512sum <file>...``
  Create SHA512 checksum of files in ``sha512sum`` compatible format::

     2a78d7a6c5328cfb1467c63beac8ff21794213901eaadafd48e7800289afbc08e5fb3e86aa31116c945ee3d7bf2a6194489ec6101051083d1108defc8e1dba89  file1.txt
     7a0b54896fe5e70cca6dd643ad6f672614b189bf26f8153061c4d219474b05dad08c4e729af9f4b009f1a1a280cb625454bf587c690f4617c27e3aebdf3b7a2d  file2.txt
524

525
``remove [-f] <file>...``
526 527 528 529
  Remove the file(s). If any of the listed files already do not
  exist, the command returns a non-zero exit code, but no message
  is logged. The ``-f`` option changes the behavior to return a
  zero exit code (i.e. success) in such situations instead.
530 531
  ``remove`` does not follow symlinks. That means it remove only symlinks
  and not files it point to.
532

533 534
``remove_directory <dir>...``
  Remove ``<dir>`` directories and their contents.  If a directory does
535
  not exist it will be silently ignored.
536 537

``rename <oldname> <newname>``
538 539
  Rename a file or directory (on one volume). If file with the ``<newname>`` name
  already exists, then it will be silently replaced.
540

541 542 543
``server``
  Launch :manual:`cmake-server(7)` mode.

544 545 546
``sleep <number>...``
  Sleep for given number of seconds.

547
``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]``
548 549
  Create or extract a tar or zip archive.  Options are:

550 551
  ``c``
    Create a new archive containing the specified files.
552
    If used, the ``<pathname>...`` argument is mandatory.
553 554
  ``x``
    Extract to disk from the archive.
555 556 557 558
    The ``<pathname>...`` argument could be used to extract only selected files
    or directories.
    When extracting selected files or directories, you must provide their exact
    names including the path, as printed by list (``-t``).
559
  ``t``
560 561 562
    List archive contents.
    The ``<pathname>...`` argument could be used to list only selected files
    or directories.
563 564 565 566 567 568 569 570
  ``v``
    Produce verbose output.
  ``z``
    Compress the resulting archive with gzip.
  ``j``
    Compress the resulting archive with bzip2.
  ``J``
    Compress the resulting archive with XZ.
571 572
  ``--zstd``
    Compress the resulting archive with Zstandard.
573 574 575 576 577
  ``--files-from=<file>``
    Read file names from the given file, one per line.
    Blank lines are ignored.  Lines may not start in ``-``
    except for ``--add-file=<name>`` to add files whose
    names start in ``-``.
578 579 580 581
  ``--format=<format>``
    Specify the format of the archive to be created.
    Supported formats are: ``7zip``, ``gnutar``, ``pax``,
    ``paxr`` (restricted pax, default), and ``zip``.
582 583 584 585 586 587
  ``--mtime=<date>``
    Specify modification time recorded in tarball entries.
  ``--``
    Stop interpreting options and treat all remaining arguments
    as file names, even if they start with ``-``.

588 589

``time <command> [<args>...]``
590
  Run command and display elapsed time.
591

592 593 594
``touch <file>...``
  Creates ``<file>`` if file do not exist.
  If ``<file>`` exists, it is changing ``<file>`` access and modification times.
595

596
``touch_nocreate <file>...``
597 598
  Touch a file if it exists but do not create it.  If a file does
  not exist it will be silently ignored.
599 600 601 602

``create_symlink <old> <new>``
  Create a symbolic link ``<new>`` naming ``<old>``.

603 604 605
.. note::
  Path to where ``<new>`` symbolic link will be created has to exist beforehand.

606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624
Windows-specific Command-Line Tools
-----------------------------------

The following ``cmake -E`` commands are available only on Windows:

``delete_regv <key>``
  Delete Windows registry value.

``env_vs8_wince <sdkname>``
  Displays a batch file which sets the environment for the provided
  Windows CE SDK installed in VS2005.

``env_vs9_wince <sdkname>``
  Displays a batch file which sets the environment for the provided
  Windows CE SDK installed in VS2008.

``write_regv <key> <value>``
  Write Windows registry value.

625

626 627 628 629
Run the Find-Package Tool
=========================

CMake provides a pkg-config like helper for Makefile-based projects:
630

631
.. code-block:: shell
632

633
  cmake --find-package [<options>]
634

635 636 637 638
It searches a package using :command:`find_package()` and prints the
resulting flags to stdout.  This can be used instead of pkg-config
to find installed libraries in plain Makefile-based projects or in
autoconf-based projects (via ``share/aclocal/cmake.m4``).
639 640 641 642 643

.. note::
  This mode is not well-supported due to some technical limitations.
  It is kept for compatibility but should not be used in new projects.

644 645 646 647 648 649 650 651 652 653 654 655 656 657 658

View Help
=========

To print selected pages from the CMake documentation, use

.. code-block:: shell

  cmake --help[-<topic>]

with one of the following options:

.. include:: OPTIONS_HELP.txt


659 660
See Also
========
661

662
.. include:: LINKS.txt