Jake McCrary

A more helpful makefile

In an older article of mine I extolled the virtues of having unified interfaces for interacting with your projects. I recently started working at Coinbase and the group I’m working with is mostly using makefiles as that common interface. We still have some more work to do to unify the makefile targets of the various projects but I’ve picked up one tip that makes switching between projects easier.

That tip is to have the default target of your makefile be one that prints out a helpful message. This looks like the following.

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

There is a lot going on there but it basically looks through your makefile targets and finds the ones that have a comment starting with ## after the target dependencies. Those targets are printed to the console along with the comment.

As an example, the makefile for my website looks similar to the below file.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
.PHONY: help
help:
  @grep -E '^[0-9a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
   sort | \
   awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

.PHONY: watch
watch: ## Watch for changes and serve preview of site with drafts
  bundle exec rake clean
  bundle exec rake preview

.PHONY: develop
develop: ## Serve a preview of the site without drafts and refresh changes
  bundle exec rake clean
  bundle exec rake develop

.PHONY: new_adventure
new_adventure: ## Start a new adventure post
  bundle exec rake new_adventure

.PHONY: new_post
new_post: ## Start a new post
  bundle exec rake new_post 

.PHONY: deploy
deploy: ## deploy
  ./deploy.sh

When this file, when I run make in this websites source, I get the following output.

1
2
3
4
5
6
7
0 [last: 0s] 21:11:50 ~/src/jakemcc/blog (master)
$ make
deploy                         deploy
develop                        Serve a preview of the site without drafts and refresh changes
new_adventure                  Start a new adventure post
new_post                       Start a new post
watch                          Watch for changes and serve preview of site with drafts

This is super useful when you’re starting doing work in a new project. With this feature you can get a quick list of useful targets and a description. It allows you to quickly see what can be done in a project.

Comments