Create Makefiles following consistent conventions.
Template
default: help
.PHONY: help
help: # Show help for each of the Makefile recipes.
@grep -E '^[a-zA-Z0-9 -]+:.*#' Makefile | sort | while read -r l; do printf "\033[1;32m$$(echo $$l | cut -f 1 -d':')\033[00m:$$(echo $$l | cut -f 2- -d'#')\n"; done
.PHONY: init
init: # Initialise the development environment.
./scripts/init.sh
Conventions
| Element | Convention |
|---|---|
| Filename | Makefile (capitalised, no extension) |
| Default target | default: help as the first line |
.PHONY |
Declare directly above each target |
| Help comments | Single # on the target line: target: # Description. |
| Target names | Lowercase, hyphen-separated (test-e2e, type-check) |
| Complex logic | Delegate to scripts (./scripts/build.sh) rather than inline |
Help Target
The self-documenting help target parses # comments and prints sorted, colour-coded output:
.PHONY: help
help: # Show help for each of the Makefile recipes.
@grep -E '^[a-zA-Z0-9 -]+:.*#' Makefile | sort | while read -r l; do printf "\033[1;32m$$(echo $$l | cut -f 1 -d':')\033[00m:$$(echo $$l | cut -f 2- -d'#')\n"; done
Every target must have a # Description. comment or it won't appear in help output.
Common Targets
| Target | Purpose |
|---|---|
help |
Show available targets (always present) |
init or setup |
Install dependencies, configure environment |
build |
Compile or bundle artifacts |
dev |
Start local development server |
test |
Run test suite |
lint |
Run linters and formatters |
Important
After creating or modifying Makefiles, remind the user:
Use tabs. Makefile recipes require literal tab characters for indentation, not spaces.