Commit d5e1e187 authored by Brad King's avatar Brad King Committed by Kitware Robot
Browse files

Merge topic 'doc-cmake-command-modes'

3e503fe1 Help: Document `cmake --build` as a separate command mode (#16093)
d4faed2f Help: Document `cmake --find-package` as a separate command mode
parents 1a027804 3e503fe1
......@@ -10,7 +10,7 @@ Synopsis
cmake [<options>] (<path-to-source> | <path-to-existing-build>)
cmake [(-D <var>=<value>)...] -P <cmake-script-file>
cmake --build <dir> [<options>] [-- <build-tool-options>...]
cmake --build <dir> [<options>...] [-- <build-tool-options>...]
cmake -E <command> [<options>...]
cmake --find-package <options>...
......@@ -49,23 +49,7 @@ Options
display help for each variable.
``--build <dir>``
Build a CMake-generated project binary tree.
This abstracts a native build tool's command-line interface with the
following options:
::
<dir> = Project binary directory to be built.
--target <tgt> = Build <tgt> instead of default targets.
May only be specified once.
--config <cfg> = For multi-configuration tools, choose <cfg>.
--clean-first = Build target 'clean' first, then build.
(To clean only, use --target 'clean'.)
--use-stderr = Ignored. Behavior is default in CMake >= 3.0.
-- = Pass remaining options to the native tool.
Run ``cmake --build`` with no options for quick help.
See `Build Tool Mode`_.
``-N``
View mode only.
......@@ -82,12 +66,7 @@ Options
done before the -P argument.
``--find-package``
Run in pkg-config like mode.
Search a package using 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).
See `Find-Package Tool Mode`_.
``--graphviz=[file]``
Generate graphviz of dependencies, see CMakeGraphVizOptions.cmake for more.
......@@ -154,6 +133,38 @@ Options
.. include:: OPTIONS_HELP.txt
Build Tool Mode
===============
CMake provides a command-line signature to build an already-generated
project binary tree::
cmake --build <dir> [<options>...] [-- <build-tool-options>...]
This abstracts a native build tool's command-line interface with the
following options:
``--build <dir>``
Project binary directory to be built. This is required and must be first.
``--target <tgt>``
Build ``<tgt>`` instead of default targets. May only be specified once.
``--config <cfg>``
For multi-configuration tools, choose configuration ``<cfg>``.
``--clean-first``
Build target ``clean`` first, then build.
(To clean only, use ``--target clean``.)
``--use-stderr``
Ignored. Behavior is default in CMake >= 3.0.
``--``
Pass remaining options to the native tool.
Run ``cmake --build`` with no options for quick help.
Command-Line Tool Mode
======================
......@@ -278,6 +289,24 @@ 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::
cmake --find-package <options>...
This runs in a pkg-config like mode.
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``).
.. 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.
See Also
========
......
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