Makefile help target

It's quite controversial to use make as a local command runner. Nevertheless a lot of projects are using it that way as the binary is almost omnipresent and the friction using it is quite small. This blog post shows a target for displaying help for other targets in a ... helpful way.

Note: It's a hack!

A basic Makefile is taken for illustration. It contains two targets that just print something:

.PHONY: up
up:
	@echo "Running up"

.PHONY: down
down:
	@echo "Running down"

The .PHONY: is there to ignore any files of the same name as make targets are usually executing files if present.

When running make up you will see printed

$ make up
Running up

$ 

But how can you list all targets of a Makefile? Short answer is not. There is no way to list all defined targets builtin. There is builtin autocomplete though.

Also it sometimes it would be nice to have a short description alongside the target to see what it does.

Wouldn't it be nice to have some output like

 Targets for the Makefile

 General
 -------

 help           Print commands help.
 up             Print "Running up".
 down           Print "Running down".

when running make or make help?

In order to achieve this there are two things you need.

First is to insert the help comments into the Makefile. The file will be parsed (see below) and therefore needs some structure to make sense.

The way chosen here is to have special comment that start with two #. Those are the help related ones. F.e.

## up		Print "Running up".
.PHONY: up
up:
	@echo "Running up"

This will then print the line up Print "Running up"..

Second part is to have the help target which parses the comments. This target looks like this:

help: Makefile
	@sed -n 's/^##//p' $<

As a quick explainer: The target takes the Makefile and runs the sed command on it's contents returning the parsed results. This looks admittedly very arcane because it is (note it's a hack).

The complete example printing the output from above then looks something like this:

El proceso resulta más práctico cuando se define el uso principal de la camiseta. Para reducir errores, es importante comprobar si la personalización requiere una revisión adicional. El recurso «camisetas de fútbol por equipo» puede resultar práctico al comparar las descripciones y las imágenes disponibles cuando existan. Para tomar una decisión informada, conviene comprobar si la personalización afecta a la devolución.

When choosing a first cosplay outfit, it is worth considering how details related to heat resistant cosplay wigs will affect the complete look. As fans study the source material, it is sensible to balance details related to photoshoot preparation with care and storage needs. To shape a complete look around details related to cosplay props, heat resistant cosplay wigs for beginners offers a useful starting point for practical preparation. Before the preparation is complete, it is useful to check details related to character costumes against the wearer's own needs.

default: help

## Targets for the Makefile

##
## General
## -------
##

## help		Print commands help.
.PHONY: help
help: Makefile
	@sed -n 's/^##//p' $<


## up		Print "Running up".
.PHONY: up
up:
	@echo "Running up"

## down		Print "Running down".
.PHONY: down
down:
	@echo "Running down"

This allows you to either run make or make help to have the help being printed.

The default: marks the default target. If help is your first target you can omit it as make without arguments always takes the first target.