Inconsistent use of square brackets in cmake CLI documentation
When you type an erroneous build command like cmake --build --config Debug
(here I missed a directory after --build
), you get a short usage description:
(env) d:\projects\videolib\build\vs2019>cmake --build --config Debug
Unknown argument Debug
Usage: cmake --build [<dir> | --preset <preset>] [options] [-- [native-options]]
Options:
<dir> = Project binary directory to be built.
--preset <preset>, --preset=<preset>
= Specify a build preset.
--list-presets
= List available build presets.
--parallel [<jobs>], -j [<jobs>]
= Build in parallel using the given number of jobs.
If <jobs> is omitted the native build tool's
default number is used.
The CMAKE_BUILD_PARALLEL_LEVEL environment variable
specifies a default parallel level when this option
is not given.
--target <tgt>..., -t <tgt>...
= Build <tgt> instead of default targets.
--config <cfg> = For multi-configuration tools, choose <cfg>.
--clean-first = Build target 'clean' first, then build.
(To clean only, use --target 'clean'.)
--verbose, -v = Enable verbose output - if supported - including
the build commands to be executed.
-- = Pass remaining options to the native tool.
Both [options]
and [-- [native-options]]
are optional in the CLI. Later in the same help we also see an optional [jobs]
. Thus one can think that [<dir> | --preset <preset>]
is also optional. This, combined with an unclear error message (Unknown argument Debug
) makes it difficult to find out what's wrong with a command. This took away a lot of my time just now.
It would be nice to have a consistent usage of special symbols like []
. E.g.: []
can be used only for optional elements and ()
can be used for grouping: (<dir> | --preset <preset>)
.
cmake version: 3.20.5 OS: Windows 10 x64.
Edited by artem-kamyshev