dwmkerr/makefile-development

Makefile Development

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.