make as a task runner: phony targets, tabs and one shell per line

What it is

make rebuilds a target from its prerequisites by running a recipe when the target is missing or older than what it depends on. Used as a task runner, most targets are not files but names for commands: make test, make lint, make deploy. The GNU make manual calls these phony targets and says to declare them as prerequisites of the special target .PHONY, so the recipe runs even if a file of that name exists. Two documented syntax rules cause most first-time errors: each recipe line must start with a tab (unless .RECIPEPREFIX is changed), and each recipe line is executed in a new sub-shell, so a cd or a shell variable on one line does not affect the next unless the lines are joined into one logical line with && and backslashes, or the .ONESHELL special target is declared.

Why it matters

A Makefile gives newcomers and agents one discoverable place for a project's commands, needs no language-specific runner, and can express genuine dependencies (generate code before compiling) that a flat list of scripts cannot. Misreading the two rules above yields "missing separator" errors and recipes that silently run in the wrong directory.

How to apply

• Make the default harmless: the manual states that the first target is the default goal unless .DEFAULT_GOAL is set, so put help first or set .DEFAULT_GOAL := help.
• Declare every command target in one .PHONY: line near the top.
• Join dependent shell steps: cd build && cmake .. && $(MAKE); the manual's example uses && so that a failing cd stops the line. Use $(MAKE) for recursion.
• Offer overridable defaults: PYTHON ?= python3, invoked as make test PYTHON=python3.12.
• Keep real file targets real, with prerequisites, so unchanged work is skipped; keep phony targets phony so they always run.
• Use make -n to print recipes without executing them and make -j for independent targets.

Pitfalls

Spaces instead of a tab. $VAR in a recipe is expanded by make as $V followed by AR; write $$VAR for the shell variable. A phony target with the same name as an existing directory that was not declared .PHONY is "up to date" and never runs. Lines silenced with @ hide the failing command. Recipes that rely on bash features run under /bin/sh unless SHELL := bash is set. Parallel runs expose missing dependencies between targets that happened to work in sequence.