Makefile: Difference between revisions

Setting up a simple Makefile is easy. You can even go a long way ''without'' a Makefile, simply by using make's internal rulesets, however setting up a global project Makefile that works as intended is quite a bit harder.

First, I assemble various "file lists" which I need later in the Makefile.

<pre>

</pre>

Further down I have a target ''"dist"'', which packages all source and header files into a tarball. I create lists of the sources and headers anyway, but for auxiliary files which are not used anywhere else in the Makefile, I need this explicit list to have them included in the tarball.

<pre>

PROJDIRS := functions includes internals

''Note that this is not a recursive approach; there is no Makefile in those subdirectories. Dependencies are hard enough to get right if you use one Makefile. Google for a very good paper on the subject titled "recursive make considered harmful"; not only is a single Makefile easier to maintain (once you learned a couple of tricks), it's also more efficient!''

<pre>

SRCFILES := $(shell find $(PROJDIRS) -mindepth 1 -maxdepth 3 -name "*.c")

''The -mindepth option keeps any top-level files out of the result set, like tmp.c or test.c or whatever you might have created for testing something on the fly. The -maxdepth option stops the 'find' to recurse into the CVS/ directories I used to have. You might want to adapt this to your requirements.''

I think it's time I explain my approach to testing. I write strictly one library function per source file. Then, I add a test driver to that source file:

<pre>

Thus, when I compile that source with ''gcc -c'', I get an object file with the library function code; when I compile with ''gcc -DTEST'', I get a test driver executable for that function. Returning the number of errors allows me to do a grand total of errors encountered (see below).

<pre>

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

''OBJFILES'' should be clear - a list of the source files, with ''*.c'' exchanged for ''*.o''. ''TSTFILES'' does the same for the extension ''*.t'', which I chose for my test driver executables.

Many people edit their Makefile every time they add/change an ''#include'' somewhere in their code. Did you know that ''GCC'' can do this automatically for you? Yes, it can. Trust me. Although the approach looks a little backward. For each source file, ''GCC'' will create a ''dependency file'' (which I made end in ''*.d''), which contains a Makefile dependency rule listing that source file's includes. (And more, but see below.)

<pre>

</pre>

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

<pre>

</pre>

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:

<pre>

</pre>

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

<pre>

I suggest you add them one by one instead of all at once. ;) These flags are for C, there are more to be used for C++.

Now come the rules, in their typical backward manner (top-level rule first).

<pre>

all: pdclib.a

The awkward looking loop in the ''clean'' rule is to avoid confusing error messages if the files to be deleted don't exist.

<pre>

test: testdrivers

If you get a ''SEGFAULT'' or something like that, add a temporary ''echo $$file'' to the loop to get the name of the test driver this happens in. For ''normal'' test failures, add a diagnostic to the test driver.

<pre>

-include $(DEPFILES)

This will ''grep'' all those ''TODO'' and ''FIXME'' comments from the files and display them in the terminal. It's nice to be remembered of what's still missing before you do a release. To add another keyword, just add another <code>-e keyword</code>. Don't forget to add <code>todolist</code> to your <code>.PHONY</code> list.

Now comes the dependency magic I talked about earlier:

Note that the dependency list of the rule includes the Makefile itself. If you changed e.g. the ''CFLAGS'', you want them to be applied, don't you?

<pre>

%.t: %.c Makefile pdclib.a

This is somewhat of an anticlimax in its "triviality". My test drivers need to link against the ''PDCLib'' itself, but that's already all. This is not really perfect; if ''any'' PDCLib function was touched (and, thus, pdclib.a updated), it recreates ''all'' test drivers, even when not necessary. Ah well, no Makefile ever is perfect, but I'd rather have too much compiled than missing a dependency.

Hope this helps you in creating your own Makefile, and then forgetting about it (as you should, because 'make' should lessen your workload, not add more).