This option has been broken since commit b9f9915516 (cmMakefile: Remove
VarUsageStack., 2015-05-17, v3.3.0-rc1~52^2). That commit removed the
check that an initialized variable has actually been used and caused the
option to warn on every variable ever set. This was not caught by the
test suite because the test for the feature only checked that warnings
appear when needed and not that they do not appear when not needed.
The option was never very practical to use. Remove it to avoid the
runtime cost of usage tracking and checks for every variable (which we
were doing even when the option was not used).
1994f950ff cmake: List valid values for --trace-format on the command line
e39766d84a Help: Fix documentation of --trace-format parameter
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !4500
For users of CMake who want to optimize their scripts if they take a
while to run, this commit adds the ability to output profiling data.
To enable this output, it adds the two command line parameters
to select the output path and format.
This commit adds the first profiling format of type ``google-trace``,
which is the output is a JSON file containing Duration events as per the
Google Trace Format specification:
https://docs.google.com/document/d/1CvAClvFfyA5R-
PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview#
Add the timestamp and stack depth of the function call to the JSON trace
output format. This information can be useful for cmake profiling and
call stack inspection (see e.g. https://github.com/volo-zyko/cmake-profile-stats).
Improve unit test to allow for varying set of keys to check in trace lines.
e113ab1168 trace: Add test for the JSON-v1 trace
482497e0de trace: Add JSON output format
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !4102
Add a new `--trace-format=` flag, to enable the new JSON trace
output format. This new format is easier to parse by machines
than the existing format. This new format also removes the
ambiguity of the whitespace in the "old" format (e.g. is that
whitespace part of a file path, or does it seperate arguments)
Enable debug messages a new `--find-debug` command-line option or via
the `CMAKE_FIND_DEBUG_MODE` variable.
This work was started by Chris Wilson, continued by Ray Donnelly, and
then refactored by Robert Maynard to collect information into a single
message per find query.
Co-Author: Ray Donnelly <mingw.android@gmail.com>
Co-Author: Chris Wilson <chris+github@qwirx.com>
Other multi-word command line options use hyphens to separate
the words, so the --loglevel option introduced in CMake 3.15 was
inconsistent in this regard. Rename it to --log-level but still support
the original --loglevel name to preserve backward compatibility.
Update documentation for the change made by commit e6c9a8bac3 (cmake:
Teach -E remove_directory to remove directory symlinks, 2019-08-26).
Also add a release note.
Issue: #19533
The message() command requires uppercase log levels. Even
though the cmake --loglevel option is not case sensitive, show
the supported values as uppercase to match the message()
docs as closely as possible, since they are related to the same
feature.
Also fixes the wrong string being shown for the warning level
by cmake --help.
It isn't yet clear whether we want to make this part of the
documented API for the install script. Remove it from the
docs before it appears in an official release for now.
Relates: #18997
077ab5774c cmake: add short version of '--target <tgt>...' option
071f5e1544 cmake: Reformat '--parallel' and '--verbose' options in help
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !3078
While we already support `VERBOSE` environment variable and
`CMAKE_VERBOSE_MAKEFILE` cached variable, add `-v` and `--verbose`
command line options to be able to activate verbose output directly from
CMake's build tool mode command line.
Also make `msbuild` honor the verbosity setting. `xcodebuild` still
doesn't honor the verbosity setting as it will need a policy added
and reworking of cmGlobalGenerator and cmsys to support
multiple command invocation.
Extend the description section to cover all capabilities that
the "cmake" tool has. Extend the buildsystem generation section
to introduce important concepts and describe the basic workflow.
Inspired-by: Joachim Wuttke (l) <j.wuttke@fz-juelich.de>
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.
