Makefile: Difference between revisions

A rule defines a ''target'', 0..n ''dependencies'', and 0..n ''commands''. The general idea is that ''make'' checks if the target (file) is there; if it isn't, or any of the dependencies is newer than the target, the commands are executed. The general syntax is:

target: dependency

command

Both ''dependency'' and ''command'' are optional. There might be more than one ''command'' line, in which case they are executed in sequence.

As stated above, this tutorial is mainly derived from work done on the PDCLib project - which builds a single linker library. In that project, there is strictly one library function per source file. In each such source file, there is a test driver attached for conditional compilation, like this:

#ifdef TEST

int main()

}

#endif

Thus, when that source is compiled with <code>gcc -c</code>, it results in an object file with the library function code; when compiled with <code>gcc -DTEST</code>, it gives a test driver executable for that function. Returning the number of errors allows to do a grand total of errors encountered (see below).

=== Non-Source Files ===

# This is a list of all non-source files that are part of the distribution.

AUXFILES := Makefile Readme.txt

Further down we will have a target ''"dist"'', which packages all required files into a tarball for distribution. Lists of the sources and headers are created anyway. But there are commonly some auxiliary files, which are not referenced anywhere else in the Makefile but should still end up in the tarball. These are listed here.

=== Project Directories ===

PROJDIRS := functions includes internals

Those are subdirectories holding the actual sources. (Or rather, searched for source files automatically, see below.) These could be subprojects, or whatever. We could simply search for source files starting with the current working directory, but if you like to have temporary subdirectories in your project (for testing, keeping reference sources etc.), that wouldn't work.

=== Sources and Headers ===

SRCFILES := $(shell find $(PROJDIRS) -type f -name "\*.c")

HDRFILES := $(shell find $(PROJDIRS) -type f -name "\*.h")

It should be obvious to see what these two lines do. We now have a list of all source and header files in our project directories.

=== Object Files and Test Driver Executables ===

OBJFILES := $(patsubst %.c,%.o,$(SRCFILES))

TSTFILES := $(patsubst %.c,%_t,$(SRCFILES))

''OBJFILES'' should be clear - a list of the source files, with ''*.c'' exchanged for ''*.o''. ''TSTFILES'' does the same for the filename suffix ''*_t'', which we will use for our test driver executables.

We need two seperate sets of dependency files; one for the library objects, and one for the test driver executables (which usually have additional includes, and thus dependencies, not needed for the OBJFILES).

DEPFILES := $(patsubst %.c,%.d,$(SRCFILES))

TSTDEPFILES := $(patsubst %,%.d,$(TSTFILES))

=== Distribution Files ===

The last list is the one with all sources, headers, and auxiliary files that should end up in a distribution tarball.

ALLFILES := $(SRCFILES) $(HDRFILES) $(AUXFILES)

== .PHONY ==

The next one can take you by surprise. When you write a rule for ''make clean'', and there happens to be a file named ''clean'' in your working directory, you might be surprised to find that ''make'' does nothing, because the "target" of the rule ''clean'' already exists. To avoid this, declare such rules as ''phony'', i.e. disable the checking for a file of that name. These will be executed every time:

.PHONY: all clean dist check testdrivers todolist

== CFLAGS ==

If you thought ''-Wall'' does tell you everything, you'll be in for a rude surprise now. If you don't even use ''-Wall'', shame on you. ;)

WARNINGS := -Wall -Wextra -pedantic -Wshadow -Wpointer-arith -Wcast-align \

-Wwrite-strings -Wmissing-prototypes -Wmissing-declarations \

-Wconversion -Wstrict-prototypes

CFLAGS := -g -std=gnu99 $(WARNINGS)

It is suggested to add new warning options to your project one at a time instead of all at once, to avoid getting swamped in warnings. ;) These flags are merely recommendations for C work. If you use C++, you need different ones. Check out the GCC manual; each major compiler update changes the list of available warning options.

=== Top-Level Targets ===

all: pdclib.a

dist:

@tar czf pdclib.tgz $(ALLFILES)

The ''@'' at the beginning of a line tells ''make'' to be quiet, i.e. not to echo the executed commands on the console prior to executing them. The Unix credo is "no news is good news". You don't get a list of processed files with ''cp'' or ''tar'', either, so it's completely beyond me why developers chose to have their Makefiles churn out endless lists of useless garbage. One very practical advantage of shutting up ''make'' is that you actually get to ''see'' those compiler warnings, instead of having them drowned out by noise.

=== Automated Testing, pt. 2 ===

check: testdrivers

-@rc=0; count=0; \

testdrivers: $(TSTFILES)

Call it crude, but it works beautifully for me. The leading ''-'' means that 'make' will not abort when encountering an error, but continue with the loop.

=== Dependencies, pt. 2 ===

-include $(DEPFILES) $(TSTDEPFILES)

Further below, you will see how dependency files are ''generated''. Here, we ''include'' all of them, i.e. make the dependencies listed in them part of our Makefile. Never mind that they might not even exist when we run our Makefile the first time - the leading "-" again suppresses the errors.

=== Extracting TODO Statements ===

todolist:

-@for file in $(ALLFILES:Makefile=); do fgrep -H -e TODO -e FIXME $$file; done; true

Taking all files in your project, with exception of the Makefile itself, this will ''grep'' all those ''TODO'' and ''FIXME'' comments from your files, and display them in the terminal. It is nice to be remembered of what is still missing before you do a release. To add another keyword, just insert another <code>-e keyword</code>.

Below is an example of a ''backup'' target, which creates a dated 7-Zip archive of the directory where the Makefile resides.

THISDIR := $(shell basename `pwd`)

TODAY := $(shell date +%Y-%m-%d)

backup: clean

@tar cf - ../$(THISDIR) | 7za a -si ../$(BACKUPDIR)/$(THISDIR).$(TODAY)_`date +%H%M`.tar.7z

== Summary ==

Luckily, 'make' allows for conditional evaluation and manual error reporting, quite akin to the C preprocessor:

ifndef FRAMEWORK_PATH

$(error FRAMEWORK_PATH is not set. Please set to the path where you installed "Framework".)

$(warning FRAMEWORK_PATH is set to $(FRAMEWORK_PATH), not /usr/lib/framework. Are you sure this is correct?)

endif

== Multi-Target ==