Skip to content
  • Brad King's avatar
    Add an option for explicit BYPRODUCTS of custom commands (#14963) · e15a7075
    Brad King authored
    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.
    e15a7075