introduce 'make help'

makefile

@@ -63,7 +63,7 @@ ifneq ($V,1)
 endif
 	${silent} $(RANLIB) $@
 
-test: $(LIBNAME) $(TOBJECTS)
+test: $(call print-help,test,Builds the library and the 'test' application to run all self-tests) $(LIBNAME) $(TOBJECTS)
 ifneq ($V,1)
 	@echo "   * ${CC} $@"
 endif
@@ -71,7 +71,7 @@ endif
 
 # build the demos from a template
 define DEMO_template
-$(1): demos/$(1).o $$(LIBNAME)
+$(1): $(call print-help,$(1),Builds the library and the '$(1)' demo) demos/$(1).o $$(LIBNAME)
 ifneq ($V,1)
 	@echo "   * $${CC} $$@"
 endif
@@ -84,11 +84,11 @@ $(foreach demo, $(strip $(DEMOS)), $(eval $(call DEMO_template,$(demo))))
 #This rule installs the library and the header files. This must be run
 #as root in order to have a high enough permission to write to the correct
 #directories and to set the owner and group to root.
-install: .common_install
+install: $(call print-help,install,Installs the library and headers)) .common_install
 
-install_bins: .common_install_bins
+install_bins: $(call print-help,install_bins,Installs the useful demos ($(USEFUL_DEMOS))) .common_install_bins
 
-uninstall: .common_uninstall
+uninstall: $(call print-help,uninstall,Uninstalls the library and headers)) .common_uninstall
 
 profile:
 	LTC_CFLAGS="$(LTC_CFLAGS) -fprofile-generate" $(MAKE) timing EXTRALIBS="$(EXTRALIBS) -lgcov"
@@ -127,7 +127,7 @@ coverage: EXTRALIBS += -lgcov
 coverage: LIB_PRE = -Wl,--whole-archive
 coverage: LIB_POST = -Wl,--no-whole-archive
 
-coverage: test
+coverage: $(call print-help,coverage,Create code-coverage of the library - but better use coverage.sh) test
 	./test
 
 # cleans everything - coverage output and standard 'clean'

makefile.shared

@@ -48,30 +48,27 @@ LOBJECTS = $(OBJECTS:.o=.lo)
 $(LIBNAME): $(OBJECTS)
 	$(LT) --mode=link --tag=CC $(CC) $(LTC_CFLAGS) $(CPPFLAGS) $(LTC_LDFLAGS) $(LOBJECTS) $(EXTRALIBS) -o $@ -rpath $(LIBPATH) -version-info $(VERSION_LT)
 
-install: .common_install
-	sed -e 's,^prefix=.*,prefix=$(PREFIX),' -e 's,^Version:.*,Version: $(VERSION_PC),' libtomcrypt.pc.in > libtomcrypt.pc
-	install -d $(DESTDIR)$(LIBPATH)/pkgconfig
-	install -m 644 libtomcrypt.pc $(DESTDIR)$(LIBPATH)/pkgconfig/
-
-install_bins: .common_install_bins
-
-uninstall: .common_uninstall
-	rm $(DESTDIR)$(LIBPATH)/pkgconfig/libtomcrypt.pc
-
-test: $(LIBNAME) $(TOBJECTS)
+test: $(call print-help,test,Builds the library and the 'test' application to run all self-tests) $(LIBNAME) $(TOBJECTS)
 	$(LT) --mode=link --tag=CC $(CC) $(LTC_CFLAGS) $(CPPFLAGS) $(LTC_LDFLAGS) -o $(TEST) $(TOBJECTS) $(LIBNAME) $(EXTRALIBS)
 
 # build the demos from a template
 define DEMO_template
-$(1): demos/$(1).o $$(LIBNAME)
-ifneq ($V,1)
-	@echo "   * $${CC} $$@"
-endif
+$(1): $(call print-help,$(1),Builds the library and the '$(1)' demo) demos/$(1).o $$(LIBNAME)
 	$$(LT) --mode=link --tag=CC $$(CC) $$(LTC_CFLAGS) $$(CPPFLAGS) $$(LTC_LDFLAGS) $$^ $$(EXTRALIBS) -o $(1)
 endef
 
 $(foreach demo, $(strip $(DEMOS)), $(eval $(call DEMO_template,$(demo))))
 
+install: $(call print-help,install,Installs the library, headers and pkd-config file)) .common_install
+	sed -e 's,^prefix=.*,prefix=$(PREFIX),' -e 's,^Version:.*,Version: $(VERSION_PC),' libtomcrypt.pc.in > libtomcrypt.pc
+	install -d $(DESTDIR)$(LIBPATH)/pkgconfig
+	install -m 644 libtomcrypt.pc $(DESTDIR)$(LIBPATH)/pkgconfig/
+
+install_bins: $(call print-help,install_bins,Installs the useful demos ($(USEFUL_DEMOS))) .common_install_bins
+
+uninstall: $(call print-help,uninstall,Uninstalls the library, headers and pkd-config file)) .common_uninstall
+	rm $(DESTDIR)$(LIBPATH)/pkgconfig/libtomcrypt.pc
+
 # ref:         $Format:%D$
 # git commit:  $Format:%H$
 # commit time: $Format:%ai$

makefile_include.mk

@@ -44,6 +44,11 @@ endif
 endif
 endif
 
+need-help := $(filter help,$(MAKECMDGOALS))
+define print-help
+$(if $(need-help),$(info $1 -- $2))
+endef
+
 #
 # Compilation flags. Note the += does not write over the user's CFLAGS!
 #
@@ -168,8 +173,8 @@ GROUP=wheel
 endif
 
 
-#The default rule for make builds the libtomcrypt library.
-default: library
+#The first rule is also the default rule and builds the libtomcrypt library.
+library: $(call print-help,library,Builds the library) $(LIBNAME)
 
 
 # List of objects to compile (all goes to libtomcrypt.a)
@@ -356,29 +361,30 @@ src/hashes/sha2/sha256.o: src/hashes/sha2/sha256.c src/hashes/sha2/sha224.c
 $(DOBJECTS): LTC_CFLAGS := -Itests $(LTC_CFLAGS)
 $(TOBJECTS): LTC_CFLAGS := -Itests $(LTC_CFLAGS)
 
-#This rule makes the libtomcrypt library.
-library: $(LIBNAME)
-
 #Dependencies on *.h
 $(OBJECTS): $(HEADERS)
 $(DOBJECTS): $(HEADERS) $(THEADERS)
 $(TOBJECTS): $(HEADERS) $(THEADERS)
 
-bins: $(USEFUL_DEMOS)
+all: $(call print-help,all,Builds the library and all demos and test utils (test $(UNBROKEN_DEMOS) $(BROKEN_DEMOS))) all_test $(BROKEN_DEMOS)
 
-all: all_test $(BROKEN_DEMOS)
+all_test: $(call print-help,all_test,Builds the library and all unbroken demos and test utils (test $(UNBROKEN_DEMOS))) test $(UNBROKEN_DEMOS)
 
-all_test: test $(UNBROKEN_DEMOS)
+bins: $(call print-help,bins,Builds the library and all useful demos) $(USEFUL_DEMOS)
 
 #build the doxy files (requires Doxygen, tetex and patience)
-doxygen doxy docs:
+doxygen: $(call print-help,doxygen,Builds the doxygen html documentation)
+	$(MAKE) -C doc/ $@ V=$(V)
+doxy: $(call print-help,doxy,Builds the complete doxygen documentation including refman.pdf (takes long to generate))
+	$(MAKE) -C doc/ $@ V=$(V)
+docs: $(call print-help,docs,Builds the Developer Manual)
 	$(MAKE) -C doc/ $@ V=$(V)
 
-doc/crypt.pdf:
+doc/crypt.pdf: $(call print-help,doc/crypt.pdf,Builds the Developer Manual)
 	$(MAKE) -C doc/ crypt.pdf V=$(V)
 
 
-install_all: install install_bins install_docs install_test
+install_all: $(call print-help,install_all,Install everything - library bins docs tests) install install_bins install_docs install_test
 
 INSTALL_OPTS ?= -m 644
 
@@ -388,17 +394,21 @@ INSTALL_OPTS ?= -m 644
 	$(INSTALL_CMD) $(INSTALL_OPTS) $(LIBNAME) $(DESTDIR)$(LIBPATH)/$(LIBNAME)
 	install -m 644 $(HEADERS) $(DESTDIR)$(INCPATH)
 
-.common_install_bins: $(USEFUL_DEMOS)
+$(DESTDIR)$(BINPATH):
 	install -d $(DESTDIR)$(BINPATH)
+
+.common_install_bins: $(USEFUL_DEMOS) $(DESTDIR)$(BINPATH)
 	$(INSTALL_CMD) -m 775 $(USEFUL_DEMOS) $(DESTDIR)$(BINPATH)
 
-install_docs: doc/crypt.pdf
+install_docs: $(call print-help,install_docs,Installs the Developer Manual) doc/crypt.pdf
 	install -d $(DESTDIR)$(DATAPATH)
 	install -m 644 doc/crypt.pdf $(DESTDIR)$(DATAPATH)
 
-install_hooks:
-	for s in `ls hooks/`; do ln -s ../../hooks/$$s .git/hooks/$$s; done
+install_test: $(call print-help,install_test,Installs the self-test binary) test $(DESTDIR)$(BINPATH)
+	$(INSTALL_CMD) -m 775 $< $(DESTDIR)$(BINPATH)
 
+install_hooks: $(call print-help,install_hooks,Installs the git hooks)
+	for s in `ls hooks/`; do ln -s ../../hooks/$$s .git/hooks/$$s; done
 
 HEADER_FILES=$(notdir $(HEADERS))
 .common_uninstall:
@@ -407,7 +417,7 @@ HEADER_FILES=$(notdir $(HEADERS))
 
 #This rule cleans the source tree of all compiled code, not including the pdf
 #documentation.
-clean:
+clean: $(call print-help,clean,Clean everything besides the pdf documentation)
 	find . -type f    -name "*.o"   \
                -o -name "*.lo"  \
                -o -name "*.a"   \
@@ -429,7 +439,7 @@ clean:
 	rm -rf `find . -type d -name "*.libs" | xargs`
 	$(MAKE) -C doc/ clean
 
-zipup: doc/crypt.pdf
+zipup: $(call print-help,zipup,Prepare the archives for a release) doc/crypt.pdf
 	@# Update the index, so diff-index won't fail in case the pdf has been created.
 	@#   As the pdf creation modifies crypt.tex, git sometimes detects the
 	@#   modified file, but misses that it's put back to its original version.
@@ -447,6 +457,8 @@ zipup: doc/crypt.pdf
 	gpg -b -a crypt-$(VERSION).tar.xz
 	gpg -b -a crypt-$(VERSION).zip
 
-codecheck:
+codecheck: $(call print-help,codecheck,Check the code of the library)
 	perl helper.pl -a
 	perlcritic *.pl
+
+help: $(call print-help,help,That's what you're currently looking at)