cmake.1.rst 18.7 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 19 20 21 22 23 24 25 26 27 28 29 30 31 32
  cmake [<options>] -S <path-to-source> -B <path-to-build>

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

 `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>]
33

34 35 36
Description
===========

Brad King's avatar
Brad King committed
37 38 39 40 41 42 43 44 45 46 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
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`_.
Optionally use **cmake** to `Build a Project`_ or just run the
corresponding build tool (e.g. ``make``) directly.  **cmake** can also
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.
104

105 106 107 108

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

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

Brad King's avatar
Brad King committed
112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
``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
133

Brad King's avatar
Brad King committed
134 135
    $ cd build
    $ cmake .
136

Brad King's avatar
Brad King committed
137 138 139 140 141 142 143 144 145 146
``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
147 148 149

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

Brad King's avatar
Brad King committed
150 151 152 153 154 155 156 157 158 159 160 161
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.

162 163
.. _`CMake Options`:

164
Options
165
-------
166

167
.. include:: OPTIONS_BUILD.txt
168

169 170
``-L[A][H]``
 List non-advanced cached variables.
171

172 173 174 175 176 177 178
 List cache variables will run CMake and list all the variables from
 the CMake cache that are not marked as INTERNAL or 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
 display help for each variable.
179

180 181
``-N``
 View mode only.
182

183 184
 Only load the cache.  Do not actually run configure and generate
 steps.
185

186
``--graphviz=[file]``
187
 Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more.
188

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

193 194
``--system-information [file]``
 Dump information about this system.
195

196 197 198
 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.
199

200 201
``--debug-trycompile``
 Do not delete the try_compile build tree. Only useful on one try_compile at a time.
202

203 204 205 206 207 208
 Do not delete the files and directories created for try_compile
 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.
209

210 211
``--debug-output``
 Put cmake in a debug mode.
212

Ben Boeckel's avatar
Ben Boeckel committed
213
 Print extra information during the cmake run like stack traces with
214
 message(send_error ) calls.
215

216 217
``--trace``
 Put cmake in trace mode.
218

Ben Boeckel's avatar
Ben Boeckel committed
219 220 221 222 223 224
 Print a trace of all calls made and from where.

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

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

226 227 228 229 230
``--trace-source=<file>``
 Put cmake in trace mode, but output only lines of a specified file.

 Multiple options are allowed.

231 232
``--warn-uninitialized``
 Warn about uninitialized values.
233

234
 Print a warning when an uninitialized variable is used.
235

236 237
``--warn-unused-vars``
 Warn about unused variables.
238

239
 Find variables that are declared or set, but not used.
240

241 242
``--no-warn-unused-cli``
 Don't warn about command line options.
243

244 245
 Don't find variables that are declared on the command line, but not
 used.
246

247 248
``--check-system-vars``
 Find problems with variable usage in system files.
249

250 251 252
 Normally, unused and uninitialized variables are searched for only
 in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR.  This flag tells CMake to
 warn about other files as well.
253

254 255
.. _`Build Tool Mode`:

256
Build a Project
257 258 259
===============

CMake provides a command-line signature to build an already-generated
260 261 262
project binary tree:

.. code-block:: shell
263

264
  cmake --build <dir> [<options>] [-- <build-tool-options>]
265 266 267 268 269 270 271

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.

272
``--parallel [<jobs>], -j [<jobs>]``
273 274 275 276 277 278
  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.

279
``--target <tgt>..., -t <tgt>...``
280
  Build ``<tgt>`` instead of default targets.  May be specified multiple times.
281 282 283 284 285 286 287 288 289 290 291

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

292
``--verbose, -v``
293 294 295 296 297 298 299
  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.


300 301 302 303 304
``--``
  Pass remaining options to the native tool.

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

305

306 307
Open a Project
==============
308

309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339
.. 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
is not modified.  If variables are defined using -D, this must be
done before the -P argument.


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

CMake provides builtin command-line tools through the signature

.. code-block:: shell

  cmake -E <command> [<options>]
340 341 342 343

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

344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380
``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.

381 382 383
``chdir <dir> <cmd> [<arg>...]``
  Change the current working directory and run a command.

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

389
``copy <file>... <destination>``
390 391
  Copy files to ``<destination>`` (either file or directory).
  If multiple files are specified, the ``<destination>`` must be
392
  directory and it must exist. Wildcards are not supported.
393 394
  ``copy`` does follow symlinks. That means it does not copy symlinks,
  but the files or directories it point to.
395

396 397 398
``copy_directory <dir>... <destination>``
  Copy directories to ``<destination>`` directory.
  If ``<destination>`` directory does not exist it will be created.
399
  ``copy_directory`` does follow symlinks.
400

401
``copy_if_different <file>... <destination>``
402 403 404 405
  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.
406
  ``copy_if_different`` does follow symlinks.
407 408 409 410 411 412 413 414 415 416 417

``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``
418
  Display the current environment variables.
419

420 421
``make_directory <dir>...``
  Create ``<dir>`` directories.  If necessary, create parent
422 423
  directories too.  If a directory already exists it will be
  silently ignored.
424

425
``md5sum <file>...``
426 427 428 429
  Create MD5 checksum of files in ``md5sum`` compatible format::

     351abe79cd3800b38cdfb25d45015a15  file1.txt
     052f86c15bbde68af55c7f7b340ab639  file2.txt
430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459

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

461
``remove [-f] <file>...``
462 463 464 465
  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.
466 467
  ``remove`` does not follow symlinks. That means it remove only symlinks
  and not files it point to.
468 469

``remove_directory <dir>``
470 471
  Remove a directory and its contents.  If a directory does
  not exist it will be silently ignored.
472 473

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

477 478 479
``server``
  Launch :manual:`cmake-server(7)` mode.

480 481 482
``sleep <number>...``
  Sleep for given number of seconds.

483
``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<file>...]``
484 485
  Create or extract a tar or zip archive.  Options are:

486 487 488 489 490 491 492 493 494 495 496 497 498 499 500
  ``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.
501 502 503 504 505 506 507 508 509 510
  ``--``
    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.
511 512 513 514
  ``--format=<format>``
    Specify the format of the archive to be created.
    Supported formats are: ``7zip``, ``gnutar``, ``pax``,
    ``paxr`` (restricted pax, default), and ``zip``.
515 516

``time <command> [<args>...]``
517
  Run command and display elapsed time.
518

519 520 521
``touch <file>...``
  Creates ``<file>`` if file do not exist.
  If ``<file>`` exists, it is changing ``<file>`` access and modification times.
522

523
``touch_nocreate <file>...``
524 525
  Touch a file if it exists but do not create it.  If a file does
  not exist it will be silently ignored.
526 527 528 529

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

530 531 532
.. note::
  Path to where ``<new>`` symbolic link will be created has to exist beforehand.

533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551
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.

552

553 554 555 556
Run the Find-Package Tool
=========================

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

558
.. code-block:: shell
559

560
  cmake --find-package [<options>]
561

562 563 564 565
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``).
566 567 568 569 570

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

571 572 573 574 575 576 577 578 579 580 581 582 583 584 585

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


586 587
See Also
========
588

589
.. include:: LINKS.txt