make-templates(32) Language: English


Documentation for the MDVL Makefile Templates

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

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.

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.

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

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.

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

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