awk script to generate a help text from a Makefile

README.md

Makehelp

Generates help text for makefiles based on comment annotations.

Usage

Fetch the script and point it at one or more makefiles

curl -#fSLO https://gist.githubusercontent.com/bluebrown/2ec155902622b5e46e2bfcbaff342eb9/raw/Makehelp.awk
awk -f Makehelp.awk Makefile

Or from within the Makefile:

help:  ## show this help message
    @awk -f Makehelp.awk $(MAKEFILE_LIST)

example.mk

##@ Options

fruits ?= lime strawberry pineapple

##@ Commands

help:  ## show this help message
	@./Makehelp.awk $(MAKEFILE_LIST)

smoothie: $(fruits)  ## make a soomthie using $fruits
	@shuf -e $^

$(fruits): # single # undcoumented no op

Makehelp.awk

#!/usr/bin/env -S awk -f

BEGIN { FS = "[[:space:]]*(#?##@|:.*##|\\?=)[[:space:]]*" }

# ##@ <heading>
/^#?##@/  { printf("\n%s\n", $2); next }

# <target>: ## <description>
/^[a-zA-Z_0-9/-]+:.*##/ { printf("  %-20s%s\n", $1, $2); next }

# [export] <variable> ?= [<default>]
/^(export[[:space:]]+)?[a-zA-Z_0-9/-]+[[:space:]]*\?=/ {
  sub(/^export[ \t]+/, "", $1); printf("  %-20s%s\n", $1, $2)
}