Build Tools and Makefiles

A build tool is an executable model of your project. It records which source creates which object, which headers invalidate that object, which flags created an executable, and how tests prove the result. Correct incremental builds are faster than rebuilding everything—and prevent stale-object bugs.

Make is a dependency graph

A rule has a target, prerequisites, and a recipe. If the target is missing or older than any prerequisite, Make runs its recipe. An executable depends on objects; each object depends on its source and every included header. This graph is the durable alternative to a list of commands copied into a terminal.

build/inventory: build/main.o build/inventory.o
⇥$(CC) $^ $(LDLIBS) -o $@

build/main.o: src/main.c include/inventory.h
⇥$(CC) $(CPPFLAGS) $(CFLAGS) -c $< -o $@

$@ is this rule's target, $< is its first prerequisite, and $^ is all prerequisites without duplicates. The visible ⇥ means a literal tab in a real Makefile recipe. A missing-separator error nearly always means the recipe indentation is spaces instead of a tab.

A complete, maintainable starting Makefile

CC       := cc
CPPFLAGS := -Iinclude
CFLAGS   := -std=c17 -Wall -Wextra -Wpedantic -Wconversion -g -O0
BUILD    := build
APP      := $(BUILD)/inventory
SOURCES  := src/main.c src/inventory.c src/parse.c
OBJECTS  := $(SOURCES:src/%.c=$(BUILD)/%.o)
DEPS     := $(OBJECTS:.o=.d)

.PHONY: all debug test clean print-vars
all: debug
debug: $(APP)

$(APP): $(OBJECTS) | $(BUILD)
⇥$(CC) $(OBJECTS) -o $@

$(BUILD)/%.o: src/%.c | $(BUILD)
⇥$(CC) $(CPPFLAGS) $(CFLAGS) -MMD -MP -c $< -o $@

$(BUILD):
⇥mkdir -p $@

-include $(DEPS)

test: $(APP)
⇥./tests/run-tests.sh

clean:
⇥rm -rf build dist

print-vars:
⇥@printf 'APP=%s\nOBJECTS=%s\n' '$(APP)' '$(OBJECTS)'

The pattern substitution maps src/parse.c to build/parse.o. | $(BUILD) is order-only: Make creates the directory, but its timestamp does not make every object stale. Keep generated outputs in build/ and dist/, never beside source files.

Header dependency files keep incremental builds correct

An object embeds code compiled from the headers it saw. If a shared header changes, every source that includes it must recompile. Hand-maintained header prerequisite lists become wrong as modules grow. -MMD asks the compiler to generate a .d file beside each object; -MP makes removed headers less brittle; -include tolerates missing dependency files on the first build.

# Generated build/parse.d
build/parse.o: src/parse.c include/parse.h include/inventory.h
include/parse.h:
include/inventory.h:

# Edit inventory.h. Make must rebuild parse.o, main.o, and any test object
# that includes it, then relink exactly the affected executables.

Debug, sanitizer, and release builds need distinct artifacts

Flags are inputs. A release executable should not quietly link debug objects compiled with another flag set. Use different output directories or an explicit clean boundary. Run tests against every configuration you intend to ship.

# Example policy (extend shared rules rather than copy recipes):
debug: CFLAGS += -g -O0 -fsanitize=address,undefined
debug: BUILD := build/debug

release: CFLAGS := -std=c17 -Wall -Wextra -Wpedantic -O2 -DNDEBUG
release: BUILD := dist/release

# The full project should derive APP and OBJECTS from BUILD for each target,
# then run the same test suite against both configurations.

Assertions may disappear under NDEBUG; required error checks cannot depend on them. Sanitizers are a powerful testing configuration, but their instrumented output is not a release artifact.

Diagnose a build graph deliberately

make -n debug              # inspect recipes safely
make --debug=b debug      # why targets rebuild
make -j4 test              # parallel independent prerequisites
make clean && make test    # diagnostic clean rebuild, not daily workflow

Parallel builds are safe only if every recipe writes its declared target and every generated input is named as a prerequisite. An undeclared shared generated file can race under -j even when it appears to work locally.

Build the application and tests as separate deliverables

A serious project needs more than an application target that launches manually. Give the test binary its own target and link it only with the module objects it needs—not the application's main.o. That makes module tests independent and lets Make rebuild test results when public headers or implementation objects change.

TEST_BUILD := build/tests
TEST_APP   := $(TEST_BUILD)/inventory-test
TEST_SOURCES := tests/inventory_test.c tests/parse_test.c
TEST_OBJECTS := $(TEST_SOURCES:tests/%.c=$(TEST_BUILD)/%.o)
MODULE_OBJECTS := build/inventory.o build/parse.o

$(TEST_APP): $(TEST_OBJECTS) $(MODULE_OBJECTS) | $(TEST_BUILD)
⇥$(CC) $^ -o $@

$(TEST_BUILD)/%.o: tests/%.c | $(TEST_BUILD)
⇥$(CC) $(CPPFLAGS) $(CFLAGS) -MMD -MP -c $< -o $@

$(TEST_BUILD):
⇥mkdir -p $@

test: $(TEST_APP)
⇥$(TEST_APP)

This graph exposes a useful design test: if a module cannot be linked into a test binary without the CLI entry point, separate the module API from command-line presentation. A test target should return non-zero when any assertion fails so Make and continuous integration reliably stop.

Keep each class of compiler flag in the right variable

CPPFLAGS := -Iinclude -D_POSIX_C_SOURCE=200809L
CFLAGS   := -std=c17 -Wall -Wextra -Wpedantic -Wconversion
LDFLAGS  :=
LDLIBS   := -lm

# Link libraries after the objects that reference them.
$(APP): $(OBJECTS)
⇥$(CC) $(LDFLAGS) $^ $(LDLIBS) -o $@

This convention lets a developer or CI override a class of flags without editing your Makefile: make CFLAGS="-O2 -g" release. It also avoids the common error of putting -lm before the object that needs math symbols.

Understand expansion before you build a configuration matrix

:= is a simply expanded variable: its value is computed when Make reads the assignment. = is recursively expanded later, every time it is used. Use := for stable derived paths and lists; use recursive expansion only when you intentionally need late binding.

MODE := debug
BUILD := build/$(MODE)      # build/debug immediately
FLAGS = $(BASE_FLAGS) -O2   # BASE_FLAGS is looked up later
BASE_FLAGS := -Wall

# Use target-specific values carefully: prerequisites can inherit them.
release: MODE := release
release: CFLAGS += -O2 -DNDEBUG
release: $(APP)

For larger projects, avoid mutating the same object path for several modes. A configuration is an input to compilation, therefore its object directory must include the configuration name. If you cannot explain which flags produced build/release/parse.o, the build is not reproducible.

Independent lab: automate the inventory manager

Lesson review

• Rules model targets, prerequisites, and recipes; Make uses timestamps to refresh stale targets.
• Compile each source to an object, then link fresh objects into executables.
• Use automatic variables and pattern rules to avoid duplicated paths and commands.
• Generate .d dependencies for headers and mark actions as .PHONY.
• Keep debug, sanitizer, and release artifacts distinct and test each configuration.
• Use dry runs and Make debug output to repair the graph instead of depending on clean rebuilds.