diff options
author | Brad King <brad.king@kitware.com> | 2021-07-13 09:33:52 -0400 |
---|---|---|
committer | Brad King <brad.king@kitware.com> | 2021-07-13 09:41:26 -0400 |
commit | 161f1f42d6400f4de85767108c090991c41326fe (patch) | |
tree | 1dff6a4f562c330c67eb67f9b75ea094b73e728d | |
parent | 00e8292434871887f174cfc1a8b3941abefe4cb1 (diff) | |
download | cmake-161f1f42d6400f4de85767108c090991c41326fe.tar.gz |
Help: Clarify 'cmake --build' signature alternatives
Documentation added by
* commit 4f4f2028b8 (Help: Add documentation for buildPresets and
testPresets, 2021-01-13, v3.20.0-rc1~51^2~7)
* commit 676ecf0d37 (cmake-presets: Add build and test presets,
2020-12-14, v3.20.0-rc1~51^2~6)
used square brackets in the `cmake --build` signature to indicate
non-optional alternatives, which is not a typical convention.
A common convention is to use parentheses instead, but in this
case it is probably clearer to list the two signatures separately.
Fixes: #22413
16 files changed, 20 insertions, 16 deletions
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index 2d639b68ec..e23ddd8231 100644 --- a/Help/manual/cmake.1.rst +++ b/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: diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx index d83183f390..1725375d95 100644 --- a/Source/cmakemain.cxx +++ b/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" diff --git a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-bad-number-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build--parallel-bad-number-stderr.txt index 16f8be8b0e..96de4d17db 100644 --- a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-bad-number-stderr.txt +++ b/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\]\] diff --git a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-large-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build--parallel-large-stderr.txt index e7b9aaaf2a..0bb806ff43 100644 --- a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-large-stderr.txt +++ b/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\]\] diff --git a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-no-space-bad-number-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build--parallel-no-space-bad-number-stderr.txt index 16f8be8b0e..96de4d17db 100644 --- a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-no-space-bad-number-stderr.txt +++ b/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\]\] diff --git a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-zero-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build--parallel-zero-stderr.txt index d1241f46db..b965d4a47c 100644 --- a/Tests/RunCMake/CommandLine/BuildDir--build--parallel-zero-stderr.txt +++ b/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\]\] diff --git a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-bad-number-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build-jobs-bad-number-stderr.txt index d52b16583a..97e90ec99a 100644 --- a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-bad-number-stderr.txt +++ b/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\]\] diff --git a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-large-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build-jobs-large-stderr.txt index e7b9aaaf2a..0bb806ff43 100644 --- a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-large-stderr.txt +++ b/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\]\] diff --git a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-no-space-bad-number-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build-jobs-no-space-bad-number-stderr.txt index d52b16583a..97e90ec99a 100644 --- a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-no-space-bad-number-stderr.txt +++ b/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\]\] diff --git a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-zero-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build-jobs-zero-stderr.txt index d1241f46db..b965d4a47c 100644 --- a/Tests/RunCMake/CommandLine/BuildDir--build-jobs-zero-stderr.txt +++ b/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\]\] diff --git a/Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-first-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-first-stderr.txt index 2dd9bc4249..c15fdbabd9 100644 --- a/Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-first-stderr.txt +++ b/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\]\] diff --git a/Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-second-stderr.txt b/Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-second-stderr.txt index 2dd9bc4249..c15fdbabd9 100644 --- a/Tests/RunCMake/CommandLine/BuildDir--build-multiple-targets-with-clean-second-stderr.txt +++ b/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\]\] diff --git a/Tests/RunCMake/CommandLine/build-no-dir-stderr.txt b/Tests/RunCMake/CommandLine/build-no-dir-stderr.txt index 9b4d26bc29..4811bea2f7 100644 --- a/Tests/RunCMake/CommandLine/build-no-dir-stderr.txt +++ b/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\]\] diff --git a/Tests/RunCMake/CommandLine/build-unknown-command-long-stderr.txt b/Tests/RunCMake/CommandLine/build-unknown-command-long-stderr.txt index c8f1a03cb8..559e4b6135 100644 --- a/Tests/RunCMake/CommandLine/build-unknown-command-long-stderr.txt +++ b/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\]\] diff --git a/Tests/RunCMake/CommandLine/build-unknown-command-partial-match-stderr.txt b/Tests/RunCMake/CommandLine/build-unknown-command-partial-match-stderr.txt index e4ad6b2da4..1f44c4e33f 100644 --- a/Tests/RunCMake/CommandLine/build-unknown-command-partial-match-stderr.txt +++ b/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\]\] diff --git a/Tests/RunCMake/CommandLine/build-unknown-command-short-stderr.txt b/Tests/RunCMake/CommandLine/build-unknown-command-short-stderr.txt index a6cfeceace..4f5ba558bc 100644 --- a/Tests/RunCMake/CommandLine/build-unknown-command-short-stderr.txt +++ b/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\]\] |