Extend the Synposis, and provide links to manual sections.
Add sections for `cmake --open` and `cmake --help-*`.
Introduce a new section for buildsystem generation to distinguish it
from the other functionality. Populate it with minimal placeholder text
for now. It will be extended later.
Co-Author: Brad King <brad.king@kitware.com>
Print the name of the **cmake** executable in boldface, so that it does
not appear less prominent than other shell commands (which are underlaid
with links). Similarly the other tool manuals.
The allows `-E create_symlink` to work on Windows. It utilizes
`uv_fs_symlink`. I am still unsure exactly which Windows platforms will
work without requiring Administrator privileges or needing a user/group
with the "Create Symbolic Links" User Rights. It does work with my
Windows 10 Pro with Developer Mode turned on. In the test suite check
that the symlink either worked or failed with a permissions error.
Use recent changes in cmSystemTools::FileExists to check that a symlink
is broken.
Document the previously internal option of '-B' and provide a
matching source directory option with '-S'. Both '-B', and '-S'
can be used independently of each other.
While we already support `cmake --build . -- -j`, the options after `--`
are specific to the native build tool. Add new options `--parallel
[<N>]` and `-j [<N>]` to abstract this and map to the proper option
for the native build tool.
Even in relatively small projects using `--trace` (and `--trace-expand`)
may produce a lot of output. When developing a custom module usually
one is interested in output of only a few particular modules.
Add a `--trace-source=<file>` option to enable tracing only a subset of
source files. The final output would be only from requested modules,
ignoring anything else not matched to given filename(s).
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.
Joachim Wuttke (l)