How to create a self-documenting Makefile
Tags: showdev, productivity, devops
Published: 2020-08-11 12:04:29

---
title: How to create a self-documenting Makefile
published: true
date: 2020-08-05 12:55:19 UTC
tags: ["showdev","productivity", "devops"]
canonical_url: https://victoria.dev/blog/how-to-create-a-self-documenting-makefile/
cover_image: https://dev-to-uploads.s3.amazonaws.com/i/6lru4nlhhkcdwb0m1od7.png
---

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:

```sh
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
```

… you could just type:

```sh
make start
```

…and then start working?

## [Making a difference](#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](https://www.gnu.org/software/make/manual/make.html#Rules) and [recipes](https://www.gnu.org/software/make/manual/make.html#Recipes). Similar parallels exist for POSIX flavor make, like [Target Rules](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html#tag_20_76_13_04); here’s a [great article](https://nullprogram.com/blog/2017/08/20/) on POSIX-compatible Makefiles.

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

```Makefile
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
```

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](#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:

```Makefile
.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}'
```

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`:

```text
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
```

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.