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

Help/manual/cmake.1.rst

@@ -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
 ========