Merge pull request #250 from libtom/pr/readme-building

README building instructions

README.md

@@ -1,15 +1,16 @@
-libtomcrypt
-==========
+# libtomcrypt
 
 See `doc/crypt.pdf` for a detailed documentation
 
-Project Status
---------------
+## Project Status
 
-develop: [![Build Status](https://api.travis-ci.org/libtom/libtomcrypt.png?branch=develop)](https://travis-ci.org/libtom/libtomcrypt) [![Coverage Status](https://coveralls.io/repos/libtom/libtomcrypt/badge.png?branch=develop)](https://coveralls.io/r/libtom/libtomcrypt) [![Coverity Scan Build Status](https://scan.coverity.com/projects/487/badge.svg)](https://scan.coverity.com/projects/487)
+master: [![Build Status](https://api.travis-ci.org/libtom/libtomcrypt.png?branch=master)](https://travis-ci.org/libtom/libtomcrypt) [![Coverage Status](https://coveralls.io/repos/libtom/libtomcrypt/badge.png?branch=master)](https://coveralls.io/r/libtom/libtomcrypt)
 
-Submitting patches
-------------------
+develop: [![Build Status](https://api.travis-ci.org/libtom/libtomcrypt.png?branch=develop)](https://travis-ci.org/libtom/libtomcrypt) [![Coverage Status](https://coveralls.io/repos/libtom/libtomcrypt/badge.png?branch=develop)](https://coveralls.io/r/libtom/libtomcrypt)
+
+[![Coverity Scan Build Status](https://scan.coverity.com/projects/487/badge.svg)](https://scan.coverity.com/projects/487)
+
+## Submitting patches
 
 Please branch off from develop if you want to submit a patch.
 
@@ -17,10 +18,100 @@ Patch integration will be faster if tests and documentation are included.
 
 Please update the makefiles in a separate commit. To update them simply run the `updatemakes.sh` script.
 
-Branches
---------
+## Branches
 
 Please be aware, that all branches besides _master_ and _develop_ __can__ and __will be__ force-pushed, rebased and/or removed!
 
 If you want to rely on such an _unstable_ branch, create your own fork of this repository to make sure nothing breaks for you.
 
+## Configuration options
+
+By default the library builds its entire feature set (besides `katja`) in a (depending on your needs more or less) optimal way.
+
+There are numerous configuration options available if you want to trim down the functionality of the library.
+
+Please have a look at `src/headers/tomcrypt_custom.h` for all available configuration options.
+
+The following list is a small part of the available, but the most often required, configuration switches.
+
+| Flag | Behavior |
+| ---- | -------- |
+| `LTC_NO_TEST` | Remove all algorithm self-tests from the library |
+| `LTC_NO_FILE` | Remove all API functions requiring a pre-defined `FILE` data-type (mostly useful for embedded targets) |
+| `MAX_RSA_SIZE` | Per default set to `4096`, if you need support for importing or generating bigger RSA keys, change this at compile-time. |
+| `GMP_DESC` | enable [gmp](https://gmplib.org/) as MPI provider *\*1* |
+| `LTM_DESC` | enable [libtommath](http://www.libtom.net/) as MPI provider *\*1* |
+| `TFM_DESC` | enable [tomsfastmath](http://www.libtom.net/) as MPI provider *\*1* *\*2* |
+| `USE_GMP` | use `gmp` as MPI provider when building the binaries *\*3* |
+| `USE_LTM` | use `libtommath` as MPI provider when building the binaries *\*3* |
+| `USE_TFM` | use `tomsfastmath` as MPI provider when building the binaries *\*3* |
+
+*\*1* It is possible to build the library against all MPI providers in parallel and choose at startup-time which math library should be used.
+
+*\*2* Please be aware that `tomsfastmath` has the limitation of a fixed max size of MPI's.
+
+*\*3* Only one is supported at the time & this is only required when building the binaries, not when building the library itself.
+
+## Building the library
+
+There are several `makefile`s provided. Please choose the one that fits best for you.
+
+| makefile | use-case |
+| -------- | -------- |
+| `makefile` | builds a static library (GNU Make required, broken on Mac OSX - use `makefile.unix` instead) |
+| `makefile.shared` | builds a shared (and static) library (GNU Make required) |
+| `makefile.unix` | for unusual UNIX platforms, or if you do not have GNU Make |
+| `makefile.mingw` | for usage with the mingw compiler on MS Windows |
+| `makefile.msvc` | for usage with the MSVC compiler on MS Windows |
+| `libtomcrypt_VS2008.sln` | A VisualStudio 2008 project for MS Windows |
+
+### Make targets
+
+The `makefile`s provide several targets to build (VS project excluded).
+The following list does not claim to be complete resp. to be available across all `makefile` variants.
+
+| target | application |
+| ------ | ----------- |
+| *empty target*/none given | c.f. `library`
+| `library` | builds only the library |
+| `hashsum` | builds the `hashsum` binary, similar to [`shasum`](https://linux.die.net/man/1/shasum), but with support for all hash-algorithms included in the library *\*4* |
+| `ltcrypt` | builds the `ltcrypt` binary, implementing something similar to [`crypt`](https://linux.die.net/man/3/crypt) *\*4* |
+| `sizes` | builds the `sizes` binary, printing all internal data sizes on invocation *\*4* |
+| `constants` | builds the `constants` binary, printing all internal constants on invocation *\*4* |
+| `openssl-enc` | builds the `openssl-enc` binary, which is more or less compatible to [`openssl enc`](https://linux.die.net/man/1/enc) *\*4* *\*5* |
+| `test` | builds the `test` binary, which runs all algorithm self-tests + some extended tests *\*4* *\*6* |
+| `timing` | builds the `timing` binary, which can be used to measure timings for algorithms and modes *\*4* *\*6* |
+| `bins` | builds `hashsum` *\*4* |
+| `all_test` | builds `test`, `hashsum`, `ltcrypt`, `small`, `tv_gen`, `sizes` & `constants` *\*4* |
+
+*\*4* also builds `library`
+
+*\*5* broken build in some configurations, therefore not built by default
+
+*\*6* requires define of one of `USE_GMP`, `USE_LTM` or `USE_TFM` (+ the appropriate MPI provider)
+
+### Examples
+
+You want to build the library as static library
+
+    make
+
+You want to build the library as shared library
+
+    make -f makefile.shared
+
+You have `libtommath` installed on your system and want to build a static library and the `test` binary to run the self-tests.
+
+    make CFLAGS="-DUSE_LTM -DLTM_DESC" EXTRALIBS="-ltommath" test
+
+You have `tomsfastmath` installed on your system and want to build a shared library and all binaries
+
+    make -f makefile.shared CFLAGS="-DUSE_TFM -DTFM_DESC" EXTRALIBS="-ltfm" all demos
+
+You have `gmp`, `libtommath` and `tomsfastmath` installed on your system and want to build a static library and the `timing` binary to measure timings against `gmp`.
+
+    make CFLAGS="-DUSE_GMP -DGMP_DESC -DLTM_DESC -DTFM_DESC" EXTRALIBS="-lgmp" timing
+
+If you have `libtommath` in a non-standard location:
+
+    make CFLAGS="-DUSE_LTM -DLTM_DESC -I/opt/devel/ltm" EXTRALIBS="/opt/devel/ltm/libtommath.a" all

doc/makefile

@@ -14,7 +14,10 @@ LEFTOVERS=*.dvi *.log *.aux *.toc *.idx *.ilg *.ind *.out *.lof
 doxygen:
 	doxygen $(silent_stdout)
 
-doxy: doxygen
+patched_doxygen:
+	(cat Doxyfile && echo "HAVE_DOT=no") | doxygen - $(silent_stdout)
+
+doxy: patched_doxygen
 	${MAKE} -C doxygen/latex $(silent_stdout) && mv -f doxygen/latex/refman.pdf .
 	@echo The huge doxygen PDF should be available as doc/refman.pdf
 

makefile

@@ -17,7 +17,7 @@ PLATFORM := $(shell uname | sed -e 's/_.*//')
 
 ifneq ($(MAKECMDGOALS),clean)
 ifeq ($(PLATFORM), Darwin)
-$(error Can't build static library on Mac, please use makefile.shared)
+$(error Known to not work on Mac, please use makefile.unix for static libraries or makefile.shared for shared libraries)
 endif
 endif
 
@@ -63,13 +63,7 @@ ifneq ($V,1)
 endif
 	${silent} $(RANLIB) $@
 
-timing: $(LIBNAME) $(TIMINGS)
-ifneq ($V,1)
-	@echo "   * ${CC} $@"
-endif
-	${silent} $(CC) $(LTC_LDFLAGS) $(TIMINGS) $(LIB_PRE) $(LIBNAME) $(LIB_POST) $(EXTRALIBS) -o $(TIMING)
-
-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
@@ -77,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
@@ -90,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"
@@ -133,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,33 +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)
 
-timing: $(TIMINGS) $(LIBNAME)
-	$(LT) --mode=link --tag=CC $(CC) $(LTC_CFLAGS) $(CPPFLAGS) $(LTC_LDFLAGS) -o $(TIMING) $^ $(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!
 #
@@ -124,14 +129,25 @@ DOBJECTS = $(DSOURCES:.c=.o)
 #List of tests headers
 THEADERS = $(wildcard tests/*.h)
 
-TIMING=timing
 TEST=test
 
-USEFUL_DEMOS=hashsum
-UNBROKEN_DEMOS=$(USEFUL_DEMOS) ltcrypt small tv_gen sizes constants
-DEMOS=$(UNBROKEN_DEMOS) openssl-enc
+# Demos that are even somehow useful and could be installed as a system-tool
+USEFUL_DEMOS   = hashsum
+
+# Demos that are usable but only rarely make sense to be installed
+USEABLE_DEMOS  = ltcrypt sizes constants
+
+# Demos that are used for testing or measuring
+TEST_DEMOS     = small tv_gen
 
-TIMINGS=demos/timing.o
+# Demos that are in one config broken
+#  openssl-enc - can't be build with LTC_EASY
+#  timing      - not really broken, but older gcc builds spit warnings
+BROKEN_DEMOS   = openssl-enc timing
+
+# Combine demos in groups
+UNBROKEN_DEMOS = $(TEST_DEMOS) $(USEABLE_DEMOS) $(USEFUL_DEMOS)
+DEMOS          = $(UNBROKEN_DEMOS) $(BROKEN_DEMOS)
 
 #LIBPATH  The directory for libtomcrypt to be installed to.
 #INCPATH  The directory to install the header files for libtomcrypt.
@@ -158,8 +174,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)
@@ -346,29 +362,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
+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
 
@@ -378,17 +395,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:
@@ -397,7 +418,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"   \
@@ -419,7 +440,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.
@@ -437,6 +458,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)