Commit 8b3a537c authored by Joachim Wuttke's avatar Joachim Wuttke Committed by Craig Scott

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@kitware.com>
parent f9c3f7b1
......@@ -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
========
......
......@@ -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