A short note on Makefile hygiene

2025-11-04

Makefiles rot faster than the code they build, mostly because nobody reviews them with the same care. Four habits have kept mine readable longer than they deserved.

Declare your phonies

Every target that is not a file goes in .PHONY. Skipping this works right up until somebody creates a directory called test and the test target silently stops running. That is a genuinely miserable afternoon.

.PHONY: all test clean install

One recipe, one job

If a recipe has more than about five lines, it wants to be a script in ./scripts/ that the recipe calls. Shell inside make is shell with a second layer of quoting rules on top, and you will get the escaping wrong eventually.

Use := unless you mean =

Recursive assignment re-evaluates every time the variable is referenced. If the right hand side shells out, you have just made a command run an unpredictable number of times. This is the single most common source of mysteriously slow builds I have run into.

Make the default target harmless

The first target in the file is what a bare make runs. Make it either the ordinary build or a help message. Never make it something that deploys.