You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
866 lines
28 KiB
866 lines
28 KiB
.. cmake-manual-description: CMake Command-Line Reference
|
|
|
|
cmake(1)
|
|
********
|
|
|
|
Synopsis
|
|
========
|
|
|
|
.. parsed-literal::
|
|
|
|
`Generate a Project Buildsystem`_
|
|
cmake [<options>] <path-to-source>
|
|
cmake [<options>] <path-to-existing-build>
|
|
cmake [<options>] -S <path-to-source> -B <path-to-build>
|
|
|
|
`Build a Project`_
|
|
cmake --build <dir> [<options>] [-- <build-tool-options>]
|
|
|
|
`Install a Project`_
|
|
cmake --install <dir> [<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>]
|
|
|
|
Description
|
|
===========
|
|
|
|
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`_, `Install 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.
|
|
|
|
.. _`Generate a Project Buildsystem`:
|
|
|
|
Generate a Project Buildsystem
|
|
==============================
|
|
|
|
Run CMake with one of the following command signatures to specify the
|
|
source and build trees and generate a buildsystem:
|
|
|
|
``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
|
|
|
|
$ cd build
|
|
$ cmake .
|
|
|
|
``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
|
|
|
|
In all cases the ``<options>`` may be zero or more of the `Options`_ below.
|
|
|
|
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.
|
|
|
|
.. _`CMake Options`:
|
|
|
|
Options
|
|
-------
|
|
|
|
.. include:: OPTIONS_BUILD.txt
|
|
|
|
``-L[A][H]``
|
|
List non-advanced cached variables.
|
|
|
|
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
|
|
display help for each variable.
|
|
|
|
``-N``
|
|
View mode only.
|
|
|
|
Only load the cache. Do not actually run configure and generate
|
|
steps.
|
|
|
|
``--graphviz=[file]``
|
|
Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more.
|
|
|
|
Generate a graphviz input file that will contain all the library and
|
|
executable dependencies in the project. See the documentation for
|
|
:module:`CMakeGraphVizOptions` for more details.
|
|
|
|
``--system-information [file]``
|
|
Dump information about this system.
|
|
|
|
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.
|
|
|
|
``--log-level=<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``.
|
|
|
|
To make a log level persist between CMake runs, set
|
|
:variable:`CMAKE_MESSAGE_LOG_LEVEL` as a cache variable instead.
|
|
If both the command line option and the variable are given, the command line
|
|
option takes precedence.
|
|
|
|
For backward compatibility reasons, ``--loglevel`` is also accepted as a
|
|
synonym for this option.
|
|
|
|
``--log-context``
|
|
Enable the :command:`message` command outputting context attached to each
|
|
message.
|
|
|
|
This option turns on showing context for the current CMake run only.
|
|
To make showing the context persistent for all subsequent CMake runs, set
|
|
:variable:`CMAKE_MESSAGE_CONTEXT_SHOW` as a cache variable instead.
|
|
When this command line option is given, :variable:`CMAKE_MESSAGE_CONTEXT_SHOW`
|
|
is ignored.
|
|
|
|
``--debug-trycompile``
|
|
Do not delete the :command:`try_compile` build tree.
|
|
Only useful on one :command:`try_compile` at a time.
|
|
|
|
Do not delete the files and directories created for :command:`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.
|
|
|
|
``--debug-output``
|
|
Put cmake in a debug mode.
|
|
|
|
Print extra information during the cmake run like stack traces with
|
|
:command:`message(SEND_ERROR)` calls.
|
|
|
|
``--debug-find``
|
|
Put cmake find commands in a debug mode.
|
|
|
|
Print extra find call information during the cmake run to standard
|
|
error. Output is designed for human consumption and not for parsing.
|
|
See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging
|
|
a more local part of the project.
|
|
|
|
``--trace``
|
|
Put cmake in trace mode.
|
|
|
|
Print a trace of all calls made and from where.
|
|
|
|
``--trace-expand``
|
|
Put cmake in trace mode.
|
|
|
|
Like ``--trace``, but with variables expanded.
|
|
|
|
``--trace-format=<format>``
|
|
Put cmake in trace mode and sets the trace output format.
|
|
|
|
``<format>`` can be one of the following values.
|
|
|
|
``human``
|
|
Prints each trace line in a human-readable format. This is the
|
|
default format.
|
|
|
|
``json-v1``
|
|
Prints each line as a separate JSON document. Each document is
|
|
separated by a newline ( ``\n`` ). It is guaranteed that no
|
|
newline characters will be present inside a JSON document.
|
|
|
|
JSON trace format:
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"file": "/full/path/to/the/CMake/file.txt",
|
|
"line": 0,
|
|
"cmd": "add_executable",
|
|
"args": ["foo", "bar"],
|
|
"time": 1579512535.9687231,
|
|
"frame": 2
|
|
}
|
|
|
|
The members are:
|
|
|
|
``file``
|
|
The full path to the CMake source file where the function
|
|
was called.
|
|
|
|
``line``
|
|
The line in ``file`` of the function call.
|
|
|
|
``defer``
|
|
Optional member that is present when the function call was deferred
|
|
by :command:`cmake_language(DEFER)`. If present, its value is a
|
|
string containing the deferred call ``<id>``.
|
|
|
|
``cmd``
|
|
The name of the function that was called.
|
|
|
|
``args``
|
|
A string list of all function parameters.
|
|
|
|
``time``
|
|
Timestamp (seconds since epoch) of the function call.
|
|
|
|
``frame``
|
|
Stack frame depth of the function that was called.
|
|
|
|
Additionally, the first JSON document outputted contains the
|
|
``version`` key for the current major and minor version of the
|
|
|
|
JSON trace format:
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"version": {
|
|
"major": 1,
|
|
"minor": 1
|
|
}
|
|
}
|
|
|
|
The members are:
|
|
|
|
``version``
|
|
Indicates the version of the JSON format. The version has a
|
|
major and minor components following semantic version conventions.
|
|
|
|
``--trace-source=<file>``
|
|
Put cmake in trace mode, but output only lines of a specified file.
|
|
|
|
Multiple options are allowed.
|
|
|
|
``--trace-redirect=<file>``
|
|
Put cmake in trace mode and redirect trace output to a file instead of stderr.
|
|
|
|
``--warn-uninitialized``
|
|
Warn about uninitialized values.
|
|
|
|
Print a warning when an uninitialized variable is used.
|
|
|
|
``--warn-unused-vars``
|
|
Does nothing. In CMake versions 3.2 and below this enabled warnings about
|
|
unused variables. In CMake versions 3.3 through 3.18 the option was broken.
|
|
In CMake 3.19 and above the option has been removed.
|
|
|
|
``--no-warn-unused-cli``
|
|
Don't warn about command line options.
|
|
|
|
Don't find variables that are declared on the command line, but not
|
|
used.
|
|
|
|
``--check-system-vars``
|
|
Find problems with variable usage in system files.
|
|
|
|
Normally, unused and uninitialized variables are searched for only
|
|
in :variable:`CMAKE_SOURCE_DIR` and :variable:`CMAKE_BINARY_DIR`.
|
|
This flag tells CMake to warn about other files as well.
|
|
|
|
``--profiling-output=<path>``
|
|
Used in conjunction with ``--profiling-format`` to output to a given path.
|
|
|
|
``--profiling-format=<file>``
|
|
Enable the output of profiling data of CMake script in the given format.
|
|
|
|
This can aid performance analysis of CMake scripts executed. Third party
|
|
applications should be used to process the output into human readable format.
|
|
|
|
Currently supported values are:
|
|
``google-trace`` Outputs in Google Trace Format, which can be parsed by the
|
|
about:tracing tab of Google Chrome or using a plugin for a tool like Trace
|
|
Compass.
|
|
|
|
``--preset <preset>``, ``--preset=<preset>``
|
|
Reads a :manual:`preset <cmake-presets(7)>` from
|
|
``<path-to-source>/CMakePresets.json`` and
|
|
``<path-to-source>/CMakeUserPresets.json``. The preset may specify the
|
|
generator and the build directory, and a list of variables and other
|
|
arguments to pass to CMake. The current working directory must contain
|
|
CMake preset files. The :manual:`CMake GUI <cmake-gui(1)>` can
|
|
also recognize ``CMakePresets.json`` and ``CMakeUserPresets.json`` files. For
|
|
full details on these files, see :manual:`cmake-presets(7)`.
|
|
|
|
The presets are read before all other command line options. The options
|
|
specified by the preset (variables, generator, etc.) can all be overridden by
|
|
manually specifying them on the command line. For example, if the preset sets
|
|
a variable called ``MYVAR`` to ``1``, but the user sets it to ``2`` with a
|
|
``-D`` argument, the value ``2`` is preferred.
|
|
|
|
``--list-presets, --list-presets=<[configure | build | test | all]>``
|
|
Lists the available presets. If no option is specified only configure presets
|
|
will be listed. The current working directory must contain CMake preset files.
|
|
|
|
.. _`Build Tool Mode`:
|
|
|
|
Build a Project
|
|
===============
|
|
|
|
CMake provides a command-line signature to build an already-generated
|
|
project binary tree:
|
|
|
|
.. code-block:: shell
|
|
|
|
cmake --build <dir> [<options>] [-- <build-tool-options>]
|
|
cmake --build --preset <preset> [<options>] [-- <build-tool-options>]
|
|
|
|
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 (unless a preset
|
|
is specified) and must be first.
|
|
|
|
``--preset <preset>``, ``--preset=<preset>``
|
|
Use a build preset to specify build options. The project binary directory
|
|
is inferred from the ``configurePreset`` key. The current working directory
|
|
must contain CMake preset files.
|
|
See :manual:`preset <cmake-presets(7)>` for more details.
|
|
|
|
``--list-presets``
|
|
Lists the available build presets. The current working directory must
|
|
contain CMake preset files.
|
|
|
|
``--parallel [<jobs>], -j [<jobs>]``
|
|
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.
|
|
|
|
Some native build tools always build in parallel. The use of ``<jobs>``
|
|
value of ``1`` can be used to limit to a single job.
|
|
|
|
``--target <tgt>..., -t <tgt>...``
|
|
Build ``<tgt>`` instead of the default target. Multiple targets may be
|
|
given, separated by spaces.
|
|
|
|
``--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.
|
|
|
|
``--verbose, -v``
|
|
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.
|
|
|
|
|
|
``--``
|
|
Pass remaining options to the native tool.
|
|
|
|
Run ``cmake --build`` with no options for quick help.
|
|
|
|
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 generators, choose configuration ``<cfg>``.
|
|
|
|
``--component <comp>``
|
|
Component-based install. Only install component ``<comp>``.
|
|
|
|
``--default-directory-permissions <permissions>``
|
|
Default directory install permissions. Permissions in format ``<u=rwx,g=rx,o=rx>``.
|
|
|
|
``--prefix <prefix>``
|
|
Override the installation prefix, :variable:`CMAKE_INSTALL_PREFIX`.
|
|
|
|
``--strip``
|
|
Strip before installing.
|
|
|
|
``-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.
|
|
|
|
Open a Project
|
|
==============
|
|
|
|
.. 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> [-- <unparsed-options>...]
|
|
|
|
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.
|
|
|
|
Any options after ``--`` are not parsed by CMake, but they are still included
|
|
in the set of :variable:`CMAKE_ARGV<n> <CMAKE_ARGV0>` variables passed to the
|
|
script (including the ``--`` itself).
|
|
|
|
|
|
Run a Command-Line Tool
|
|
=======================
|
|
|
|
CMake provides builtin command-line tools through the signature
|
|
|
|
.. code-block:: shell
|
|
|
|
cmake -E <command> [<options>]
|
|
|
|
Run ``cmake -E`` or ``cmake -E help`` for a summary of commands.
|
|
Available commands are:
|
|
|
|
``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.
|
|
``supportedPlatforms``
|
|
.. versionadded:: 3.21
|
|
|
|
Optional member that may be present when the generator supports
|
|
platform specification via :variable:`CMAKE_GENERATOR_PLATFORM`
|
|
(``-A ...``). The value is a list of platforms known to be supported.
|
|
``extraGenerators``
|
|
A list of strings with all the extra generators compatible with
|
|
the generator.
|
|
|
|
``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.
|
|
|
|
``serverMode``
|
|
``true`` if cmake supports server-mode and ``false`` otherwise.
|
|
Always false since CMake 3.20.
|
|
|
|
``cat <files>...``
|
|
Concatenate files and print on the standard output.
|
|
|
|
``chdir <dir> <cmd> [<arg>...]``
|
|
Change the current working directory and run a command.
|
|
|
|
``compare_files [--ignore-eol] <file1> <file2>``
|
|
Check if ``<file1>`` is same as ``<file2>``. If files are the same,
|
|
then returns ``0``, if not it returns ``1``. In case of invalid
|
|
arguments, it returns 2. The ``--ignore-eol`` option
|
|
implies line-wise comparison and ignores LF/CRLF differences.
|
|
|
|
``copy <file>... <destination>``
|
|
Copy files to ``<destination>`` (either file or directory).
|
|
If multiple files are specified, the ``<destination>`` must be
|
|
directory and it must exist. Wildcards are not supported.
|
|
``copy`` does follow symlinks. That means it does not copy symlinks,
|
|
but the files or directories it point to.
|
|
|
|
``copy_directory <dir>... <destination>``
|
|
Copy content of ``<dir>...`` directories to ``<destination>`` directory.
|
|
If ``<destination>`` directory does not exist it will be created.
|
|
``copy_directory`` does follow symlinks.
|
|
|
|
``copy_if_different <file>... <destination>``
|
|
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.
|
|
``copy_if_different`` does follow symlinks.
|
|
|
|
``create_symlink <old> <new>``
|
|
Create a symbolic link ``<new>`` naming ``<old>``.
|
|
|
|
.. note::
|
|
Path to where ``<new>`` symbolic link will be created has to exist beforehand.
|
|
|
|
``create_hardlink <old> <new>``
|
|
Create a hard link ``<new>`` naming ``<old>``.
|
|
|
|
.. note::
|
|
Path to where ``<new>`` hard link will be created has to exist beforehand.
|
|
``<old>`` has to exist beforehand.
|
|
|
|
``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``
|
|
Display the current environment variables.
|
|
|
|
``false``
|
|
Do nothing, with an exit code of 1.
|
|
|
|
``make_directory <dir>...``
|
|
Create ``<dir>`` directories. If necessary, create parent
|
|
directories too. If a directory already exists it will be
|
|
silently ignored.
|
|
|
|
``md5sum <file>...``
|
|
Create MD5 checksum of files in ``md5sum`` compatible format::
|
|
|
|
351abe79cd3800b38cdfb25d45015a15 file1.txt
|
|
052f86c15bbde68af55c7f7b340ab639 file2.txt
|
|
|
|
``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
|
|
|
|
``remove [-f] <file>...``
|
|
.. deprecated:: 3.17
|
|
|
|
Remove the file(s). The planned behavior was that 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.
|
|
``remove`` does not follow symlinks. That means it remove only symlinks
|
|
and not files it point to.
|
|
|
|
The implementation was buggy and always returned 0. It cannot be fixed without
|
|
breaking backwards compatibility. Use ``rm`` instead.
|
|
|
|
``remove_directory <dir>...``
|
|
.. deprecated:: 3.17
|
|
|
|
Remove ``<dir>`` directories and their contents. If a directory does
|
|
not exist it will be silently ignored. If ``<dir>`` is a symlink to
|
|
a directory, just the symlink will be removed.
|
|
Use ``rm`` instead.
|
|
|
|
``rename <oldname> <newname>``
|
|
Rename a file or directory (on one volume). If file with the ``<newname>`` name
|
|
already exists, then it will be silently replaced.
|
|
|
|
``rm [-rRf] <file> <dir>...``
|
|
Remove the files ``<file>`` or directories ``dir``.
|
|
Use ``-r`` or ``-R`` to remove directories and their contents recursively.
|
|
If any of the listed files/directories 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.
|
|
|
|
``server``
|
|
Launch :manual:`cmake-server(7)` mode.
|
|
|
|
``sleep <number>...``
|
|
Sleep for given number of seconds.
|
|
|
|
``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<pathname>...]``
|
|
Create or extract a tar or zip archive. Options are:
|
|
|
|
``c``
|
|
Create a new archive containing the specified files.
|
|
If used, the ``<pathname>...`` argument is mandatory.
|
|
``x``
|
|
Extract to disk from the archive.
|
|
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``).
|
|
``t``
|
|
List archive contents.
|
|
The ``<pathname>...`` argument could be used to list only selected files
|
|
or directories.
|
|
``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.
|
|
``--zstd``
|
|
Compress the resulting archive with Zstandard.
|
|
``--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 ``-``.
|
|
``--format=<format>``
|
|
Specify the format of the archive to be created.
|
|
Supported formats are: ``7zip``, ``gnutar``, ``pax``,
|
|
``paxr`` (restricted pax, default), and ``zip``.
|
|
``--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 ``-``.
|
|
|
|
|
|
``time <command> [<args>...]``
|
|
Run command and display elapsed time.
|
|
|
|
``touch <file>...``
|
|
Creates ``<file>`` if file do not exist.
|
|
If ``<file>`` exists, it is changing ``<file>`` access and modification times.
|
|
|
|
``touch_nocreate <file>...``
|
|
Touch a file if it exists but do not create it. If a file does
|
|
not exist it will be silently ignored.
|
|
|
|
``true``
|
|
Do nothing, with an exit code of 0.
|
|
|
|
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.
|
|
|
|
|
|
Run the Find-Package Tool
|
|
=========================
|
|
|
|
CMake provides a pkg-config like helper for Makefile-based projects:
|
|
|
|
.. code-block:: shell
|
|
|
|
cmake --find-package [<options>]
|
|
|
|
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``).
|
|
|
|
.. 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.
|
|
|
|
|
|
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
|
|
|
|
To view the presets available for a project, use
|
|
|
|
.. code-block:: shell
|
|
|
|
cmake <source-dir> --list-presets
|
|
|
|
See Also
|
|
========
|
|
|
|
.. include:: LINKS.txt
|