makehelp
makehelp
?
What is makehelp.pl
is a Makefile and a Perl script which provide built-in doxygen-style help in Makefile
s.
Special comments in the Makefile
are used to provide user documentation for goals and variables.
These comments are extracted by makehelp to print a nice documentation.
That documentation is similar to the built-in help texts of UNIX commands.
makehelp
without Installation
Using To use makehelp
in your project without installing it, append the following lines to your Makefile
:
-include .makehelp/include/makehelp/Help.mk
ifeq "help" "$(filter help,$(MAKECMDGOALS))"
.makehelp/include/makehelp/Help.mk:
git clone --depth=1 https://github.com/christianhujer/makehelp.git .makehelp
endif
And add the following lines to your .gitignore
:
.makehelp
.help.mk
makehelp
Installing Makehelp can run with or without installation.
If you want to install makehelp, run sudo make install
.
Per default, the include files are installed in /usr/local/include/makehelp/
and the binary files are installed in /usr/local/bin/
.
makehelp
.
Using makehelp
from your Makefile
Running To run makehelp
from your Makefile
, simply include the following line in your Makefile
:
-include makehelp/Help.mk
The best position to include this is at the end of your Makefile
.
If you are including other Makefiles and do not want to export the help they provide, include those Makefiles after makehelp/Help.mk
, not before.
makehelp
in your Makefile
Using Makehelp comments start with ##
instead of #
.
They should be positioned before those variables or goals that you want to document.
Included makefiles are supported.
Example for a variable documentation
## The prefix path for installation.
# Unless overridden individually, other installation paths are derived from this.
PREFIX:=/usr/local/
Example for goal documentation
.PHONY: all
## Builds everything.
all: hello
Sample Makefile
## The prefix path for installation.
# Unless overridden individually, other installation paths are derived from this.
PREFIX:=/usr/local/
## The path to install binary files.
BINDIR=$(PREFIX)bin/
.PHONY: all
## Builds everything.
all: hello
.PHONY: clean
## Removes generated files.
clean::
$(RM) hello hello.o
.PHONY: install
## Installs the binary program to $(BINDIR).
# On most systems, this needs to be run as root, i.e. using sudo.
install: all
install -d $(BINDIR) hello
-include makehelp/Help.mk
Sample output of running make help
:
Usage: make [OPTION|GOAL|VARIABLE]...
Runs make to make the specified GOALs.
If no GOAL is specified, the default goal is made (usually "all").
Popular make OPTIONs:
-s Silent mode, disables command echo.
-k Keep going, continues after errors.
-j N Run N jobs in parallel.
-n Don't run the commands, just print them.
-q Run no commands; exit status says if up to date.
-h Print make help text.
Use option -h to lists the GNUmake part of the help.
A VARIABLE is specified as name=value pair.
Supported VARIABLEs:
BINDIR The path to install binary files.
Current value: $(PREFIX)bin/
PREFIX The prefix path for installation.
Unless overridden individually, other installation paths are derived from this.
Current value: /usr/local/
Supported GOALs:
all Builds everything.
clean Removes generated files.
help Prints this help message.
install Installs the binary program to $(PREFIX)bin/.
On most systems, this needs to be run as root, i.e. using sudo.
For more examples, see