How to document a makefile?

Question

Is there a way to write “standard” comments in a Makefile so that I can later transfer them to a Doxygen-like program to produce good (HTML or man) documentation? I would like to have a clear overview of my main goals somewhere, but nothing too fantastic.

Answer 1

One nice touch is to provide a fake help target, which displays a summary of goals and options. From the Linux kernel 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 '' 

It may be a little work to maintain the documentation this way, but I believe that it perfectly separates what is intended for “users” and is intended for people who support Makefile itself (built-in comments).

Answer 2

Self-Documenting Makefiles (John Graham-Cumming, 2005) allows you to write help along with each rule. This is a lightweight and very great solution that works with at least GNU Make.

Here is my slightly modified version (the def-help section helps organize long lists of rules).

Answer 3

I made my own decision using a short Perl script that formats help like other GNU tools:

 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." 

What gives this:

 $ 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 4

The following is a simpler solution that does not require defining custom functions or aggregating help text away from the rules that they document.

 # 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. 

Running make or make help leads to the following:

 ---------------------------------------------------------------------- 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.