Opscraft
Makefile · Lesson 4 of 7 · 4 min read

How recipes execute

One shell per line

Each recipe line runs in its own shell process. State doesn't carry between lines:

bad:
    cd app
    npm test            # runs in the ORIGINAL directory — cd was lost

good:
    cd app && npm ci && npm test

also-good:
    cd app; \
    npm ci; \
    npm test             # backslash-continued: one shell

Or make every recipe a single shell with .ONESHELL: (all lines of a recipe go to one shell — then add set -e behaviour via .SHELLFLAGS).

Enlarge diagramBAD: TWO SHELLSGOOD: ONE SHELLshell 1: cd appshell 2: npm test (wrong folder)shell 1cd app && npm ci && npm test
Figure 1. Each recipe line runs in a new shell, so cd on one line is forgotten by the next.
Swipe sideways to see all of it, or tap to open it full screen.

Shell and error behaviour

  • Default shell is /bin/sh (dash on Ubuntu — no bash-isms like [[ ]] or arrays). Set SHELL := bash and .SHELLFLAGS := -eu -o pipefail -c for safer recipes.
  • make stops at the first recipe line that exits non-zero ("Error 1"). But within one line like cmd1; cmd2, a failure of cmd1 is hidden unless the shell has -e — another reason for .SHELLFLAGS.
  • .DELETE_ON_ERROR: deletes a half-written target file if its recipe fails, so a corrupt artifact isn't treated as up to date next time.

Prefixes

Prefix Effect
@ Don't echo the command before running it
- Ignore errors from this line
+ Run even under make -n (used for $(MAKE) calls)

$ in recipes

Make expands $... before the shell sees it. To pass a literal $ to the shell, double it:

list:
    @for f in charts/*; do echo "linting $$f"; helm lint $$f; done
    @echo "home is $$HOME, app is $(APP)"

$(APP) is a make variable; $$f and $$HOME reach the shell as $f and $HOME.

Recursive make

SERVICES := orders payments catalog
.PHONY: test-all $(SERVICES)
test-all: $(SERVICES)
$(SERVICES):
    $(MAKE) -C services/$@ test

Always use $(MAKE), not make: it passes flags like -j, -n, -k and the jobserver to the sub-make. --no-print-directory (or MAKEFLAGS += --no-print-directory) silences "Entering directory" noise.

Enlarge diagrammake test-all -j4root Makefile$(MAKE) -C services/orderstest$(MAKE) -C services/paymentstest$(MAKE) -C services/catalogtestin parallel
Figure 2. Recursive make across a monorepo. $(MAKE) passes -j and other flags down so the whole tree shares one job limit.
Swipe sideways to see all of it, or tap to open it full screen.

Parallel builds

make -j8 runs independent targets concurrently. If a build works serially but fails in parallel, a dependency is missing — two targets need an order that you never declared (for example, docker-build assumes generate ran first but doesn't list it). Fix by declaring the prerequisite, or mark a file .NOTPARALLEL: as a last resort.

Enlarge diagramrelease: docker-build docker-pushdocker-push: docker-build-j runs both at oncepush starts before the image existsWorks serially by accidentThe order is declaredSafe with any -jmake -j is now a free speed-up
Figure 3. Parallel make exposes missing dependencies. docker-push really needs docker-build first; serial runs hid that by luck of ordering.
Swipe sideways to see all of it, or tap to open it full screen.

include

include common.mk                # shared targets/variables across repos
-include .env                    # optional include (no error if missing) — loads KEY=VALUE lines as make vars

Teams sometimes vendor a shared common.mk from a platform repo so every service gets the same help, lint, docker-* targets.