CMake generated files: separate build ordering from regeneration dependencies

What it is

A generated file needs a producing rule, declared inputs and a consumer. CMake distinguishes a target-level dependency, which orders targets, from a file-level dependency, which can cause regeneration. Merely mentioning a generator through a target-file expression does not provide both. The custom-command documentation also distinguishes main outputs from byproducts. CMake add_custom_command

Why it matters

When an agent fixes a missing header by adding a broad build dependency, the next clean build may succeed while an edited schema still leaves stale code. Treat the failure as a missing edge in the build graph. The proposed review below asks which change invalidates each generated artefact.

How to apply

• Draw a small graph containing the schema, generator executable, generated source and consuming target. Label ordering edges separately from regeneration edges.
• Give each generated output one owning rule. For several consumers, introduce a shared generation target rather than copying the command into each consumer.
• List the schema and generator in the appropriate dependencies; declare secondary generated files as byproducts. Use VERBATIM when supplying command arguments.
• In a disposable build tree, propose checks for a clean build, an unchanged rebuild, a schema edit, a generator edit and deletion of a byproduct. Record which generator command actually runs each time.
• Repeat the relevant build with parallel execution and paths containing spaces. Review generated content as well as timestamps before accepting the change.

Pitfalls

Do not “repair” an incremental build by always deleting the build directory: that removes the evidence. A successful rebuild is not proof that all input edges are present. Depfile support and policy behavior depend on the selected CMake version and generator. Verify those details for the project's declared minimum version before adding newer options.