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.
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.
While tracing dependencies of a target, cmTargetTraceDependencies
follows sources by full path to determine if the source is to be
produced by a custom command. Commit 4959f341 (cmSourceFileLocation:
Collapse full path for directory comparisons., 2014-03-27) changed
the storage of target sources to be in the form of a normalized
path instead of an unnormalized path.
The path is followed by looking it up in a mapping via
cmMakefile::GetSourceFileWithOutput to acquire an appropriate
cmSourceFile. The mapping is populated with the OUTPUT components
of add_custom_command invocations, however it is populated with
unnormalized paths. This means that the tracing logic does not
find appropriate cmSourceFiles, and does not generate appropriate
build rules for the generated sources.
Normalize the paths in the OUTPUT components of add_custom_command
to resolve this.
The paths in the DEPENDS component of add_custom_command are also
not normalized, leading to the same problem again. Normalize the
depends paths after generator evaluation and expansion.
Use the clang RemoveCStrCalls tool to automatically migrate the
code. This was only run on linux, so does not have any positive or
negative effect on other platforms.
All commands accepting file paths should normalize the slashes so that
the string-represented names can be compared reliably. The commands
add_library and add_executable have done this for years. We taught
add_custom_command to normalize its OUTPUT names in commit a75a0a14
(Normalize add_custom_command OUTPUT names, 2010-12-15). We handled a
special case of the DEPENDS option in commit 7befc007 (Handle trailing
slashes on add_custom_command DEPENDS, 2011-01-26).
Teach both add_custom_command and add_custom_target to normalize slashes
of DEPENDS files up front. This approach subsumes the above-mentioned
special case so remove the one line added for it but keep its test.
Extend the CustomCommand test to check that slash count mismatches
between custom command OUTPUT and DEPENDS can still be linked correctly.
Previously the OUTPUT arguments of add_custom_command were not
slash-normalized but those of add_library and add_executable were.
This caused the example
add_custom_command(OUTPUT a//b.c ...)
add_library(... a//b.c ...)
to fail at build time with "no rule to make a/b.c". Fix this and modify
the CustomCommand test to try it.
This converts the CMake license to a pure 3-clause OSI-approved BSD
License. We drop the previous license clause requiring modified
versions to be plainly marked. We also update the CMake copyright to
cover the full development time range.
- Option was recently added but never released.
- Custom commands no longer depend on build.make so we do
not need the option.
- Rule hashes now take care of rebuilding when rules change
so the dependency is not needed.
- Allows make rules to be created with no dependencies.
- Such rules will not re-run even if the commands themselves change.
- Useful to create rules that run only if the output is missing.
Stephen Kelly
Brad King
Peter Collingbourne
Nils Gladitz
Ken Martin
Andy Cedilnik
Bill Hoffman
Sebastien Barre
Will Schroeder