DEV Community

Cover image for How to create a self-documenting Makefile
Victoria Drake
Victoria Drake

Posted on • Originally published at victoria.dev on

How to create a self-documenting Makefile

My new favorite way to completely underuse a Makefile? Creating personalized, per-project repository workflow command aliases that you can check in.

Can a Makefile improve your DevOps and keep developers happy? How awesome would it be if a new developer working on your project didn’t start out by copying and pasting commands from your README? What if instead of:

pip3 install pipenv
pipenv shell --python 3.8
pipenv install --dev
npm install
pre-commit install --install-hooks
# look up how to install Framework X...
# copy and paste from README...
npm run serve
Enter fullscreen mode Exit fullscreen mode

… you could just type:

make start
Enter fullscreen mode Exit fullscreen mode

…and then start working?

Making a difference

I use make every day to take the tedium out of common development activities like updating programs, installing dependencies, and testing. To do all this with a Makefile (GNU make), we use Makefile rules and recipes. Similar parallels exist for POSIX flavor make, like Target Rules; here’s a great article on POSIX-compatible Makefiles.

Here’s some examples of things we can make easier (sorry):

update: ## Do apt upgrade and autoremove
    sudo apt update && sudo apt upgrade -y
    sudo apt autoremove -y

env:
    pip3 install pipenv
    pipenv shell --python 3.8

install: ## Install or update dependencies
    pipenv install --dev
    npm install
    pre-commit install --install-hooks

serve: ## Run the local development server
    hugo serve --enableGitInfo --disableFastRender --environment development

initial: update env install serve ## Install tools and start development server
Enter fullscreen mode Exit fullscreen mode

Now we have some command-line aliases that you can check in! Great idea! If you’re wondering what’s up with that weird ## comment syntax, it gets better.

A self-documenting Makefile

Aliases are great, if you remember what they all are and what they do without constantly typing cat Makefile. Naturally, you need a help command:

.PHONY: help
help: ## Show this help
    @egrep -h '\s##\s' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
Enter fullscreen mode Exit fullscreen mode

With a little command-line magic, this egrep command takes the output of MAKEFILE_LIST, sorts it, and uses awk to find strings that follow the ## pattern. It then prints a helpful formatted version of the comments.

We’ll put it at the top of the file so it’s the default target. Now to see all our handy shortcuts and what they do, we just run make, or make help:

help         Show this help
initial      Install tools and start development server
install      Install or update dependencies
serve        Run the local development server
update       Do apt upgrade and autoremove
Enter fullscreen mode Exit fullscreen mode

Now we have our very own personalized and project-specific CLI tool!

The possibilities for improving your DevOps flow with a self-documenting Makefile are almost endless. You can use one to simplify any workflow and produce some very happy developers.

Top comments (3)

Collapse
 
mariobermonti profile image
Mario E. Bermonti Pérez

This is really cool. Thank you!

Collapse
 
pyrsmk profile image
Aurélien Delogu

Thanks! You made my day!

Collapse
 
shikkic profile image
Dan Cadden

This is really cool I want to try incorporating this into our Make workflow, thanks for sharing!