makefile

Files (1)

• SKILL.md

SKILL.md (first lines)

## 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

```makefile
# -------------------------------------------------------
# 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
```

## Code Examples

### Variables and Substitution

```makefile
# Simple expansion (evaluates immediately) - PREFERRED
CC := gcc

# Recursive expansion (evaluates when used)
CFLAGS = -Wall $(EXTRA_FLAGS)

# Conditional assignment (set default, allow override)
PREFIX ?= /usr/local

# Append to variable
CFLAGS += -g

# Always reference with $() - not bare $VAR
objects := $(sources:.c=.o)
```

### Pattern Rules and Implicit Rules

```makefile
# Custom pattern rule for generic transformations
%.pdf: %.md
	pandoc $< -o $@

# Compile with auto-dependency generation
%.o: %.c
	$(CC) $(CFLAGS) -MMD -MP -c $< -o $@
```

### Order-Only Prerequisites

```makefile
# The directory is created before compiling but does NOT
# trigger recompilation when its timestamp changes.

From dallay/agents-skills, MIT.

More from dallay/agents-skills