[Cmake-commits] CMake branch, master, updated. v3.13.0-551-gfaf4496
Kitware Robot
kwrobot at kitware.com
Wed Nov 28 04:33:05 EST 2018
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "CMake".
The branch, master has been updated
via faf4496db372847f34046acfd0d57dda7812eafa (commit)
via e15cac8ee748022d31e734f3ab9529bf6c36ac25 (commit)
via 8b3a537c29974da62f4a46f4631bbec1550a2a23 (commit)
via f9c3f7b16479f84cde3b0249f83e53a32960dff3 (commit)
from 049ca05da93ef7f6fced82a88069a382c6008ebf (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=faf4496db372847f34046acfd0d57dda7812eafa
commit faf4496db372847f34046acfd0d57dda7812eafa
Merge: 049ca05 e15cac8
Author: Craig Scott <craig.scott at crascit.com>
AuthorDate: Wed Nov 28 09:26:22 2018 +0000
Commit: Kitware Robot <kwrobot at kitware.com>
CommitDate: Wed Nov 28 04:26:33 2018 -0500
Merge topic 'doc-cmake.1'
e15cac8ee7 Help: Extend the cmake(1) manual
8b3a537c29 Help: Improve cmake(1) manual organization
f9c3f7b164 Help: Emphasize tool names in their manuals
Acked-by: Kitware Robot <kwrobot at kitware.com>
Merge-request: !2662
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=e15cac8ee748022d31e734f3ab9529bf6c36ac25
commit e15cac8ee748022d31e734f3ab9529bf6c36ac25
Author: Brad King <brad.king at kitware.com>
AuthorDate: Mon Nov 26 10:26:19 2018 -0500
Commit: Craig Scott <craig.scott at crascit.com>
CommitDate: Tue Nov 27 21:13:32 2018 +1100
Help: Extend the cmake(1) manual
Extend the description section to cover all capabilities that
the "cmake" tool has. Extend the buildsystem generation section
to introduce important concepts and describe the basic workflow.
Inspired-by: Joachim Wuttke (l) <j.wuttke at fz-juelich.de>
diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst
index 0287767..1de10c4 100644
--- a/Help/manual/cmake-generators.7.rst
+++ b/Help/manual/cmake-generators.7.rst
@@ -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
-------------------------
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index c7f3537..915e0d4 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -9,7 +9,8 @@ Synopsis
.. parsed-literal::
`Generate a Project Buildsystem`_
- cmake [<options>] {<path-to-source> | <path-to-existing-build>}
+ cmake [<options>] <path-to-source>
+ cmake [<options>] <path-to-existing-build>
cmake [<options>] -S <path-to-source> -B <path-to-build>
`Build a Project`_
@@ -33,37 +34,131 @@ Synopsis
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.
-
-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.
+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
==============================
-.. code-block:: shell
+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> | <path-to-existing-build>}
- cmake [<options>] -S <path-to-source> -B <path-to-build>
+``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
-The parameter ``<path-to-source>`` must be the relative or absolute path
-of the source directory that contains the top-level ``CMakeLists.txt`` file.
-Alternatively, if the named directory contains ``CMakeCache.txt`` it will
-be treated as ``<path-to-existing-build>`` and the path to the source will
-be loaded from the cache.
+ $ cd build
+ $ cmake .
-By default, **cmake** writes the generated Makefiles and all other output
-to the directory from where it was invoked. This behavior can be changed
-by the variant with the parameter ``<path-to-build>``.
+``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
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=8b3a537c29974da62f4a46f4631bbec1550a2a23
commit 8b3a537c29974da62f4a46f4631bbec1550a2a23
Author: Joachim Wuttke (l) <j.wuttke at fz-juelich.de>
AuthorDate: Thu Nov 15 10:49:42 2018 +0100
Commit: Craig Scott <craig.scott at crascit.com>
CommitDate: Tue Nov 27 21:13:32 2018 +1100
Help: Improve cmake(1) manual organization
Extend the Synposis, and provide links to manual sections.
Add sections for `cmake --open` and `cmake --help-*`.
Introduce a new section for buildsystem generation to distinguish it
from the other functionality. Populate it with minimal placeholder text
for now. It will be extended later.
Co-Author: Brad King <brad.king at kitware.com>
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index d8b71a9..c7f3537 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -8,13 +8,27 @@ 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> | <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
===========
@@ -29,16 +43,34 @@ 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.
+
+Generate a Project Buildsystem
+==============================
+
+.. code-block:: shell
+
+ cmake [<options>] {<path-to-source> | <path-to-existing-build>}
+ cmake [<options>] -S <path-to-source> -B <path-to-build>
+
+The parameter ``<path-to-source>`` must be the relative or absolute path
+of the source directory that contains the top-level ``CMakeLists.txt`` file.
+Alternatively, if the named directory contains ``CMakeCache.txt`` it will
+be treated as ``<path-to-existing-build>`` and the path to the source will
+be loaded from the cache.
+
+By default, **cmake** writes the generated Makefiles and all other output
+to the directory from where it was invoked. This behavior can be changed
+by the variant with the parameter ``<path-to-build>``.
+
+In all cases the ``<options>`` may be zero or more of the `Options`_ below.
+
.. _`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 +82,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 +156,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:
+
+.. code-block:: shell
- cmake --build <dir> [<options>...] [-- <build-tool-options>...]
+ cmake --build <dir> [<options>] [-- <build-tool-options>]
This abstracts a native build tool's command-line interface with the
following options:
@@ -185,12 +199,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
+==============
- cmake -E <command> [<options>...]
+.. 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>]
Run ``cmake -E`` or ``cmake -E help`` for a summary of commands.
Available commands are:
@@ -326,7 +369,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 +422,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 provides a pkg-config like helper for Makefile-based projects:
- cmake --find-package <options>...
+.. code-block:: shell
-This runs in a pkg-config like mode.
+ cmake --find-package [<options>]
-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``).
+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
========
diff --git a/Help/variable/CMAKE_ARGC.rst b/Help/variable/CMAKE_ARGC.rst
index aec9711..30db2a2 100644
--- a/Help/variable/CMAKE_ARGC.rst
+++ b/Help/variable/CMAKE_ARGC.rst
@@ -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`` ...
diff --git a/Help/variable/CMAKE_ARGV0.rst b/Help/variable/CMAKE_ARGV0.rst
index 8b1ecb7..c4d1c21 100644
--- a/Help/variable/CMAKE_ARGV0.rst
+++ b/Help/variable/CMAKE_ARGV0.rst
@@ -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`.
https://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=f9c3f7b16479f84cde3b0249f83e53a32960dff3
commit f9c3f7b16479f84cde3b0249f83e53a32960dff3
Author: Joachim Wuttke (l) <j.wuttke at fz-juelich.de>
AuthorDate: Thu Nov 15 10:49:42 2018 +0100
Commit: Brad King <brad.king at kitware.com>
CommitDate: Mon Nov 26 10:17:44 2018 -0500
Help: Emphasize tool names in their manuals
Print the name of the **cmake** executable in boldface, so that it does
not appear less prominent than other shell commands (which are underlaid
with links). Similarly the other tool manuals.
diff --git a/Help/manual/ccmake.1.rst b/Help/manual/ccmake.1.rst
index cc3ceec..9548471 100644
--- a/Help/manual/ccmake.1.rst
+++ b/Help/manual/ccmake.1.rst
@@ -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.
diff --git a/Help/manual/cmake-gui.1.rst b/Help/manual/cmake-gui.1.rst
index 57a9850..9322e33 100644
--- a/Help/manual/cmake-gui.1.rst
+++ b/Help/manual/cmake-gui.1.rst
@@ -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.
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index b11526c..d8b71a9 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -19,7 +19,7 @@ Synopsis
Description
===========
-The "cmake" executable is the CMake command-line interface. It may be
+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.
diff --git a/Help/manual/cpack.1.rst b/Help/manual/cpack.1.rst
index 9ddab1e..679c547 100644
--- a/Help/manual/cpack.1.rst
+++ b/Help/manual/cpack.1.rst
@@ -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.
diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst
index e24b10d..9e0ce27 100644
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -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.
-----------------------------------------------------------------------
Summary of changes:
Help/manual/ccmake.1.rst | 2 +-
Help/manual/cmake-generators.7.rst | 4 +
Help/manual/cmake-gui.1.rst | 2 +-
Help/manual/cmake.1.rst | 266 +++++++++++++++++++++++++++++--------
Help/manual/cpack.1.rst | 6 +-
Help/manual/ctest.1.rst | 4 +-
Help/variable/CMAKE_ARGC.rst | 6 +-
Help/variable/CMAKE_ARGV0.rst | 4 +-
8 files changed, 226 insertions(+), 68 deletions(-)
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list