Fixes: #19771

Target-level dependencies to utility targets are added from another target if
the other target requires a byproduct of the utility target or if it requires a
byproduct of PRE_BUILD, PRE_LINK, or POST_BUILD build events of a target.

Issue: #19005

Provide a way for custom commands and targets to set the pool variable
of the ninja build statement. Setting `JOB_POOL` is not compatible with
`USES_TERMINAL`, which implies the `console` pool.

The option is silently ignored with other generators.

Closes: #18483

  * Replace most "::" by ".. code-block:: cmake"
  * Header sentence in imperative voice,
    detailed command description in present tense.

Jon Chronopoulos authored Sep 22, 2018 and Brad King committed Sep 28, 2018

This teaches add_custom_command and add_custom_target WORKING_DIRECTORY
about generator expressions

Fixes: #14089

Fixes: #17949

This generator has been deprecated since CMake 3.9.  Remove it.

This generator has been deprecated since CMake 3.6.  Remove it.

This option allows lists generated by generator expressions to be expanded.

Closes: #15935

Christoph Kulla authored Aug 05, 2016 and Brad King committed Aug 30, 2016

Provide a way for custom commands to inform the ninja build tool about
their implicit dependencies.  For now simply make use of the option an
error on other generators.

Closes: #15479

Jean-Christophe Fillion-Robin authored May 04, 2016 and Brad King committed May 09, 2016

Teach the `add_custom_command` and `add_custom_target' commands to
substitute argv0 with the crosscompiling emulator if it is a target with
the `CROSSCOMPILING_EMULATOR` property set.

When documenting in the COMMAND option how to reference an executable,
we previously only explicitly covered how to do it for argv[0] and left
it to the reader to follow the reference to the generator expressions
manual.  Add explicit mention of the TARGET_FILE genex in this
documentation since it will be a commonly used generator expression in
this context.

Specify explicitly that at most one custom command may use a given
source file as its main dependency.

A common idiom in CMake-based build systems is to have custom commands
that generate files not listed explicitly as outputs so that these
files do not have to be newer than the inputs.  The file modification
times of such "byproducts" are updated only when their content changes.
Then other build rules can depend on the byproducts explicitly so that
their dependents rebuild when the content of the original byproducts
really does change.

This "undeclared byproduct" approach is necessary for Makefile, VS, and
Xcode build tools because if a byproduct were listed as an output of a
rule then the rule would always rerun when the input is newer than the
byproduct but the byproduct may never be updated.

Ninja solves this problem by offering a 'restat' feature to check
whether an output was really modified after running a rule and tracking
the fact that it is up to date separately from its timestamp.  However,
Ninja also stats all dependencies up front and will only restat files
that are listed as outputs of rules with the 'restat' option enabled.
Therefore an undeclared byproduct that does not exist at the start of
the build will be considered missing and the build will fail even if
other dependencies would cause the byproduct to be available before its
dependents build.

CMake works around this limitation by adding 'phony' build rules for
custom command dependencies in the build tree that do not have any
explicit specification of what produces them.  This is not optimal
because it prevents Ninja from reporting an error when an input to a
rule really is missing.  A better approach is to allow projects to
explicitly specify the byproducts of their custom commands so that no
phony rules are needed for them.  In order to work with the non-Ninja
generators, the byproducts must be known separately from the outputs.

Add a new "BYPRODUCTS" option to the add_custom_command and
add_custom_target commands to specify byproducts explicitly.  Teach the
Ninja generator to specify byproducts as outputs of the custom commands.
In the case of POST_BUILD, PRE_LINK, and PRE_BUILD events on targets
that link, the byproducts must be specified as outputs of the link rule
that runs the commands.  Activate 'restat' for such rules so that Ninja
knows it needs to check the byproducts, but not for link rules that have
no byproducts.

Peter Collingbourne authored Nov 05, 2014 and Brad King committed Nov 14, 2014

Teach the add_custom_command and add_custom_target commands a new
USES_TERMINAL option.  Use it to tell the generator to give the command
direct access to the terminal if possible.

Explicitly say that the commands are not composed into a stateful
script.

State explicitly that the PRE_LINK mode is not for targets created by
the add_custom_target command.  The existing wording for PRE_BUILD being
treated as PRE_LINK by non-VS generators will now imply this restriction
for PRE_BUILD too.

Format the reStructuredText markup manually.  Organize the command
options into a definition list.  Use inline markup to cross-reference
related documents.

Remove leftover generator expression documentation that is now in
the cmake-generator-expressions(7) manual.

Stephen Kelly authored Mar 07, 2014 and Brad King committed Mar 20, 2014

Rely on evaluation in cmCustomCommandGenerator for the generators.

When tracing target dependencies, depend on the union of dependencies
for all configurations.

Generator expressions are supported in many places and are a distinct
concept worthy of their own manual page.  The old builtin documentation
was previously represented by preprocessor macros to generate it into
each place that supports them.  Factor out the duplicate content into a
dedicated cmake-generator-expressions manual page and reference it from
each original location.

Kitware Robot authored Oct 15, 2013 and Brad King committed Oct 15, 2013

Run the convert-help.bash script to convert documentation:

 ./convert-help.bash "/path/to/CMake-build/bin"

Then remove it.