Make Found Nothing to Rebuild. The Header Had Changed.

In a DevOps pipeline, a successful make with exit code 0 usually signals a fresh build, but that green-light can be misleading. Imagine a release engineer runs an incremental build, sees “nothing to be done,” and ships the binary, only to discover later that a modified header file’s change wasn’t included. The acceptance question is concrete: Does the compiled artifact truly reflect every declared input change? The team must treat an apparently “up-to-date” build as unproven unless its binary’s behavior matches the inputs. This article walks through a minimal GNU Make + GCC example where a header edit should have invalidated and rebuilt an object but did not. It shows how missing dependency edges can let make succeed while yielding stale output.

Our audience is build maintainers and DevOps engineers who need to validate incremental builds. We work in a controlled Linux directory with GNU Make 4.4.1 and GCC 14.2.0, capturing compiler/make versions and file timestamps. We avoid peripheral topics (Docker, CI fleets, etc.) and focus purely on Make’s dependency graph and GCC’s auto-dependency flags. We do not claim hermetic or bit-reproducible builds; this scoped test only covers user-header changes in one .c file. Each incremental case is classified into four release-decision outcomes: ACCEPT (artifact is verified current), REPAIR (fix the graph rules), CLEAN-REBUILD (wipe outputs and rebuild), or HOLD (don’t ship an unproven artifact). The playbook shows how to detect a stale build, strengthen the graph, and decide what to do when metadata (like a missing depfile) is lost. At the end, we compare the incremental build outputs against an independent clean compile (the real “truth”) before accepting a release binary. By the end, you’ll see not just how to fix Makefile bugs, but how to gate releases until every header change is accounted for.

Define what a current binary must demonstrate

An incremental build script (or CI pipeline) can only promise “current” if the final executable’s behavior matches all declared inputs. In Make terms, that means every header or source the program should use was declared as a prerequisite to propagate its timestamp to a rebuild. If a header changed but was omitted from the Makefile graph, GNU Make will happily skip a rebuild, and make exits 0, as if everything is fine. But from the team’s perspective, that green status is a false positive. The binary can’t be accepted unless it embodies the header change. We define an artifact as current only if a fresh build from the edited sources produces the same runtime output as the incremental build; otherwise, the build itself is faulty and must be remedied.

In other words, tool success (exit status) is not enough; the build’s release policy must require functional evidence that the declared dependency graph was honored. This aligns with build-and-release best practices in a DevOps environment, where a pipeline’s “green” means not just passing scripts but actually delivering correct behavior. For example, a pipeline flow guide might encourage fast rebuilds and artifact caching, but ultimately the team’s gate requires testable proof: if a header changes, the binary must reflect that change at runtime. We treat the build artifact as the contract. Even though make finished without error, we ask: “Did editing limits.h to define a new LIMIT value cause the incremental build to redo the compile/link steps so the executable prints the new value?” If not, the graph is incomplete.

This article assumes a baseline where a header edit should change behavior (printing a constant) and explores when Make fails to do so. We track all file mtimes, compiler flags, and outputs in a temporary directory (to avoid altering system state). The target audience should be familiar with Make syntax and the concept of prerequisites; we won’t re-teach basic Make features or diverge into CI tooling or Docker caching. Instead, we focus on how GNU Make decides what to rebuild. By understanding that decision logic, we can identify stale builds and decide whether to accept a cached object or require a repair and rebuild.

For full context on automating and validating builds in a release pipeline, see Refonte’s DevOps lifecycle guide. In the next section we inspect the actual Makefile graph that was in effect.

Read the graph Make was actually given

Let’s examine the initial Makefile’s relevant rules (recipe lines begin with a tab):

.DEFAULT_GOAL := all
.PHONY: all
all: build/app

build/app: build/main.o
  gcc $< -o $@

build/main.o: main.c | build
  gcc -c main.c -o $@

build:
  mkdir -p $@

This snippet declares all -> build/app -> build/main.o -> main.c. There is one normal prerequisite (main.c) for build/main.o, and an order-only prerequisite (| build) to ensure the build/ directory exists. Crucially, neither config.h nor limits.h (which main.c includes indirectly) are listed as prerequisites. In Make’s graph, these headers are invisible edges: Make will not rebuild main.o if they change, because it only watches main.c’s timestamp here.

Recall from GNU Make’s own manual: a normal prerequisite does two things: (1) it enforces build-order and (2) if it’s newer than the target, it makes the target out-of-date. In contrast, an order-only prerequisite (after a |) enforces only build-order, not freshness. In our case, main.c is a normal prerequisite of build/main.o, so if main.c changed, Make would recompile. But config.h and limits.h weren’t mentioned at all (neither as normal nor order-only). Hence, the compiler may know about them internally, but Make’s graph is unaware. The result: editing limits.h won’t trigger the build/main.o rule, because Make never saw a “dependency relationship” for it.

The build/ directory is correctly marked order-only, which is appropriate: we want to create it if missing, but not treat directory timestamp changes as invalidating main.o. (Directory timestamps change when contents are added, so they’re poor rebuild signals.) Here, build works as intended (it’s only for ordering) and does not protect us from stale code. Our missing prerequisites are the real problem. The graph Make was given is incomplete. Before we fix it, we’ll build the transitive-header fixture to reproduce the issue.

Build the transitive-header fixture in isolation

First, we set up the source files in a new temp directory (illustrated here as console commands). The directory structure is disposable and starts empty. We then verify tool versions and initial behavior:

# Create workspace and write source files
mkdir build-header-test && cd build-header-test
cat > main.c << 'EOF'
#include <stdio.h>
#include "config.h"
int main(void) {
    printf("%d\n", LIMIT);
    return 0;
}
EOF
cat > config.h << 'EOF'
#include "limits.h"
EOF
cat > limits.h << 'EOF'
#define LIMIT 7
EOF

The code: main.c includes <stdio.h> and "config.h". In turn, config.h includes "limits.h", which defines LIMIT. Initially LIMIT is 7. The executable should print 7. Note that limits.h is not directly included by main.c; it’s transitive via config.h.

Next, record the tools:

which make && make --version | head -n1
which gcc && gcc --version | head -n1

Sample output (actual paths may vary):

/usr/bin/make
GNU Make 4.4.1
/usr/bin/gcc
gcc (GCC) 14.2.0

This ensures we use GNU Make 4.4.1 and GCC 14.2.0, matching our research environment. (These versions are explicitly invoked in our harness but not assumed to be latest.)

Now put the Makefile in place exactly as above:

.DEFAULT_GOAL := all
.PHONY: all
all: build/app

build/app: build/main.o
  gcc $< -o $@

build/main.o: main.c | build
  gcc -c main.c -o $@

build:
  mkdir -p $@

Here the dependency graph (excluding order-only) is:

•   all depends on build/app.

•   build/app depends on build/main.o.

•   build/main.o depends on main.c.

Visually:

all
 └─ build/app
     └─ build/main.o
         └─ main.c

Notice config.h and limits.h are not in this tree (they aren’t listed under main.o).

We first build from scratch and run the program:

make
./build/app

Expected output is 7. This confirms the baseline behavior before any changes. (We can also record build/main.o and build/app hashes or contents for reference.) No error occurs, since Make compiles main.o and links build/app normally. We verify the graph: by default, Make doesn’t know it must rebuild main.o if config.h or limits.h change.

We’ll now introduce the header edit. To clearly detect freshness, we adjust file timestamps deterministically rather than using sleep. We set all source/header files to an old baseline time T, then set the object and executable to T+10s, then set limits.h (after editing it) to T+20s. For example (using GNU touch):

# Set main.c, config.h, limits.h to 2026-01-01 00:00:00 UTC
touch -d "2026-01-01 00:00:00" main.c config.h limits.h

# Build once (again) so main.o and app get newer timestamps
make
# Now set build outputs to 2026-01-01 00:00:10
touch -d "2026-01-01 00:00:10" build/main.o build/app

# Edit only limits.h to define 9 and set timestamp to 2026-01-01 00:00:20
printf "#define LIMIT 9\n" > limits.h
touch -d "2026-01-01 00:00:20" limits.h

# Verify mtimes:
stat -c '%n %y' main.c config.h limits.h build/main.o build/app

A sample stat output might be:

main.c       2026-01-01 00:00:00.000000000 +0000
config.h     2026-01-01 00:00:00.000000000 +0000
limits.h     2026-01-01 00:00:20.000000000 +0000
build/main.o 2026-01-01 00:00:10.000000000 +0000
build/app    2026-01-01 00:00:10.000000000 +0000

This shows limits.h is now strictly newer than build/main.o (and the executable). We have established the intended ordering. If any commands reverted or a system clock changed, we would stop the test. Here it’s correct: limits.h (0:00:20) > main.o (0:00:10). We are ready to run make again in this state.

Observe a successful command serving old behavior

With the header edited, we run make on the unchanged Makefile (no added dependencies):

make
./build/app

The make output shows no rebuild of main.o (because main.o’s only prerequisite is main.c, which is older) and the link step might run (because it depends on main.o which wasn’t changed). In effect, main.o is reused, build/app is relinked (or reused). The executable prints:

7

Even though we changed limits.h to yield 9, the incremental build still prints 7. Crucially, make exited 0 and said nothing was out-of-date. This is not acceptable. The tool succeeded, but the output is stale.

For comparison, do a clean compile ignoring Make (or in a fresh directory):

gcc main.c -o clean_app && ./clean_app

This produces the correct 9. That is our ground truth for the new source contents. The incremental build’s output 7 is wrong. The evidence table for Case A (missing header prerequisites) is:

•   Declared graph: main.o depends only on main.c (and order-only build/).

•   Make invocation: make

•   Compile ran? No (no new compile of main.o)

•   Link ran? Possibly yes (relinked with old main.o)

•   Source hashes: main.c/content, config.h, limits.h (changed)

•   Object hash: from before (old main.o)

•   Depfile: none

•   Goal: default (all)

•   Incremental output: 7 (stale)

•   Clean reference output: 9

•   Decision: REJECT/REPAIR (the binary is stale).

Because the result changed only after the missing header input was edited, and make failed to rebuild, this build is not current. A fix is needed. The next step is to ensure the Makefile reflects all relevant headers.

Test normal and order-only header prerequisites

We now test two fixes: first making the headers normal prerequisites, second (incorrectly) marking them order-only.

Case D: Explicit normal prerequisites: We modify the rule for build/main.o to list both headers on the left of the pipe, e.g.:

build/main.o: main.c config.h limits.h | build

This declares config.h and limits.h as normal prerequisites. The Makefile is now:

build/main.o: main.c config.h limits.h | build
  gcc -c main.c -o $@

We redo from the edited state (i.e. with limits.h timestamp still newer):

rm -f build/main.o build/app
make
./build/app

Now Make sees that limits.h (and config.h) is newer than build/main.o, so it recompiles main.o and relinks build/app. The program output is 9. The incremental and clean outputs match. The normal prerequisites fixed the issue. We would ACCEPT this build (the artifact is now current).

Case B: Headers as order-only prerequisites: Alternatively, suppose we mistakenly wrote:

build/main.o: main.c | config.h limits.h build

That is, we put config.h limits.h after the pipe, making them order-only. In this scenario, the rule is:

build/main.o: main.c | config.h limits.h build
  gcc -c main.c -o $@

We again start from scratch with limits.h newer and run:

rm -f build/main.o build/app
make
./build/app

Make enforces order (it will ensure the headers exist before compiling), but it does not treat them as dependencies. So main.o is not rebuilt even though those headers changed. The output is still 7. In table form:

•   Order-only prereq: config.h, limits.h (on right of |)

•   Incremental output: 7 (stale, same as Case A)

•   Decision: REPAIR (order-only does not solve invalidation).

This illustrates that a pipe ‘|’ means “build-order only,” not content dependency. A directory is often order-only (as above with build/), but headers must be normal prerequisites if changing them should trigger rebuilds. In summary, making headers order-only still failed to rebuild; making them normal succeeded. The order-only case (B) yields the same stale result as missing them entirely (A).

A directory is not a content dependency: Note how build/ was correctly order-only to avoid rebuilds on directory changes. By contrast, config.h and limits.h are content dependencies. They belong on the left side of : (normal prerequisites). The pipe symbol should not be used for headers unless the intent is purely ordering (rare for headers). In general, use order-only prerequisites only for things like ensuring directories or special targets exist, not for actual source files.

Generate a depfile without mistaking it for an active rule

To automate tracking header dependencies, many projects use GCC’s -MMD -MP -MF -MT flags. We test Case C: we let the compiler generate a dependency file but do not include it in Make.

Using the original rule (main.c normal, build directory order-only), run:

rm -rf build
make
# Generate a .d dependency file as a side effect
gcc -MMD -MP -MF build/main.d -MT build/main.o -c main.c -o build/main.o

Here, -MMD tells GCC to write user-header dependencies to build/main.d (omitting system headers). The -MP option adds a phony rule for each header (to avoid errors if later removed). The -MT build/main.o ensures the target in the .d file is build/main.o (not just main.o), matching our build path.

Inspect build/main.d:

cat build/main.d

It contains lines like:

build/main.o: main.c config.h limits.h
build/main.d: config.h limits.h

This shows GCC discovered both headers (config.h, limits.h) transitively. However, because we have not added -include build/main.d to the Makefile yet, Make never reads build/main.d. The .d file sitting on disk does nothing by itself. We then run the build:

make
./build/app

The result remains stale (7). The reason is simply that Make’s graph was unchanged. The mere presence of a .d file isn’t enough; it must be explicitly included in the makefile to affect the build. We have evidence both of discovery and of non-participation: the .d file lists the correct headers, but since it wasn’t loaded, the incremental build still didn’t recompile.

Compiler dependency flags in brief:

•   -MMD (or -MD) tells gcc to output dependencies. -MMD omits system headers.

•   -MF file writes them to file (instead of stdout).

•   -MT target sets the rule’s target name (e.g. build/main.o).

•   -MP adds phony dummy targets for each header (so removing a header won’t crash make).

None of these flags magically fix the Make graph on their own. They simply generate the data. You must still -include the .d file in the makefile so make sees the edges. Until then, Case C’s outcome is the same as before: stale output, build succeeded.

Include the generated dependencies and retest incrementally

For Case E we fix the Makefile to include the dependency file. First, revert to the intended compilation rule (with dependency flags) and add an -include directive. For example:

.DEFAULT_GOAL := all
.PHONY: all
all: build/app

build/app: build/main.o
  gcc $< -o $@

build/main.o: main.c | build
  gcc -MMD -MP -MF build/main.d -MT build/main.o -c main.c -o $@

build:
  mkdir -p $@

# Include the .d file (ignore if missing)
-include build/main.d

We now rerun from a clean state:

rm -rf build
make

In this run, the compiler first creates build/main.o and build/main.d. Then make processes the -include build/main.d. Now config.h and limits.h appear in Make’s graph as normal prerequisites of build/main.o. Since limits.h is newer, Make rebuilds main.o (compiling), and then relinks build/app. The final output is 9, as desired.

The make log will show a compile step for main.c, followed by linking. Neither step is aborted or silent. The outcome matches the clean build. We should note which recipes ran:

•   The compile recipe (gcc -c main.c) ran (because main.o was out-of-date).

•   The link recipe (gcc $< -o build/app) ran with the newly built object.

We see: incremental output 9. This fixes the problem.

Caution on -include: The -include (or sinclude) directive tells Make to include the given file, but not to error if it’s missing. We rely on it being non-fatal: if build/main.d did not exist (say on first build), make won’t stop. However, note that the manual recommends placing such include lines after the first default goal, to avoid changing what Make considers the default target. In our simple Makefile the default is all defined first, so it’s safe.

A depfile must name the actual object target

When generating a .d, ensure the target in it exactly matches the object’s path. That is why we used -MT build/main.o. Without -MT, gcc’s default would emit “main.o: ...headers...”. If the Makefile rule is for build/main.o, they wouldn’t match, and Make would ignore that rule. By using -MT build/main.o, the .d file says:

build/main.o: main.c config.h limits.h

So make knows build/main.o depends on those headers. In general, always align -MT with the object path used by the make rule.

Handle an existing object whose depfile disappeared

Case F considers the scenario where, after a successful incremental build (with .d generation and inclusion), the .d file is lost but the object and executable remain cached. We simulate:

rm build/main.d   # delete the depfile only
make
./build/app

With -include build/main.d in the Makefile, GNU Make will try to include it but silently ignore its absence (because of the ‘-’). The existing build/main.o is still there and newer than sources, so make again thinks everything is up-to-date. The build completes with no errors, and the output is stale 7 again. We have no new dependency info (since .d is missing) but our cache fooled make.

This situation shows an important nuance: just using dependency files is not bulletproof unless you also monitor metadata. In our side-effect design, the .d is created at the same time as main.o and is meant to be always paired. If the pair is broken (object exists without its depfile), the Makefile’s “include” will happily skip it. The result is the same stale output as before.

For this policy, we must declare a build decision: we cannot accept an artifact built this way, because we lack proof that it covers the latest headers. In practice, we treat “missing required metadata” as a build error. If a .d is missing for an object governed by this dependency-generation convention, the object should be invalidated or the dependency list regenerated. A safe approach is to HOLD the build: flag it for review or force a clean rebuild. If we were rewriting make rules, one could add an explicit dependency so that missing .d forces a rebuild, but by default -include hides it.

In summary, Case F is not acceptable: our pipeline should detect “existing object with missing .d” and prevent release. We add this to the decision matrix below.

Compare clean and incremental evidence without overclaiming

We now summarize behavior across all cases. A quick table of results (outputs only) for reference:

From this, we see that only scenarios D and E produce current binaries (9), while A, B, C, F do not. In each failing case, the executable still prints 7 despite editing the header. We treat 9 as the expected behavior.

Hashes vs behavior: One might be tempted to compare executable hashes, but that can be misleading (build paths, timestamps, or debug info often differ between runs). Instead, we rely on runtime behavior as the oracle: equal outputs (9) on this fixture confirm correctness. In a real project, a functional test (or diff of output) would be the acceptance criterion, not matching binaries bit-for-bit.

We enforced the timestamp ordering to control the experiment, but in general if an incremental build yields the same runtime effect as a clean build after the same edits, that is necessary evidence of correctness here. It isn’t sufficient proof of covering every code path or environment difference, but it is required. In practice, one extends testing by checking other inputs (compiler flags, env vars, generated headers, etc.) explicitly, rather than assuming perfect caching.

Bound what this dependency repair does not track

Our focus was strictly on user-header dependencies in one .c file. We should acknowledge limitations. This method does not catch changes to system headers (those aren’t listed by -MMD), compiler flags, or environment variables. For example, if a compiler option or included-from-system change affects the binary, GCC’s -MMD won’t list that and Make wouldn’t rebuild. Also, generated headers (created by build scripts) require their own rules. We assume here that any such generated file is either treated as a normal source or has its own dependency logic.

We also did not test parallel builds or distributed caches. In a real CI environment, remote caches or make -j could expose other timing issues, but the core lesson remains: the dependency graph must be complete. If any input is external to this simple graph (e.g., system /usr/include), additional contract checks would be needed.

In short: this exercise shows how to fix one particular bug. It does not promise that using -MMD makes a build fully hermetic. You would still need to audit any other compiler option changes, library versions, or environment differences separately. The GNU Make auto-dependency flags solve one piece of cache correctness: tracking user headers. They do not, for example, catch the case “gcc -Iflags changed.” That is out of scope here.

Turn missing metadata into a reviewable build decision

Based on our experiments, we define a release gate: categorize the outcomes into one of four actions for the build artifact. We assume logs recorded each compile/link event and file evidence.

•   ACCEPT (Verified current binary): If the build graph has all required edges (like cases D or E), and the incremental binary’s output matches the independent clean build, then the artifact can be accepted. (Decision: proceed to release.)

•   REPAIR (Fix the dependency graph): If the output is stale but the fix is straightforward (missing a header edge or include), we REPAIR the Makefile and re-test. This happened in A, B, C. The build should be marked red until the graph is fixed, but no need to discard history; just patch and re-run.

•   CLEAN-REBUILD and RETEST (Containment): If the graph fix is non-trivial or if automated metadata generation is heavily relied on, one might choose to wipe outputs and rebuild entirely, verifying the graph first. In practice, after repairing the Makefile, you’d clean and rebuild to ensure no cached object remains. This ensures no stale leftover. After that, rerun the header-change test to prove the fix.

•   HOLD (Unproven artifact): If metadata is missing (like case F), we do not blindly trust the binary. The build is flagged for manual review or blocked. The specific decision is: do not accept an object when its required .d file is gone. (We don’t apply this to the “no .d system at all” case, only to cases where using a side-effect .d means an orphan object.) Until a clean rebuild regenerates the .d or we manually verify, the artifact is on hold.

Thus, for each test variant we enforce: if any expected header change did not trigger a rebuild, we treat the build as broken until proven correct. We log exactly which targets ran and which prerequisites were listed. If a .d is missing (case F) we fail the build under our rules. Even though plain make didn't error, our pipeline detects “required metadata missing” and marks failure. This makes the stale-case explicit.

Do not accept an object with missing required metadata: Our chosen policy was that objects built under the side-effect .d scheme must have their .d. If main.o exists without main.d, we treat that object as needing invalidation. The rule is not “all builds with -include must fail if a .d is missing” (that would be too broad). It’s only for the design where the .d is supposed to accompany the object. In short, if using automatic depfiles, a missing depfile means “graph is incomplete” and we hold that build.

We keep artifacts and logs from each scenario so we can audit them. Crucially, we do not delete the evidence before making the decision. An empty build (no logs) is not success; it’s an error to have nothing to inspect. Keeping a trace of what make did and what file states were is part of our acceptance criteria.

Repair and release with explicit ownership

When a stale build is detected, who fixes it? We establish roles: the build owner (the engineer maintaining the Makefile) is responsible for repairing the graph. The release manager then verifies the fix by re-running the header-change test. We summarize the four outcomes:

•   ACCEPT: Owner: anyone (build process is correct). Evidence: Clean and incremental outputs match; Make rebuilt the needed targets. Next step: Release artifact.

•   REPAIR: Owner: build maintainer. Evidence needed: Logs or diff showing which header was missing from Makefile. After fix, re-run test to produce 9. Next step: fix Makefile and mark issue resolved before release.

•   CLEAN-REBUILD: Owner: build or release engineer. Evidence needed: Confirmation that a fix (or precaution) was applied (e.g. delete outputs and rebuild). Typically used if troubleshooting. Next step: Perform make clean then make all after fix, then rerun tests.

•   HOLD: Owner: build maintainer. Evidence needed: Log showing an object without its .d. The artifact is not clearly wrong (pipeline saw green), but we suspect it. We hold it and do not ship. Next step: regenerate metadata (e.g. touch source or force depfile regen) or clean rebuild, then rerun tests.

For any held build, we require a new test run after the artifact is fixed. We identify which parts of the build were cached. For example, in case F, the artifact build/app was built before the header change; that must be annotated. The release is paused until a proven build (either a successful incremental with deps or a clean rebuild) can be produced.

Finally, we recommend updating the build logs or issue tracker with the fix. For example, “Added missing headers to Makefile dependencies. Binaries rebuilt and output verified.” Once the fix is validated (output=9 on incremental test), the release can proceed. Keeping the change minimal (just adding deps) avoids unnecessary risk; a full tool upgrade is not needed here.

Strengthen delivery fundamentals through practical training

Catching this kind of bug is as much about team practice as tools. A green build light doesn’t guarantee correctness: the pipeline must embed sanity checks like we’ve used here. Teaching engineers about Make’s dependency model and the meaning of order-only vs normal prerequisites is essential. For a broader foundation covering Linux automation, scripting, and CI/CD best practices (including build sanity checks like this), consider structured training. Refonte Learning’s DevOps Engineer Program offers an industry-aligned curriculum in Linux, automation, Git/GitHub, CI/CD, containers, and more.

By tightening the feedback loop (e.g. making missing depfiles fail builds) and by verifying behavior against a clean build, a team can distinguish mere tool success from true correctness. In our experiment, every fix involved explicitly owning the headers as prerequisites: either by hand (Case D) or via GCC’s depfiles with -include (Case E). Any missing step was caught by comparing the output. That discipline (test every input change, audit the dependency graph) is a key skill in DevOps engineering. It ensures that a green CI pipeline truly means “all inputs accounted for.”

For a broader foundation in Linux, automation and CI/CD, explore Refonte Learning’s DevOps Engineer Program.