cmake.1.rst 21.4 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`_
Brad King's avatar
Brad King committed
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
===========

Brad King's avatar
Brad King committed
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
Brad King's avatar
Brad King committed
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
==============================

Brad King's avatar
Brad King committed
112 113
Run CMake with one of the following command signatures to specify the
source and build trees and generate a buildsystem:
114

Brad King's avatar
Brad King committed
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

Brad King's avatar
Brad King committed
137 138
    $ cd build
    $ cmake .
139

Brad King's avatar
Brad King committed
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.

Brad King's avatar
Brad King committed
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
``--loglevel=<ERROR|WARNING|NOTICE|STATUS|VERBOSE|DEBUG|TRACE>``
204 205 206
 Set the log level.

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

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 243
``--trace-redirect=<file>``
 Put cmake in trace mode and redirect trace output to a file instead of stderr.

244 245
``--warn-uninitialized``
 Warn about uninitialized values.
246

247
 Print a warning when an uninitialized variable is used.
248

249 250
``--warn-unused-vars``
 Warn about unused variables.
251

252
 Find variables that are declared or set, but not used.
253

254 255
``--no-warn-unused-cli``
 Don't warn about command line options.
256

257 258
 Don't find variables that are declared on the command line, but not
 used.
259

260 261
``--check-system-vars``
 Find problems with variable usage in system files.
262

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

267 268
.. _`Build Tool Mode`:

269
Build a Project
270 271 272
===============

CMake provides a command-line signature to build an already-generated
273 274 275
project binary tree:

.. code-block:: shell
276

277
  cmake --build <dir> [<options>] [-- <build-tool-options>]
278 279 280 281 282 283 284

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.

285
``--parallel [<jobs>], -j [<jobs>]``
286 287 288 289 290 291
  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.

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

295
``--target <tgt>..., -t <tgt>...``
296 297
  Build ``<tgt>`` instead of the default target.  Multiple targets may be
  given, separated by spaces.
298 299 300 301 302 303 304 305 306 307 308

``--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.

309
``--verbose, -v``
310 311 312 313 314 315 316
  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.


317 318 319 320 321
``--``
  Pass remaining options to the native tool.

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

322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339
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>``
340
  For multi-configuration generators, choose configuration ``<cfg>``.
341 342 343 344 345

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

``--prefix <prefix>``
346
  Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`.
347 348

``--strip``
349
  Strip before installing.
350 351 352 353 354 355 356

``-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.
357

358 359
Open a Project
==============
360

361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379
.. 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
380 381
is not modified.  If variables are defined using ``-D``, this must be
done before the ``-P`` argument.
382 383 384 385 386 387 388 389 390 391


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

CMake provides builtin command-line tools through the signature

.. code-block:: shell

  cmake -E <command> [<options>]
392 393 394 395

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

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 426 427 428 429
``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.

430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445
  ``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.

446 447 448
  ``serverMode``
    ``true`` if cmake supports server-mode and ``false`` otherwise.

449 450 451
``chdir <dir> <cmd> [<arg>...]``
  Change the current working directory and run a command.

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

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

464 465 466
``copy_directory <dir>... <destination>``
  Copy directories to ``<destination>`` directory.
  If ``<destination>`` directory does not exist it will be created.
467
  ``copy_directory`` does follow symlinks.
468

469
``copy_if_different <file>... <destination>``
470 471 472 473
  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.
474
  ``copy_if_different`` does follow symlinks.
475 476 477 478 479 480 481 482 483 484 485

``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``
486
  Display the current environment variables.
487

488 489
``make_directory <dir>...``
  Create ``<dir>`` directories.  If necessary, create parent
490 491
  directories too.  If a directory already exists it will be
  silently ignored.
492

493
``md5sum <file>...``
494 495 496 497
  Create MD5 checksum of files in ``md5sum`` compatible format::

     351abe79cd3800b38cdfb25d45015a15  file1.txt
     052f86c15bbde68af55c7f7b340ab639  file2.txt
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 524 525 526 527

``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
528

529
``remove [-f] <file>...``
530 531 532 533
  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.
534 535
  ``remove`` does not follow symlinks. That means it remove only symlinks
  and not files it point to.
536

537 538
``remove_directory <dir>...``
  Remove ``<dir>`` directories and their contents.  If a directory does
539
  not exist it will be silently ignored.
540 541

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

545 546 547
``server``
  Launch :manual:`cmake-server(7)` mode.

548 549 550
``sleep <number>...``
  Sleep for given number of seconds.

551
``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]``
552 553
  Create or extract a tar or zip archive.  Options are:

554 555
  ``c``
    Create a new archive containing the specified files.
556
    If used, the ``<pathname>...`` argument is mandatory.
557 558
  ``x``
    Extract to disk from the archive.
559 560 561 562
    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``).
563
  ``t``
564 565 566
    List archive contents.
    The ``<pathname>...`` argument could be used to list only selected files
    or directories.
567 568 569 570 571 572 573 574
  ``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.
575 576
  ``--zstd``
    Compress the resulting archive with Zstandard.
577 578 579 580 581
  ``--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 ``-``.
582 583 584 585
  ``--format=<format>``
    Specify the format of the archive to be created.
    Supported formats are: ``7zip``, ``gnutar``, ``pax``,
    ``paxr`` (restricted pax, default), and ``zip``.
586 587 588 589 590 591
  ``--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 ``-``.

592 593

``time <command> [<args>...]``
594
  Run command and display elapsed time.
595

596 597 598
``touch <file>...``
  Creates ``<file>`` if file do not exist.
  If ``<file>`` exists, it is changing ``<file>`` access and modification times.
599

600
``touch_nocreate <file>...``
601 602
  Touch a file if it exists but do not create it.  If a file does
  not exist it will be silently ignored.
603 604 605 606

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

607 608 609
.. note::
  Path to where ``<new>`` symbolic link will be created has to exist beforehand.

610 611 612 613 614 615
``true``
  Do nothing, with an exit code of 0.

``false``
  Do nothing, with an exit code of 1.

616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634
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.

635

636 637 638 639
Run the Find-Package Tool
=========================

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

641
.. code-block:: shell
642

643
  cmake --find-package [<options>]
644

645 646 647 648
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``).
649 650 651 652 653

.. 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.

654 655 656 657 658 659 660 661 662 663 664 665 666 667 668

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


669 670
See Also
========
671

672
.. include:: LINKS.txt