From f9c3f7b16479f84cde3b0249f83e53a32960dff3 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Thu, 15 Nov 2018 10:49:42 +0100 Subject: 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. --- Help/manual/ccmake.1.rst | 2 +- Help/manual/cmake-gui.1.rst | 2 +- Help/manual/cmake.1.rst | 2 +- Help/manual/cpack.1.rst | 6 +++--- Help/manual/ctest.1.rst | 4 ++-- 5 files changed, 8 insertions(+), 8 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-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 `. 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. -- cgit v0.12 From 8b3a537c29974da62f4a46f4631bbec1550a2a23 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Thu, 15 Nov 2018 10:49:42 +0100 Subject: 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 --- Help/manual/cmake.1.rst | 155 +++++++++++++++++++++++++++++------------- Help/variable/CMAKE_ARGC.rst | 6 +- Help/variable/CMAKE_ARGV0.rst | 4 +- 3 files changed, 112 insertions(+), 53 deletions(-) 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 [] { | } - cmake [] -S -B - cmake [{-D =}...] -P - cmake --build [...] [-- ...] - cmake --open - cmake -E [...] - cmake --find-package ... + `Generate a Project Buildsystem`_ + cmake [] { | } + cmake [] -S -B + + `Build a Project`_ + cmake --build [] [-- ] + + `Open a Project`_ + cmake --open + + `Run a Script`_ + cmake [{-D =}...] -P + + `Run a Command-Line Tool`_ + cmake -E [] + + `Run the Find-Package Tool`_ + cmake --find-package [] + + `View Help`_ + cmake --help[-] 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 [] { | } + cmake [] -S -B + +The parameter ```` 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 ```` 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 ````. + +In all cases the ```` may be zero or more of the `Options`_ below. + .. _`CMake Options`: Options -======= +------- .. include:: OPTIONS_BUILD.txt -``-E [...]`` - 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 `` - See `Build Tool Mode`_. - -``--open `` - 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 `` - 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 [...] [-- ...] + cmake --build [] [-- ] 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 [...] +.. code-block:: shell + + cmake --open + +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 =}...] -P + +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 [] Run ``cmake -E`` or ``cmake -E help`` for a summary of commands. Available commands are: @@ -326,7 +369,7 @@ Available commands are: ``sleep ...`` Sleep for given number of seconds. -``tar [cxt][vf][zjJ] file.tar [...] [--] [...]`` +``tar [cxt][vf][zjJ] file.tar [] [--] [...]`` 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 `` 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 ... +.. code-block:: shell -This runs in a pkg-config like mode. + cmake --find-package [] -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[-] + +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 ` 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