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