Commit faf4496d authored by Craig Scott's avatar Craig Scott Committed by Kitware Robot

Merge topic 'doc-cmake.1'

e15cac8e Help: Extend the cmake(1) manual
8b3a537c Help: Improve cmake(1) manual organization
f9c3f7b1 Help: Emphasize tool names in their manuals
Acked-by: Kitware Robot's avatarKitware Robot <kwrobot@kitware.com>
Merge-request: !2662
parents 049ca05d e15cac8e
Pipeline #124803 passed with stage
in 0 seconds
......@@ -13,7 +13,7 @@ Synopsis
Description
===========
The "ccmake" executable is the CMake curses interface. Project
The **ccmake** executable is the CMake curses interface. Project
configuration settings may be specified interactively through this
GUI. Brief instructions are provided at the bottom of the terminal
when the program is running.
......
......@@ -27,6 +27,8 @@ when creating a new build tree.
CMake Generators
================
.. _`Command-Line Build Tool Generators`:
Command-Line Build Tool Generators
----------------------------------
......@@ -58,6 +60,8 @@ Ninja Generator
/generator/Ninja
.. _`IDE Build Tool Generators`:
IDE Build Tool Generators
-------------------------
......
......@@ -14,7 +14,7 @@ Synopsis
Description
===========
The "cmake-gui" executable is the CMake GUI. Project configuration
The **cmake-gui** executable is the CMake GUI. Project configuration
settings may be specified interactively. Brief instructions are
provided at the bottom of the window when the program is running.
......
......@@ -8,37 +8,164 @@ Synopsis
.. parsed-literal::
cmake [<options>] {<path-to-source> | <path-to-existing-build>}
cmake [<options>] -S <path-to-source> -B <path-to-build>
cmake [{-D <var>=<value>}...] -P <cmake-script-file>
cmake --build <dir> [<options>...] [-- <build-tool-options>...]
cmake --open <dir>
cmake -E <command> [<options>...]
cmake --find-package <options>...
`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>]
`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 CMake command-line interface. It may be
used to configure projects in scripts. Project configuration settings
may be specified on the command line with the -D option.
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.
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
CMake is a cross-platform build system generator. Projects specify
their build process with platform-independent CMake listfiles included
in each directory of a source tree with the name CMakeLists.txt.
Users build a project by using CMake to generate a build system for a
native tool on their platform.
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
``-E <command> [<options>...]``
See `Command-Line Tool Mode`_.
``-L[A][H]``
List non-advanced cached variables.
......@@ -50,30 +177,12 @@ Options
display also advanced variables. If H is specified, it will also
display help for each variable.
``--build <dir>``
See `Build Tool Mode`_.
``--open <dir>``
Open the generated project in the associated application. This is
only supported by some generators.
``-N``
View mode only.
Only load the cache. Do not actually run configure and generate
steps.
``-P <file>``
Process script mode.
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.
``--find-package``
See `Find-Package Tool Mode`_.
``--graphviz=[file]``
Generate graphviz of dependencies, see :module:`CMakeGraphVizOptions` for more.
......@@ -142,17 +251,17 @@ Options
in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells CMake to
warn about other files as well.
.. include:: OPTIONS_HELP.txt
.. _`Build Tool Mode`:
Build Tool Mode
Build a Project
===============
CMake provides a command-line signature to build an already-generated
project binary tree::
project binary tree:
cmake --build <dir> [<options>...] [-- <build-tool-options>...]
.. code-block:: shell
cmake --build <dir> [<options>] [-- <build-tool-options>]
This abstracts a native build tool's command-line interface with the
following options:
......@@ -185,12 +294,41 @@ following options:
Run ``cmake --build`` with no options for quick help.
Command-Line Tool Mode
======================
CMake provides builtin command-line tools through the signature::
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 -E <command> [<options>...]
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>]
Run ``cmake -E`` or ``cmake -E help`` for a summary of commands.
Available commands are:
......@@ -326,7 +464,7 @@ Available commands are:
``sleep <number>...``
Sleep for given number of seconds.
``tar [cxt][vf][zjJ] file.tar [<options>...] [--] [<file>...]``
``tar [cxt][vf][zjJ] file.tar [<options>] [--] [<file>...]``
Create or extract a tar or zip archive. Options are:
``--``
......@@ -379,24 +517,40 @@ The following ``cmake -E`` commands are available only on Windows:
``write_regv <key> <value>``
Write Windows registry value.
Find-Package Tool Mode
======================
CMake provides a helper for Makefile-based projects with the signature::
Run the Find-Package Tool
=========================
cmake --find-package <options>...
CMake provides a pkg-config like helper for Makefile-based projects:
This runs in a pkg-config like mode.
.. code-block:: shell
Search a package using :command:`find_package()` and print the resulting flags
to stdout. This can be used to use cmake instead of pkg-config to find
installed libraries in plain Makefile-based projects or in autoconf-based
projects (via ``share/aclocal/cmake.m4``).
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
See Also
========
......
......@@ -13,10 +13,10 @@ Synopsis
Description
===========
The ``cpack`` executable is the CMake packaging program. It generates
The **cpack** executable is the CMake packaging program. It generates
installers and source packages in a variety of formats.
For each installer or package format, ``cpack`` has a specific backend,
For each installer or package format, **cpack** has a specific backend,
called "generator". A generator is responsible for generating the required
inputs and invoking the specific package creation tools. These installer
or package generators are not to be confused with the makefile generators
......@@ -28,7 +28,7 @@ list of generators supported for the target platform. Which of them are
to be used can be selected through the :variable:`CPACK_GENERATOR` variable
or through the command-line option ``-G``.
The ``cpack`` program is steered by a configuration file written in the
The **cpack** program is steered by a configuration file written in the
:manual:`CMake language <cmake-language(7)>`. Unless chosen differently
through the command-line option ``--config``, the file ``CPackConfig.cmake``
in the current directory is used.
......
......@@ -19,7 +19,7 @@ Synopsis
Description
===========
The "ctest" executable is the CMake test driver program.
The **ctest** executable is the CMake test driver program.
CMake-generated build trees created for projects that use the
ENABLE_TESTING and ADD_TEST commands have testing support. This
program will run the tests and report results.
......@@ -38,7 +38,7 @@ Options
``--progress``
Enable short progress output from tests.
When the output of ``ctest`` is being sent directly to a terminal, the
When the output of **ctest** is being sent directly to a terminal, the
progress through the set of tests is reported by updating the same line
rather than printing start and end messages for each test on new lines.
This can significantly reduce the verbosity of the test output.
......
......@@ -3,6 +3,6 @@ CMAKE_ARGC
Number of command line arguments passed to CMake in script mode.
When run in :ref:`-P <CMake Options>` script mode, CMake sets this variable to
the number of command line arguments. See also :variable:`CMAKE_ARGV0`,
``1``, ``2`` ...
When run in :ref:`-P <Script Processing Mode>` script mode, CMake sets this
variable to the number of command line arguments. See also
:variable:`CMAKE_ARGV0`, ``1``, ``2`` ...
......@@ -3,7 +3,7 @@ CMAKE_ARGV0
Command line argument passed to CMake in script mode.
When run in :ref:`-P <CMake Options>` script mode, CMake sets this variable to
the first command line argument. It then also sets ``CMAKE_ARGV1``,
When run in :ref:`-P <Script Processing Mode>` script mode, CMake sets this
variable to the first command line argument. It then also sets ``CMAKE_ARGV1``,
``CMAKE_ARGV2``, ... and so on, up to the number of command line arguments
given. See also :variable:`CMAKE_ARGC`.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment