Makefile: Difference between revisions

= Makefile tutorial =

 

 

The Makefile creates only one project-wide linker library, but it should be easy to expand it for multiple binaries/libraries.

 

 

== Basics ==

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

 

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 ===

 

 

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 ===

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 ===

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

 

=== Distribution Files ===

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

 

== .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:

 

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

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 ===

 

 

 

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 ===

 

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 ===

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 ===

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

 

 

Now comes the dependency magic I talked about earlier. Note that this needs GCC 3.3 or newer.

Isn't it a beauty? ;-)

 

Of course we also need a rule for generating the test driver executables (and their dependency files):

 

 

Here you can see why test driver executables get a ''*_t'' suffix instead of a ''*.t'' extension: The ''-MMD'' option uses the basename (i.e., filename without extension) of the ''compiled'' file as basis for the dependency file. If we would compile the sources into ''abc.o'' and ''abc.t'', the dependency files would both be named ''abc.d'', overwriting each other.

 

Other compilers differ a bit in their support for this, so look up their specifics when using something else than ''GCC''.

 

== Summary ==

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

 

 

 

== Multi-Target ==

Preliminary work has been done to write an improved Makefile, which allows generating multiple binaries with individual settings while still being easy to configure and use. While this is not yet in "tutorial" format, commented source can be found [[User:Solar/Makefile | here]].

 

* [http://aegis.sourceforge.net/auug97.pdf Recursive Make Considered Harmful] by Peter Miller<br />A paper detailing why the traditional approach of recursive make invocations harms performance and reliability.

* [http://www.xs4all.nl/~evbergen/nonrecursive-make.html Implementing non-recursive make] by Emile van Bergen<br />Further input on the subject of non-recursive, low-maintenance Makefile creation.

* [http://www.gnu.org/software/make/manual/ Manual for GNU make]

 

----

[[Category:Tutorials|Makefile]]

 

[[de:Makefile]]