Makefile with help message

The Makefile

The idea is pretty simple: Add comment to each target from Makefile
Here is the clean target from makefile:

clean:
    rm -f *.o

Help message here is redundant but in sake of completeness let's add it:

clean: ## Clean directory
    rm -f *.o

Now we need filter out all docstrings: here is the command for that:

ag '^[a-zA-Z_-]+:.*?## .*$$' --nofilename Makefile \
| sort \
| awk 'BEGIN{FS=": ## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

Here I'm using silver-searcher aka ag.
Seems complicated, yeah? So what does that command do?

• filters out lines basing on this regular expression: '^[a-zA-Z_-]+:.*?## .*$$', namely any string like "target_name: ##doc string".
• sorts output with command sort
• formats output with awk command BEGIN{FS=": ## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}

Let's look at that command. What do we have?

• BEGIN{FS=": ## "}

• {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}

  From the documentation: A BEGIN rule is executed once only, before the first input record is read. So it simply reads input and sets the Field separator to ": ##" to split input on two parts: before and after the FS.

  Second part just prints filtered output with formatting and colors.

One more thing -- we have to define default target to be executed when make command launched without arguments:
.DEFAULT_GOAL := help
Now we are ready.

Here is what we have as a result:

	CFLAGS=-Wall -g
	clean: ## Clean directory
	rm -f *.o
	help: ## Help target
	@ag '^[a-zA-Z_-]+:.*?## .*$$' --nofilename $(MAKEFILE_LIST) \
	| sort \
	| awk 'BEGIN{FS=": ## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
	.DEFAULT_GOAL := help

view raw Makefile hosted with ❤ by GitHub

Save that gist into Makefile and run make command in your terminal from the folder with Makefile. If everything is ok you will get formatted and colored output: all targets defined in Makefile:

$ make
clean                          Clean directory
help                           Help target

Dependencies

But aware that awk and silver-searcher are required for that snippet to work.
(Btw, ag could be replaced with grep, if needed with some modifications I guess.)

And remember -- documentation's important!

Comments

[Xun Zhou]

you are also able to extend the help: declaration to group the task with a defined title. See the example on dev.to/vikbert/best-practice-makef...

[Adam Brandizzi]

Nice trick :D