Makefile Usability

I have started using makefiles quite extensively in projects that do not have a consistent approach to handling and defining all your project lifecycle steps in one place. One thing that I found lacking in this approach was nice usability output when running the default make command. In fact the behaviour of make is to run the first target defined in a makefile unless you explicitly specify a default target using the .DEFAULT_GOAL := your_goal attribute.

This is awesome but now how do I easily describe what each target does other than having a huge echo block in my help target? I found this post which provides an excellent solution. You basically comment next to each target that you want usability output for using ##:

bootstrap: ## Installs the base components needed by this project

You then change your help target as specified in the blog post mentioned earlier:

help:
  @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

When running make or make help the above example would output:

bootstrap    Installs the base components needed by this project

This approach is excellent as anyone new to your project can simply get the code and run make. This helps get them up to speed faster in terms of how to run the various lifecycle phases. It is also awesome as you add these annotations right next to each target so that anyone reading your makefile also sees it where they would expect to see the comment.