makefile

When to Use

• Creating a new Makefile for any project (C/C++, Go, Node.js, etc.)
• Reviewing or refactoring existing makefiles for correctness and maintainability
• Debugging build failures related to make rules, prerequisites, or variables
• Setting up build automation with GNU Make (pattern rules, automatic dependencies, parallel builds)
• Ensuring portability across platforms or compliance with GNU Make conventions

Critical Patterns

• Tabs, Not Spaces: Every recipe line MUST start with a tab character. Spaces will cause a syntax error.
• Declare .PHONY: Always mark non-file targets (e.g., clean, all, test, install) with .PHONY to avoid conflicts with files of the same name.
• Use := Over = When Possible: Prefer simple expansion (:=) for variables to avoid unexpected recursive expansion and improve performance.
• Automatic Variables: Use $@ (target), $< (first prerequisite), $^ (all prerequisites), $? (newer prerequisites), and $* (stem) in recipes to keep rules generic and reusable.
• Use $(wildcard ...) Not $(shell ls ...): Never shell out for file lists; use Make's built-in $(wildcard *.c) function instead.
• Auto-Generate Dependencies: Use compiler flags like -MMD -MP to generate .d files rather than maintaining header dependencies manually.
• Clean Target: Always provide a clean target and prefix destructive commands with - to ignore errors if files don't exist.
• Variables First, Rules Second: Define all variables at the top, followed by the default goal, then build rules, then phony targets.
• Avoid Recursive Make: Don't use $(MAKE) -C subdir unless absolutely necessary; prefer includes or non-recursive approaches.

File Structure

# -------------------------------------------------------
# Project: <name>
#
# Usage:
#   make          - Build the project
#   make clean    - Remove generated files
#   make install  - Install to $(PREFIX)
#   make test     - Run tests
#
# Variables:
#   CC       - C compiler (default: gcc)
#   PREFIX   - Installation prefix (default: /usr/local)
# -------------------------------------------------------

# --- Variables ---
CC       ?= gcc
CFLAGS   := -Wall -Wextra -O2
PREFIX   ?= /usr/local

sources  := $(wildcard src/*.c)
objects  := $(sources:.c=.o)
deps     := $(objects:.o=.d)

# --- Default Goal ---
all: program

# --- Build Rules ---
program: $(objects)
	$(CC) -o $@ $^ $(LDFLAGS)

%.o: %.c
	$(CC) $(CFLAGS) -MMD -MP -c $< -o $@

-include $(deps)

# --- Phony Targets ---
.PHONY: all clean install test

clean:
	-rm -f program $(objects) $(deps)

install: program
	install -d $(PREFIX)/bin
	install -m 755 program $(PREFIX)/bin

test: program
	./run-tests.sh