Makefile Help View article history Edit article

Published: , Updated:
Talks about: <a class="post-tag post-tag-help" href="/tags/help">help</a>, <a class="post-tag post-tag-make" href="/tags/make">make</a>, <a class="post-tag post-tag-makefile" href="/tags/makefile">Makefile</a>, and <a class="post-tag post-tag-perl" href="/tags/perl">perl</a>

Use the following Perl snippet to automatically generate help output for your Makefile:

GREEN  := $(shell tput -Txterm setaf 2)
WHITE  := $(shell tput -Txterm setaf 7)
YELLOW := $(shell tput -Txterm setaf 3)
RESET  := $(shell tput -Txterm sgr0)

HELP_FUN = \
    %help; \
    while(<>) { push @{$$help{$$2 // 'targets'}}, [$$1, $$3] if /^([a-zA-Z\-]+)\s*:.*\#\#(?:@([a-zA-Z\-]+))?\s(.*)$$/ }; \
    print "usage: make [target]\n\n"; \
    for (sort keys %help) { \
    print "${WHITE}$$_:${RESET}\n"; \
    for (@{$$help{$$_}}) { \
    $$sep = " " x (32 - length $$_->[0]); \
    print "  ${YELLOW}$$_->[0]${RESET}$$sep${GREEN}$$_->[1]${RESET}\n"; \
    }; \
    print "\n"; }

To use HELP_FUN, add the following help target to the same Makefile:

.DEFAULT_GOAL := help

.PHONY: help
help: ##@other Show this help
	@perl -e '$(HELP_FUN)' $(MAKEFILE_LIST)

Each target in the Makefile is marked as phony to signal that those targets are not actually files that are generated as part of your build process. The optional description of a target can be placed after the ##@ prefix. The first word represents the group of a target and everything that follows is the description of a target. All targets should be formatted just like the help target:

.PHONY: compile
compile: ##@hacking Compile your code
	<compile some code>

.PHONY: test
test: ##@hacking Test your code
	<test some code>

.PHONY: sign-cla
sign-cla: ##@contrib Sign the contributor license agreement
	<sign some file>

Once in place, you can either use make without any argument to call the help target or use make help to see the generated output:

$ make
usage: make [target]

contrib:
  sign-cla            Sign the contributor license agreement

hacking:
  compile             Compile your code
  test                Test your code

other:
  help                Show this help