Self-Documenting Help
make help is generated from ## comments on the targets themselves, so the list of commands cannot drift from the real ones.
- Kind
- Convention
- Domain
- Environment & Tooling
- Applies at
scripts/build/- Status
- Stable
- Source
scripts/build/10-help.mk
01 Defines
A convention for documenting make targets in place: a trailing ## description on a target line lists it in make help, and a ##@ Section line starts a group.
02 Applies when
- Targets are spread across many make modules that are added and removed over time.
- The first thing a newcomer runs should show what the repository can do.
03 Boundaries
- Targets without a
##comment are internal and stay out of the listing. - The help module does not know about specific targets or repositories.
Expected behaviour
- 01
helpis the default goal, so a baremakeprints it. - 02Every public target carries a one-line
## descriptionon its rule line. - 03Each module opens its public targets with a
##@ Sectionheading. - 04An optional
HELP_STARTbanner fromrepository.mkis printed first. - 05Sections appear in module load order, because the help reads
MAKEFILE_LIST.
Behaviour#
There is no hand-maintained list of commands. The help target runs awk over
every makefile that make has loaded and picks out two kinds of line: section
headings that start with ##@, and rule lines that end in ## description.
- 01
Annotate
A module writes
doctor: ## Verify required tools ... - 02
Load
Make records every included file in
MAKEFILE_LIST - 03
Scan
awkprints##@lines as headings andtarget: ## textas entries - 04
Print
HELP_STARTbanner, then each section in load order
Because the source of the listing is the makefiles themselves, adding a module adds its section, and deleting one removes it. The help composes the same way the Make Module Registries do, without a registry of its own.
Examples#
.DEFAULT_GOAL := help
.PHONY: help
help: ## List available targets with their descriptions
@if [ -n "$(HELP_START)" ]; then printf '%s\n' "$(HELP_START)"; fi
@awk 'BEGIN { FS = ":.*##" } \
/^##@/ { printf "\n%s\n", substr($$0, 5); next } \
/^[a-zA-Z0-9_.-]+:.*?##/ { printf " %-28s %s\n", $$1, $$2 }' \
$(MAKEFILE_LIST)
@printf '\n'
The beginning of the generated output in this repository:
Start here: make doctor (check tools), make check.hugo (build site), make help (all targets)
help List available targets with their descriptions
Environment
doctor Verify required tools and repository contracts are present
config Show the explicit component configuration from repo config
Repository hygiene
format Rewrite repository files to the canonical format
Connections