The `--build` mode was confusingly documented among other options,
falsely implying that it can be used anywhere on the command line.
Move the documentation to a dedicated section and clarify its usage
as s separate command line mode.
Previously we did not clearly document that `--target` is only supported
to be specified once. Even worse, specifying it multiple times would
silently ignore any previously specified targets and only build the last
target.
Update the documentation to specify this. Update the implementation to
reject multiple `--target` options to prevent user errors.
If multiple input files are provided then the destination must be a
directory. If only one input file is provided then destination may be
either a file or directory.
Improve formatting, primarily by:
* Adding links to relevant commands, properties, generators, and so on.
* Converting code, symbols, paths, and so on to fixed-width fonts.
* Hard wrapping lines to 80 characters or less.
The --trace option is helpful, but sometimes, what you're looking for is
deep under many layers of function calls and figuring out what instance
of the function call you're looking at is tedious to determine (usually
involving patching and message()). Instead, add a --trace-expand option
to trace while expanding commands into what CMake actually sees.
Always show the option with its argument separate in summary text.
State in the main documentation that the option and its argument can be
given together too.
Extend the cmake command-line interface to support
cmake -E env [--unset=NAME]... [NAME=VALUE]... COMMAND [ARG]...
This will be useful to run processes with modified environments
without using a shell or a full "cmake -P" script to wrap it.
Extend the RunCMake.CommandLine test to cover success and failure cases.
Inspired-by: Jonathan Bohren <jbo@jhu.edu>
Add the man page description line as explicit markup at the top of each
Help/manual/*.rst file and scan it from conf.py to automatically
generate the man_pages Sphinx configuration value. This reduces the
number of places that need to be changed when a new manual is added.
Enable the --use-stderr behavior by default and ignore the old option.
Passing through the pipes allows color terminal output and other things
to work as if one ran the native build command directly.
Make the standard --help-* options available from all command-line
tools. Drop options that are no longer supported:
--copyright, --help-full, --help-html, --help-man,
--help-compatcommands, --help-custom-modules
De-duplicate Help/manual/*.1.rst help options by using an
OPTIONS_HELP.txt file included from each manual.
Add "Synopsis", "Description", and "See Also" manual page section
headers. These are typical of .1 man section pages. Also de-duplicate
the See Also section links using a separate LINKS.txt file included from
each manual.
Brad King
Bartosz Kosiorek
Sebastian Schuberth
Bartosz Kosiorek
James Johnston
Ben Boeckel
Nils Gladitz
Kitware Robot