(This post is about building C-projects, which is an important part of coding in C. I hope that counts as "on topic" :^) )

When I started coding small C and C++ programs in my free time, I either created imperfect makefiles by blindly copying Stackoverflow answers, or replaced make with other programs such as CMake because I thought make was inadequate.

Now I know a little about make, and find that it is perfectly adequate for small hobby projects, and probably for large ones as well, though I couldn't speak from experience there.

What should the makefile do?

1. Compile each translation unit if, and only if, it changed or one of the user-defined header files it depends on did

2. Combine the translation units' object files into an executable, linking with libraries if necessary

3. Distinguish between compiling 'debug' executables, including debug symbols and assertions, and 'release' executables, without those, which are optimized

4. Install the executable

Our example

We are looking at a simple program which has two different source files and headers:

main.c:

#include "message.h"

int main(void)
{
    message();

    return 0;
}

message.c:

#include <stdio.h>

#include "message.h"
#include "answer.h"

void message(void)
{
    printf("%s %d\n", MSG, ANSWER);
}

message.h:

#define MSG "The answer is"

void message(void);

answer.h:

#define ANSWER 42

Building object files

First we tell make what compiler to use and how:

CC=gcc
CFLAGS=-MMD -Wall -Wextra -pedantic -std=c11

Then we make a list of all source files and object files we are looking at:

SRC=$(wildcard src/*.c)
OBJ=$(SRC:%.c=%.o)

The first line grabs all files in the folder src that end in .c, and the second makes another list by copying the first and replacing the final .c with .o.

Then we make the rule to compile any given object file:

%.o: %.c
	$(CC) $(CFLAGS) -c -o $@ $<

Source file dependencies

I used to think setting up make so that it would compile a translation unit when one of the included header files changed was too complicated a thing to do, which led me to use CMake for a lot of projects. Turns out, after doing some more research, it is actually incredibly easy.

This ignorance of mine led me to use CMake, which is a turing-complete programming language disguised as a build system, to build programs with six or seven .c-files---effectively aiming a Tsar Bomba at a farm in Missouri. FYI, cloc tells me that CMake (version 3.31.0-rc3) has 291081 lines of code, while GNU make (version 4.4) has 27947. Keep in mind that CMake, after all those lines of code, doesn't even build the project but spits out a makefile itself, which does it.

(That is not to say that you are wrong for using CMake, or that it is not better for large programs. This is about using a small tool for a small task.)

It turns out that the C-compiler can generate a make-compatible list of dependencies for a C-file. That is a program we are already using, and it can do that as a side task while compiling the object file, so we might as well have it do that.

Looking at src/main.c, running the the compiler as follows…

$ gcc -MMD -c -o src/main.o src/main.c

…does not only give me the object file, but also a file called src/main.d, which looks like this:

$ cat src/main.d
src/main.o: src/main.c src/message.h

If you have worked with makefiles before, you'll recognize that is exactly what we'd put into it if we were giving it the dependencies by hand.

Let's first grab a list of all those .d files:

DEP=$(OBJ:%.o=%.d)

Now, before we tell the makefile how to build the object files, we'll tell it to -include $(DEP). include works the same as it does in the C-preprocessor: it treats the content of the given file(s) as if they were typed into the makefile. Prepending a minus to include tells make not to complain if the file(s) do not exist, which would be the case when we are first compiling our project.

Now, after adding a compiler flag, and adding two further lines, our object files are compiled whenever one of their dependencies changes.

(That we get the .d files only after we have compiled the translation unit is fine, because if we change the source file, we need to recompile it that time anyway. If we later change one of the headers, we have the .d file ready.)

Compiling the executable

We add to our makefile's header:

EXE=msg
LIBS=$(addprefix -l,)

If we did need libraries, we would say something like:

LIBS=$(addprefix -l,m pthread)

Then we tell make how to compile msg:

$(EXE): $(OBJ)
	$(CC) -o $@ $^ $(LIBS)

($^, as opposed to $<, expands to all dependencies instead of just the first.)

Other targets

We are done with step one and two, but we still need to distinguish between debug and release builds, and install the executable.

debug: CFLAGS += -g
debug: $(EXE)

The first line says that, if we want to make the target debug, CFLAGS is expanded by the -g flag.

Similarly:

release: CFLAGS += -O3 -DNDEBUG
release: $(EXE)

Since make defaults to the first target, we could either put debug at the top or use the usual default target, all:

all: debug

(Cleaning up)

Sometimes, for example after changing the makefile itself, you want to rebuild the project even though none of the source files have changed. For that we would first introduce a target to get rid of the old output files:

clean:
	rm -f $(OBJ) $(DEP) $(EXE)

Which we can then use to build again from scratch:

remake: clean debug
.NOTPARALLEL: remake

Adding remake to the .NOTPARALLEL pseudo-target tells make not to do clean and debug simultaneously, if something like -j4 was passed. We obviously don't want to start building and then have files deleted.

Since we would usually want to switch to release after having tested the debug build, we can also use clean there:

release: CFLAGS += -O3 -DNDEBUG
release: clean $(EXE)
.NOTPARALLEL: release

Installing

I simply use:

TARGET=/usr/local

install: all
	cp $(EXE) $(TARGET)/bin

You could also make it depend on release but that would rebuild an executable you probably just built. This way the usual paradigm of…

$ make release
$ sudo make install

…is followed, but that is simply a matter of preference.

Conclusion

The final makefile looks like this:

CC=gcc
CFLAGS=-MMD -Wall -Wextra -pedantic -std=c11

SRC=$(wildcard src/*.c)
OBJ=$(SRC:%.c=%.o)
DEP=$(OBJ:%.o=%.d)

EXE=msg
LIBS=$(addprefix -l,)

TARGET=/usr/local

all: debug

debug: CFLAGS += -g
debug: $(EXE)

remake: clean debug
.NOTPARALLEL: remake

release: CFLAGS += -O3 -DNDEBUG
release: clean $(EXE)
.NOTPARALLEL: release

clean:
	rm -f $(OBJ) $(DEP) $(EXE)

install: all
	cp $(EXE) $(TARGET)/bin

$(EXE): $(OBJ)
	$(CC) -o $@ $^ $(LIBS)

-include $(DEP)

%.o: %.c
	$(CC) $(CFLAGS) -c -o $@ $<

It can be used like this:

$ make
gcc -MMD -Wall -Wextra -pedantic -std=c11 -g -c -o src/main.o src/main.c
gcc -MMD -Wall -Wextra -pedantic -std=c11 -g -c -o src/message.o src/message.c
gcc -o msg src/main.o src/message.o
$ touch src/answer.h
$ make
gcc -MMD -Wall -Wextra -pedantic -std=c11 -g -c -o src/message.o src/message.c
gcc -o msg src/main.o src/message.o
$ ./msg
The answer is 42

So we solved not only building C-projects but also 'calculated' the Answer to the Ultimate Question of Life, the Universe, and Everything. If you happen to write a program to calculate the Ultimate Question, though, I'm afraid you'd need CMake.