In CMake, why does an add_custom_command(OUTPUT build_info.h ...) rule never run, and when do you switch to add_custom_target instead?
answer
- a rule needs a consumer
- list the output as a target source
- same directory only
- custom targets are always out of date
- write only if changed
basics
~20 sAn OUTPUT rule is attached only to a target in the same directory that lists the output as a source, so with no consumer it never runs. Use add_custom_target when the step must run on every build, such as stamping a commit hash.
solid answer
~50 s`add_custom_command(OUTPUT ...)` defines how to make a file; it does not schedule anything. The documentation says a target created in the **same directory** that lists the output as a source gets the rule, so with no consumer the build reaches the compile and fails with `'build_info.h' file not found`. Listing the header in `add_executable` or `target_sources` fixes it, and `DEPENDS` on the generator's inputs controls reruns: when the output exists and its dependencies are unchanged, the command is skipped. That is right for generated code and wrong for a value that changes without a file changing, such as the current commit. For that, `add_custom_target` is always out of date, runs every build, and needs `add_dependencies` from the consumer; write the header only when its content changes so nothing relinks needlessly. `add_custom_command(TARGET ... POST_BUILD)` is a third tool: it runs only when that target is rebuilt.
code
cmake · 13 linesset(info_h ${CMAKE_CURRENT_BINARY_DIR}/build_info.h)
add_custom_command(
OUTPUT ${info_h}
COMMAND ${CMAKE_COMMAND} -DOUT=${info_h}
-P ${CMAKE_CURRENT_SOURCE_DIR}/tools/gen_build_info.cmake
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/tools/gen_build_info.cmake
COMMENT "Generating build_info.h"
VERBATIM)
# Listing the output as a source is what attaches the rule to a target.
add_executable(engine src/main.cpp ${info_h})
target_include_directories(engine PRIVATE ${CMAKE_CURRENT_BINARY_DIR})go deeper
Recall that add_custom_command(OUTPUT) produces files at build time and that a target must use the output for it to run.
Explain how DEPENDS controls reruns, why add_custom_target always runs, and what the PRE_LINK and POST_BUILD events mean.
Diagnose missing generated files and needless rebuilds, and choose between OUTPUT rules, custom targets, build events and configure_file.
Decide which generation steps a build may run at all, so builds stay reproducible and incremental builds stay fast as generators multiply.
## A rule is not a step `add_custom_command(OUTPUT <files> COMMAND ... DEPENDS ...)` describes how to **produce** files. It does not add work to the build by itself. The CMake documentation is specific: a target created in the **same directory** (`CMakeLists.txt` file) that specifies any output of the custom command as a source file is given a rule to generate the file at build time. Until something consumes the output, no target owns the rule. A CMake 4.4.4 build with the rule defined but the header not listed anywhere went straight to compiling `main.cpp` and failed: ```plaintext main.cpp:2:10: fatal error: 'build_info.h' file not found ``` Adding `${info_h}` to `add_executable(engine src/main.cpp ${info_h})` produced `[1/3] Generating build_info.h` before the compile. ## When an OUTPUT rule re-runs The generated build system treats the rule like any compile: - With `DEPENDS`, the command re-runs when the output is missing or older than a listed dependency. - Without `DEPENDS`, it runs whenever the output is missing; the documentation adds that if the command never actually creates the output, the rule always runs. The same project built a second time reported `ninja: no work to do.`, which is exactly right for code generated from a schema or a table. List the generator script itself in `DEPENDS`, so editing the generator regenerates the file. ## Sharing one output between targets The documentation warns against listing the same output in more than one independent target that may build in parallel, because the instances of the rule may conflict. Its recommended pattern: 1. Keep the `add_custom_command(OUTPUT ...)`. 2. Add `add_custom_target(generate_x DEPENDS <output>)` to own it. 3. Make every consumer depend on that target, so the file is produced once before any of them build. ## Values that change without a file changing A commit hash or build date changes even when no tracked input file does, so an OUTPUT rule never notices. `add_custom_target` fits here: the documentation says it has no output file and is **always considered out of date**. By default nothing depends on it, so wire it up: ```cmake add_custom_target(build_info COMMAND ${CMAKE_COMMAND} -DOUT=${info_h} -P ${CMAKE_CURRENT_SOURCE_DIR}/tools/gen_build_info.cmake BYPRODUCTS ${info_h} VERBATIM) add_dependencies(engine build_info) ``` `BYPRODUCTS` declares the header as a file the target produces even though its timestamp may not change on later builds; Ninja needs that declaration to know which step creates the file. The follow-on trap: if the script rewrites the header on every run, its timestamp changes and everything including it recompiles and relinks on every build. CMake 4.4.4 showed `[3/3] Linking CXX executable engine` on each no-change rebuild while the script used `file(WRITE ...)`. After switching to `file(CONFIGURE OUTPUT ... CONTENT ...)` (CMake 3.18), which only modifies the file when its content changes, a rebuild ran just `[1/3] Refreshing build_info.h`. `cmake -E copy_if_different` from a temporary file achieves the same. ## Build events: the TARGET form `add_custom_command(TARGET engine POST_BUILD COMMAND ...)` attaches a command to an existing target instead of producing a file: | Keyword | Runs | |---|---| | `PRE_BUILD` | Before other rules in the target with Visual Studio generators; elsewhere it behaves as `PRE_LINK` | | `PRE_LINK` | After the sources compile, before linking or archiving | | `POST_BUILD` | After everything else in the target | The documentation says the command runs only when the target itself is built; if the target is up to date, it does not run. That suits stripping, signing or copying a freshly linked binary, and not generating inputs. The target must also be defined in the current directory. ## Choosing - Generated sources or headers derived from input files: `add_custom_command(OUTPUT ...)`, listed as a source of its consumer. - One output used by several targets: the same, owned by one `add_custom_target`. - Something that must run every build: `add_custom_target` plus `add_dependencies`, writing only when content changes. - Post-processing a binary: `add_custom_command(TARGET ... POST_BUILD)`. - Values fixed at configure time, such as the project version: `configure_file`, no build step at all. Add `VERBATIM` to every custom command so arguments are escaped correctly for the build tool.
- Why can a custom target that regenerates a header every build still cause needless relinks, and how do you stop it?If the generator rewrites the header unconditionally, its timestamp changes on every build, so every source that includes it recompiles and the binary relinks. Write the file only when its content changes, with `file(CONFIGURE OUTPUT ... CONTENT ...)` or by generating to a temporary file and running `cmake -E copy_if_different`. The target still runs each build, but it leaves the header untouched.
- Why should PRE_BUILD be avoided outside Visual Studio generators?Only the Visual Studio generators give `PRE_BUILD` its own meaning, running before any other rule in the target. With every other generator it behaves as `PRE_LINK`, after the sources have compiled. A command that must happen before compilation therefore silently runs too late; the documentation recommends `PRE_BUILD` only when a Visual Studio generator is known to be in use.
- Expects an add_custom_command(OUTPUT) rule to run without any consumer
- Lists the same generated output in several parallel targets
- Uses POST_BUILD to generate a header the target compiles
- Believes PRE_BUILD runs before compilation with every generator
- Regenerates a stamp header unconditionally and wonders why it always relinks