Question

有没有办法在Makefile中编写“标准”注释，以便以后将它们提供给类似Doxygen的程序，以便输出一个好的（HTML或man）文档？我想在某个地方清楚地了解我的主要目标，但没有什么太花哨的。

Answer 1

一个不错的方法是提供一个假的help目标，用于打印目标和选项的摘要。来自Linux内核Makefile：

help:
        @echo  'Cleaning targets:'
        @echo  '  clean           - Remove most generated files but keep the config and'
        @echo  '                    enough build support to build external modules'
        @echo  '  mrproper        - Remove all generated files + config + various backup files'
        @echo  '  distclean       - mrproper + remove editor backup and patch files'
        @echo  ''
        @echo  'Configuration targets:'
        @$(MAKE) -f $(srctree)/scripts/kconfig/Makefile help
        @echo  ''

以这种方式维护文档可能有点工作，但我发现它很好地将“用户”的内容与维护Makefile本身的内容（内联注释）的内容区分开来。 / p>

Answer 2

我使用简短的Perl脚本制作了自己的解决方案，该脚本将帮助格式化为其他GNU工具：

SCRIPT_VERSION=v1.0
SCRIPT_AUTHOR=John Doe

all:                ##@Build Build all the project 

clean:              ##@Cleaning Remove all intermediate objects

mrproper: clean     ##@Cleaning Remove all output and interemediate objects

HELP_FUN = \
    %help; while(<>){push@{$$help{$$2//'options'}},[$$1,$$3] \
    if/^([\w-_]+)\s*:.*\#\#(?:@(\w+))?\s(.*)$$/}; \
    print"$$_:\n", map"  $$_->[0]".(" "x(20-length($$_->[0])))."$$_->[1]\n",\
    @{$$help{$$_}},"\n" for keys %help; \

help: ##@Miscellaneous Show this help
    @echo -e "Usage: make [target] ...\n"
    @perl -e '$(HELP_FUN)' $(MAKEFILE_LIST)
    @echo -e "Written by $(SCRIPT_AUTHOR), version $(SCRIPT_VERSION)"
    @echo -e "Please report any bug or error to the author."

这给出了这个：

$ make help
Usage: make [target] ...

Miscellaneous:
  help                Show this help

Build:
  all                 Build all the project

Cleaning:
  clean               Remove all intermediate objects
  mrproper            Remove all output and interemediate objects

Written by John Doe, version v1.0
Please report any bug or error to the author.

Answer 3

以下是一个更简单的解决方案，不需要定义用户功能或将帮助文本聚合在他们记录的规则之外。

# This is a regular comment, that will not be displayed

## ----------------------------------------------------------------------
## This is a help comment. The purpose of this Makefile is to demonstrate
## a simple help mechanism that uses comments defined alongside the rules
## they describe without the need of additional help files or echoing of
## descriptions. Help comments are displayed in the order defined within
## the Makefile.
## ----------------------------------------------------------------------

help:     ## Show this help.
    @sed -ne '/@sed/!s/## //p' $(MAKEFILE_LIST)

build:    ## Build something.

install:  ## Install something.

deploy:   ## Deploy something.

format:   ## Help comments are display with their leading whitespace. For
          ## example, all comments in this snippet are aligned with spaces.

运行make或make help会产生以下结果：

----------------------------------------------------------------------
This is a help comment. The purpose of this Makefile is to demonstrate
a simple help mechanism that uses comments defined alongside the rules
they describe without the need of additional help files or echoing of
descriptions. Help comments are displayed in the order defined within
the Makefile.
----------------------------------------------------------------------
help:     Show this help.
build:    Build something.
install:  Install something.
deploy:   Deploy something.
format:   Help comments are display with their leading whitespace. For
          example, all comments in this snippet are aligned with spaces.

Answer 4

Self-Documenting Makefiles（John Graham-Cumming，2005）允许您在每条规则旁边写下帮助。这是一个轻量级且非常漂亮的解决方案，至少可以使用GNU Make。

我的slightly modified version（def-help-section帮助组织长长的规则列表）。

Answer 5

我正是出于这个目的编写了MakeHelp库。它使您可以在每个规则上方编写规则文档。非常容易使用。

我发现它与此处的其他自记录Makefile不同，因为它没有重复性，并且允许多行文档和私有规则。

Answer 6

在诸如：

的生成文件中

install: ## Do a
  @echo "foo"

start: ## Do b
  @echo "bar"

test: ## Do c
  @echo "baz"

help:
  @egrep -h '\s##\s' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m  %-30s\033[0m %s\n", $$1, $$2}'

将输出：

如何记录makefile？

6 个答案: