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@kitware.com>
Merge-request: !2662

8 files changed, 226 insertions, 68 deletions

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-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-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..915e0d4 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -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
 ========
 
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.
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`.