make-templates(32) Language: English


Documentation for the MDVL Makefile Templates

----------------------------------------------------------------------[ Meta ]--

name		make-templates
section		32
description	Documentation for the MDVL Makefile Templates
tags		mdvl make build compile c template mdvl-make-templates
encoding	utf8
compliance	public
lang		en
creation	2014/07/04 17:43:31
version		1.0.2.0
copyright	Copyright (c) 2014, 2015 Ma_Sys.ma.
		For further info send an e-mail to Ma_Sys.ma@web.de.

--------------------------------------------------------------[ Introduction ]--

Makefiles are fine tools to automate build processes. Sadly, they are often used
inefficiently, incorrectly or simply written in a very stupid and redundant way.
Therefore, some common templates which one might want to use in each and every
Makefile have been extracted and stored in the `mdvl-make-templates` package.

Currently, there are templates for the following sorts of tasks:
 * Building C applications or libraries
 * Building Java (JAR file) targets
 * Generating PDF from LaTeX sourcecode
 * Helper templates to be used in conjunction with programs which do not need a
   Makefile to build but can still make use of the `install` target or which are
   to be included in a recursive Makefile environment
 * Creating a top-level ``recursive'' Makefile to recursively build generic
   targets like `release` or `install` in a list of specified subdirectories.

------------------------------------------------------------[ Basic Features ]--

Every Makefile using one of the MDVL templates automatically exports the
following targets for user invocation.

`release`
	To prepare the program for installation
`install`
	To install the program or script into a root-structure below
	`$(DESTDIR)` (useful in conjunction with `debuild` package building).
`clean`
	To clean up all automatically generated and unnecessary files which are
	not intented to be installed.
`dist-clean`
	To clean all generated files. This is useful for resetting the source
	code tree back to its original state after a successful or failed
	compilation, installation or archive generation.
`tgz`, `7z`, `txz`
	To build archives containing a `make release` built tree including all
	source files. This is useful for releasing a program to a website or
	give it away via portable media or e-mail. If you want to rename the
	root directory of the created archive file, use `COPYPWD=<name>`. As the
	name suggests, this requires copying the whole directory once.
`todo`
	To search for common strings marking parts of the sourcecode which have
	not yet been implemented. If you only want to apply this to a specific
	directory, specify the `DTODO` macro with a pathname _after_ including
	the template.
`final`
	Includes the template code into the makefile in order to make it useful
	to other users as well. Be aware, that this might not work properly for
	recursive targets.

It does not always make sense to use all of these targets. `install` might not
be useful when building e.\,g. documentation. Also, `release`, `clean` and
`dist-clean` might be implemeneted to do nothing when dealing with Makefiles for
scripts etc.

Also, if `DEBUG=1` is specified externally (e.\,g. via `make DEBUG=1 install`)
this will reveal just about any command involved in the compilation. Be aware
however, that this will include some parts which are used to pretty-print
messages as well.

----------------------------------------------------------[ Generic Template ]--

To make use of the MDVL Makefile Templates, create a Makefile like this

{\code{make}}

	LANG   = <type of makefile>
	TARGET = <application>
	RES    = <resource files>
	
	include /usr/share/mdvl/make.mk
	
	install: instdep
		$(MKDIR) /usr/bin
		$(INSTALL) $(TARGET) /usr/bin

The `<type of makefile>` is one of the supported programming languages or a
special type name for e.\,g. recursive Makefiles etc. `TARGET` is the often name
of your application. More specifically, it is the name of the main target to be
created by this makefile. This variable is not used when a recursive Makefile
template is used. `RES` is a list of resources (e.\,g. C object files) used to
build your application. Finally, it is recommended to always include an
`install` target.

As you can see in the `install` target, there are some useful macros defined by
default.

`MKDIR`
	represents a `mkdir` command which ensures the directory is created
	below `$(DESTDIR)` and prints a colorized message to the user.
`INSTALL`
	installs a file with the same executable bit as the source file. This
	macro also ensures the installation is copied below `$(DESTDIR)`
`RINSTALL`
	This one is used like `cp -R` and also ensures everything goes below
	`$(DESTDIR)`

`MSG`
	This is a rather internal macro which may be used to print a colorized
	message like those printed by the other macros. It takes an integer to
	describe the foreground color, an action name to display in brackets and
	a message to display behind the action name as parameters.

----------------------------------------------------------------[ C Template ]--

The classical, most obvious and most suitable task for Makefiles is the compiler
invocation for the compilation of C programs. The generic template shown above
is extended and clarified as shown below.

{\code{make}}

	LANG     = c
	TARGET   = <binary>
	RES      = <object files>
	TEST_DEF = <default test in user specified format>
	
	include /usr/share/mdvl/make.mk
	
	<header dependencies for all object files>
	
	test: $(TARGET)
		<invoke test here using $(TEST) as test file specification and
				prefix $(DEBUG_APP) to the program invocation>
	
	install: instdep
		$(MKDIR) /usr/bin
		$(INSTALL) $(TARGET) /usr/bin

The following macros may optionally be declared before the `include` directive
in order to change some defaults.

`LIB=1`
	mark this as a library target. This affects the final `CFLAGS`.
`XFLAGS`
	may add some flags to the compiler invocation (useful if the application
	e.\,g. depends on external libraries).
`XCLEAN`
	may add some files to be cleared when using the `clean` target. By
	default, all registered objects (`RES`) are cleared.

Also, these macros may optinally be overriden after the `include` directive in
order to change the Makefile behaviour

`CC`
	to specify an alternative compiler
`CVER`
	to change the C version (default: `c89`).
`SHFLAGS`
	to replace the default flags.
`FLAGS`
	to replace the default flags for targets without `DEBUG=1`
`FLAGS_DBG`
	to replace the default flags for targets with `DEBUG=1`
`VALGRIND`
	to replace the valgrind executable and parameters
`TRACE`
	to specify an alternative tracing program
`STRACE`
	to replace the way `strace` is invoked.
`CLEANPAT`
	to specify an alternative list of files to be cleaned upon invocation of
	the `clean` target.

--------------------------------------------------------[ Recursive Template ]--

A special template can be used when specifying `LANG = recursive`. Then, the
Makefile will not be responsible for compiling programs itself but rather invoke
`make` in the directories given for the `RES` variable. The minimum working
example for a ``recursive'' Makefile is really simple.

{\code{make}}

	LANG   = recursive
	TARGET = <program name>
	RES    = <list your subdirectories here>
	
	include /usr/share/mdvl/make.mk

Optionally, `XTARGETS` can be specified before the inclusion of the template in
order to add some targets to be recursively built. Also, it is recommended but
not strictly required to give a `TARGET` name. `TARGET` is only used with the
archive creation targets and not required to do recursive builds or
installations.

--------------------------------------------------------------[ Raw Template ]--

The raw template is easy to use

{\code{make}}

	LANG   = raw
	TARGET = <main program file>
	
	include /usr/share/mdvl/make.mk
	
	install: instdep
		$(MKDIR) /usr/bin
		$(INSTALL) $(TARGET) /usr/bin

There are no additional macros to influence the template's behaviour because the
template always does nothing. If you need some custom means of building a
program you may either include some partial Makefile templates, add your own
template to the package or declare a target like `all` before the inclusion of
the template in order for that target to be built if `make` is invoked without
parameters. Also, if you want to do automatic cleanup, you need to specify the
`XCLEAN` macro.

-------------------------------------------------------------[ Java Template ]--

The Java template is used to compile Java sourcecode and built JAR files from
Java projects.

{\code{make}}

	LANG     = java
	TARGET   = <jarfile name including extension>
	RES      = <root package directories>
	MAIN     = <main class>
	TEST_DEF = <default test>
	
	include /usr/share/mdvl/make.mk
	
	test: all
		$(Q)java $(CPV) $(MAIN) $(TEST)

The additional macro `XCP` may be used to specify additional files/dirs to add
to the classpath. Entries are separated with a colon (`:`). Also, `XRES` may be
used to specify some directories which contain code not to be compiled/cleaned.
Apart from the additional macros, the following addtional targets are defined:

`jar`
	as an alias for `$(TARGET)` to create the JAR-file
`javadoc`
	to generate a Javadoc documentation for all source files.
`javadoc-clean`
	to delete the Javadocs. This is also used internally by `dist-clean`.

An `install` target may be optionally added.

This template attempts to build projects incrementally. In case of compilation
errors this does not work which is why we perform some automatic cleanup then.
To disable automatic cleanup, please give the `AUTOCLEAN=0` macro.

------------------------------------------------------------[ LaTeX Template ]--

The `tex` type of Makefile is used to make PDFs from LaTeX sourcecode. It is not
necessary to define any targets (compare example below).

{\code{make}}

	LANG   = tex
	TARGET = <output pdf file>
	RES    = <included files without suffix>
	
	include /usr/share/mdvl/make.mk

You can of course add an `install` target, but it won't generally be necessary.

Apart from the default targets and macros available, this template allows you
to customize behaviour via some addtional macros

`BIBTEXFATAL`
	If this is defined and set to `1`, the `make` process aborts whenever
	`bibtex8` returns non-zero.
`XDISTCLEANPAT`
	This may be used to define additional files to `dist-clean`.
`MAXRUNS`
	Specifies the maximum number of `pdflatex` runs to perform. It should
	normally not be necessary to increase this but sometimes you may want to
	decrease it.
`TEXCMD`
	If this macro is declared, this command is used instead of the default
	`pdflatex`. This allows you to use `TEXCMD = xelatex` to support UTF-8
	properly.

Not only does this template add some means of customizing the compilation, it
also adds some useful targets.

`summary.txt`
	Allows you to create a text file with the contents of `make todo` and
	all warnings generated by LaTeX.
`outline.txt`
	Originally created for the Ma_Sys.ma PDF, this generates a (very simple)
	outline of your document. It is intented to be used if you need to refer
	to section names from an external document but do not want to constantly
	have the generated PDF file open.

--------------------------------------------------------------[ Known Issues ]--

_TODO_ The LaTeX template should support a means of specifying a custom `texmf`
direcotry which should automatically be included. Currently, it looks like we
need to copy all files to the folder we also compile in (flat)... This should
either be automated or a better way should be found.

_TODO_ Issue w/ raw template: `make dist-clean` consequently deletes target for
raw targets as well... no good w/ script targets!

_TODO_ Recursive Template does not fail if sub-make fails

Templates set LANG to unexpected values (exported as environment variable).


Zum Seitenanfang