自我记录的Makefile

自动让 "make help "打印你的Makefile的用法。

由于在golang社区的广泛使用，Makefiles正在卷土重来。唯一的问题是......它们是做什么的？阅读makefile是一件很困难的事情--它通常很难看，而且许多目标只供内部使用。而且，与一个好的CLI程序不同的是，没有相当于--help 。

如果你能对makefile进行标记，并让make help ，自动产生一个使用说明，那不是很好吗？

我第一次在Marme Lab博客上读到如何做到这一点，是在Self-Documented Makefile。在Hacker News上有一个后续报道，在接近底部的地方，m6w6发布了一个甚至更好的版本：

# https://www.client9.com/self-documenting-makefiles/
help:
        @awk -F ':|##' '/^[^\t].+?:.*?##/ {\
        printf "\033[36m%-30s\033[0m %s\n", $$1, $$NF \
        }' $(MAKEFILE_LIST)
.DEFAULT_GOAL=help
.PHONY=help

把这个添加到你的makefile的底部（并确保用tab来代替前面的空格）。或者在bash中作为一个单行代码：

@awk -F ':|##' '/^[^\t].+?:.*?##/ {printf "\033[36m%-30s\033[0m %s\n", $1, $NF}' Makefile

天啊，在一行中，你得到了makefile的东西、awk的东西、正则表达式、printf格式和终端颜色。理解这一点可能很难，但使用它却非常容易。只要在同一行中使用## 注释来记录你的目标：

build: ## build but do not install
        go build .
install: ## install command
        go install .
lint: ## run linters
        gometalinter ...
clean:  ## cleanup
        go clean ./..

并尝试一下：

$ make help
build               build but do not install
install             install command
lint                run linters
clean               cleanup

如果你想要排序的输出，尽可以在help 目标的末尾添加一个|sort 。

我见过一些其他的解决方案来为Makefiles添加文档。其中一个是用另一个程序来包装make。我很想让make help 调用一个golang程序来解析Makefile来生成帮助。但这个awk 的技巧是迄今为止最好的，因为它在几乎所有的系统上都能开箱即用。我已经在macOS、linux和带有busybox的Alpine Linux上进行了测试awk 。