如何自动生成 Makefile 帮助命令

Question

我最近在网上找到了这篇文章，它解释了如何设置一个make help目标，该目标将自动解析 Makefile 以获取注释并显示格式良好的帮助命令。

它解析：

install: ## Install npm dependencies for the api, admin, and frontend apps
    @echo "Installing Node dependencies"
    @npm install

install-dev: install ## Install dependencies and prepared development configuration
    @./node_modules/.bin/selenium-standalone install
    @cp -n ./config/development.js-dist ./config/development.js | true

run-frontend-dev: webpack.PID ## Run the frontend and admin apps in dev (using webpack-dev-server)

进入：

install              Install npm dependencies for the api, admin, and frontend apps
install-dev          Install dependencies and prepared development configuration
run-frontend-dev     Run the frontend and admin apps in dev (using webpack-dev-server)

但由于某种原因，我无法让它工作（至少在 OSX 上）。有了这个目标：

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

当我运行时：

make help

我只是得到：

$ make help
make: Nothing to be done for `help'.

我也尝试了文章评论中的所有不同解决方案，但似乎没有任何效果。我究竟做错了什么？

此外，脚本的变体是什么，允许将注释放在目标之前的行上，而不是在目标之后。像这样：

# Build the source files with Babel.
build: $(shell find lib)
    @rm -rf build
    @mkdir -p build
    @$(babel) lib $(babel_options)

# Seed the database with fake data.
db-fake:
    @$(run) node bin/run-sql fake

这是有问题的完整 Makefile：

# Options.
DEBUG ?=
SOURCEMAPS ?= true
WATCH ?=

# Variables.
bin = ./node_modules/.bin
tests = $(shell find test/routes -depth 1)
shorthand-tests = $(patsubst test/routes/%.js,test-%,$(tests))

# Binaries.
babel = $(bin)/babel
mocha = $(bin)/mocha
node = node
nodemon = $(bin)/nodemon
run = heroku local:run

# Babel options.
babel_options = \
    --out-dir build \
    --copy-files

# Sourcemaps?
ifneq ($(SOURCEMAPS),false)
babel_options += --source-maps
endif

# Watch?
ifdef WATCH
babel_options += --watch
endif

# Development?
ifneq ($(NODE_ENV),production)
node = $(nodemon)
endif

# Debug?
ifdef DEBUG
node += debug
mocha += debug
endif

# Default.
default: help ## Default.

# Build the source files with Babel.
build: $(shell find lib) ## Build the source files with Babel.
    @rm -rf build
    @mkdir -p build
    @$(babel) lib $(babel_options)

# Seed the database with fake data.
db-fake: ## Seed the database with fake data.
    @$(run) node bin/run-sql fake

# Reset the database, dropping everything and the creating again.
db-reset: ## Reset the database, dropping everything and the creating again.
    @$(run) node bin/run-sql drop
    @$(run) node bin/run-sql create

# Seed the database with test data.
db-seed: ## Seed the database with test data.
    @$(run) node bin/run-sql seed

# Show the help prompt.
help: ## Show the help prompt.
  @awk '/^#/{c=substr($0,3);next}c&&/^[[:alpha:]][[:alnum:]_-]+:/{print substr($1,1,index($1,":")),c}1{c=0}' mm.mk | column -s: -t

# Open the PSQL interface.
psql: ## Open the PSQL interface.
    @psql contentshq

# Run the development server.
server: ## Run the development server.
    @$(run) $(node) bin/api

# Start the local postgres server.
start: ## Start the local postgres server.
    @pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start

# Stop the local postgres server.
stop: ## Stop the local postgres server.
    @pg_ctl -D /usr/local/var/postgres stop -s -m fast

# Run all of the tests.
test: ## Run all of the tests.
    @$(run) $(mocha) $(tests)

# Run specific route tests.
$(shorthand-tests): ## Run specific route tests.
    @$(run) $(mocha) test/routes/$(subst test-,,$@).js

# Watch the source files with Babel.
watch: ## Watch the source files with Babel.
    @WATCH=true $(MAKE) build

# Phony targets.
.PHONY: help
.PHONY: test
.PHONY: watch

Answer 1

这是一个小 awk 脚本，它将处理注释出现在目标名称之前的情况。我曾经column将文本放入列中，但您可以使用 printf 在 awk 中完成（并且，如果您愿意，还可以添加控制台代码以对输出进行着色）；使用的好处column是它可以自动计算出列宽。

你可以用同样的方式将它插入到 Makefile 中：

.PHONY: help

# Show this help.
help:
    @awk '/^#/{c=substr($$0,3);next}c&&/^[[:alpha:]][[:alnum:]_-]+:/{print substr($$1,1,index($$1,":")),c}1{c=0}' $(MAKEFILE_LIST) | column -s: -t

Answer 2

您需要一个help能够实际提取和打印消息的规则。假设您正在谈论的文章是http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html，这就是您正在寻找的内容。

.PHONY: help

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

命令方法之前的文档可能是可行的，但需要更多的工作。大多数 UNIX 命令都是逐行工作的，因此使用本文中指定的注释会更容易。