cmake.1.rst 19.9 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>]

Jiang Yi's avatar
Jiang Yi committed
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`_.
Jiang Yi's avatar
Jiang Yi committed
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
``--debug-trycompile``
204 205
 Do not delete the :command:`try_compile` build tree.
 Only useful on one :command:`try_compile` at a time.
206

207
 Do not delete the files and directories created for :command:`try_compile`
208 209 210 211 212
 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.
213

214 215
``--debug-output``
 Put cmake in a debug mode.
216

Ben Boeckel's avatar
Ben Boeckel committed
217
 Print extra information during the cmake run like stack traces with
218
 :command:`message(SEND_ERROR)` calls.
219

220 221
``--trace``
 Put cmake in trace mode.
222

Ben Boeckel's avatar
Ben Boeckel committed
223 224 225 226 227 228
 Print a trace of all calls made and from where.

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

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

230 231 232 233 234
``--trace-source=<file>``
 Put cmake in trace mode, but output only lines of a specified file.

 Multiple options are allowed.

235 236
``--warn-uninitialized``
 Warn about uninitialized values.
237

238
 Print a warning when an uninitialized variable is used.
239

240 241
``--warn-unused-vars``
 Warn about unused variables.
242

243
 Find variables that are declared or set, but not used.
244

245 246
``--no-warn-unused-cli``
 Don't warn about command line options.
247

248 249
 Don't find variables that are declared on the command line, but not
 used.
250

251 252
``--check-system-vars``
 Find problems with variable usage in system files.
253

254
 Normally, unused and uninitialized variables are searched for only
255 256
 in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`.
 This flag tells CMake to warn about other files as well.
257

258 259
.. _`Build Tool Mode`:

260
Build a Project
261 262 263
===============

CMake provides a command-line signature to build an already-generated
264 265 266
project binary tree:

.. code-block:: shell
267

268
  cmake --build <dir> [<options>] [-- <build-tool-options>]
269 270 271 272 273 274 275

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.

276
``--parallel [<jobs>], -j [<jobs>]``
277 278 279 280 281 282
  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.

283
``--target <tgt>..., -t <tgt>...``
284
  Build ``<tgt>`` instead of default targets.  May be specified multiple times.
285 286 287 288 289 290 291 292 293 294 295

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

296
``--verbose, -v``
297 298 299 300 301 302 303
  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.


304 305 306 307 308
``--``
  Pass remaining options to the native tool.

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

Jiang Yi's avatar
Jiang Yi committed
309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332
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>``
333
  The installation prefix :variable:`CMAKE_INSTALL_PREFIX`.
Jiang Yi's avatar
Jiang Yi committed
334 335

``--strip``
336
  Strip before installing by setting ``CMAKE_INSTALL_DO_STRIP``.
Jiang Yi's avatar
Jiang Yi committed
337 338 339 340 341 342 343

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

345 346
Open a Project
==============
347

348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366
.. 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
367 368
is not modified.  If variables are defined using ``-D``, this must be
done before the ``-P`` argument.
369 370 371 372 373 374 375 376 377 378


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

CMake provides builtin command-line tools through the signature

.. code-block:: shell

  cmake -E <command> [<options>]
379 380 381 382

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

383 384 385 386 387 388 389 390 391 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
``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.

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

420 421 422
``chdir <dir> <cmd> [<arg>...]``
  Change the current working directory and run a command.

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

428
``copy <file>... <destination>``
429 430
  Copy files to ``<destination>`` (either file or directory).
  If multiple files are specified, the ``<destination>`` must be
431
  directory and it must exist. Wildcards are not supported.
432 433
  ``copy`` does follow symlinks. That means it does not copy symlinks,
  but the files or directories it point to.
434

435 436 437
``copy_directory <dir>... <destination>``
  Copy directories to ``<destination>`` directory.
  If ``<destination>`` directory does not exist it will be created.
438
  ``copy_directory`` does follow symlinks.
439

440
``copy_if_different <file>... <destination>``
441 442 443 444
  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.
445
  ``copy_if_different`` does follow symlinks.
446 447 448 449 450 451 452 453 454 455 456

``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``
457
  Display the current environment variables.
458

459 460
``make_directory <dir>...``
  Create ``<dir>`` directories.  If necessary, create parent
461 462
  directories too.  If a directory already exists it will be
  silently ignored.
463

464
``md5sum <file>...``
465 466 467 468
  Create MD5 checksum of files in ``md5sum`` compatible format::

     351abe79cd3800b38cdfb25d45015a15  file1.txt
     052f86c15bbde68af55c7f7b340ab639  file2.txt
469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498

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

500
``remove [-f] <file>...``
501 502 503 504
  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.
505 506
  ``remove`` does not follow symlinks. That means it remove only symlinks
  and not files it point to.
507 508

``remove_directory <dir>``
509 510
  Remove a directory and its contents.  If a directory does
  not exist it will be silently ignored.
511 512

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

516 517 518
``server``
  Launch :manual:`cmake-server(7)` mode.

519 520 521
``sleep <number>...``
  Sleep for given number of seconds.

522
``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<file>...]``
523 524
  Create or extract a tar or zip archive.  Options are:

525 526 527 528 529 530 531 532 533 534 535 536 537 538 539
  ``c``
    Create a new archive containing the specified files.
    If used, the <file> argument is mandatory.
  ``x``
    Extract to disk from the archive.
  ``t``
    List archive contents to stdout.
  ``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.
540 541 542 543 544 545 546 547 548 549
  ``--``
    Stop interpreting options and treat all remaining arguments
    as file names even if they start in ``-``.
  ``--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 ``-``.
  ``--mtime=<date>``
    Specify modification time recorded in tarball entries.
550 551 552 553
  ``--format=<format>``
    Specify the format of the archive to be created.
    Supported formats are: ``7zip``, ``gnutar``, ``pax``,
    ``paxr`` (restricted pax, default), and ``zip``.
554 555

``time <command> [<args>...]``
556
  Run command and display elapsed time.
557

558 559 560
``touch <file>...``
  Creates ``<file>`` if file do not exist.
  If ``<file>`` exists, it is changing ``<file>`` access and modification times.
561

562
``touch_nocreate <file>...``
563 564
  Touch a file if it exists but do not create it.  If a file does
  not exist it will be silently ignored.
565 566 567 568

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

569 570 571
.. note::
  Path to where ``<new>`` symbolic link will be created has to exist beforehand.

572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590
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.

591

592 593 594 595
Run the Find-Package Tool
=========================

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

597
.. code-block:: shell
598

599
  cmake --find-package [<options>]
600

601 602 603 604
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``).
605 606 607 608 609

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

610 611 612 613 614 615 616 617 618 619 620 621 622 623 624

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


625 626
See Also
========
627

628
.. include:: LINKS.txt