Merge topic 'doc-cmake-build-signature' into release-3.21

161f1f4 Help: Clarify 'cmake --build' signature alternatives

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6343

Help/manual/cmake.1.rst

@@ -408,7 +408,8 @@ project binary tree:
 
 .. code-block:: shell
 
-  cmake --build [<dir> | --preset <preset>] [<options>] [-- <build-tool-options>]
+  cmake --build <dir>             [<options>] [-- <build-tool-options>]
+  cmake --build --preset <preset> [<options>] [-- <build-tool-options>]
 
 This abstracts a native build tool's command-line interface with the
 following options:

Source/cmakemain.cxx

@@ -600,7 +600,10 @@ int do_build(int ac, char const* const* av)
   if (dir.empty() && presetName.empty() && !listPresets) {
     /* clang-format off */
     std::cerr <<
-      "Usage: cmake --build [<dir> | --preset <preset>] [options] [-- [native-options]]\n"
+      "Usage: cmake --build <dir>            "
+      " [options] [-- [native-options]]\n"
+      "       cmake --build --preset <preset>"
+      " [options] [-- [native-options]]\n"
       "Options:\n"
       "  <dir>          = Project binary directory to be built.\n"
       "  --preset <preset>, --preset=<preset>\n"

Tests/RunCMake/CommandLine/BuildDir--build--parallel-bad-number-stderr.txt

@@ -1,3 +1,3 @@
 ^'--parallel' invalid number '12ab' given\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build--parallel-large-stderr.txt

@@ -1,3 +1,3 @@
 ^The <jobs> value is too large\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build--parallel-no-space-bad-number-stderr.txt

@@ -1,3 +1,3 @@
 ^'--parallel' invalid number '12ab' given\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build--parallel-zero-stderr.txt

@@ -1,3 +1,3 @@
 ^The <jobs> value requires a positive integer argument\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build-jobs-bad-number-stderr.txt

@@ -1,3 +1,3 @@
 ^'-j' invalid number '12ab' given\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build-jobs-large-stderr.txt

@@ -1,3 +1,3 @@
 ^The <jobs> value is too large\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build-jobs-no-space-bad-number-stderr.txt

@@ -1,3 +1,3 @@
 ^'-j' invalid number '12ab' given\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build-jobs-zero-stderr.txt

@@ -1,3 +1,3 @@
 ^The <jobs> value requires a positive integer argument\.
 +
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-first-stderr.txt

@@ -1,2 +1,2 @@
 ^Error: Building 'clean' and other targets together is not supported\.
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-second-stderr.txt

@@ -1,2 +1,2 @@
 ^Error: Building 'clean' and other targets together is not supported\.
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/build-no-dir-stderr.txt

@@ -1 +1 @@
-^Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+^Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/build-unknown-command-long-stderr.txt

@@ -1,2 +1,2 @@
 ^Unknown argument --invalid-command
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/build-unknown-command-partial-match-stderr.txt

@@ -1,2 +1,2 @@
 ^Unknown argument --targetinvalid
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]

Tests/RunCMake/CommandLine/build-unknown-command-short-stderr.txt

@@ -1,2 +1,2 @@
 ^Unknown argument -invalid-command
-Usage: cmake --build \[<dir> \| --preset <preset>\] \[options\] \[-- \[native-options\]\]
+Usage: cmake --build <dir> +\[options\] \[-- \[native-options\]\]