The case against Makefiles

Aside: Build scripts, makefiles, and other build systems

Consider a script that builds a pile of source files (without using any fancy shell features that would have been unavailable in 1976)

#!/bin/sh

CFLAGS="-Wall"

# Compile the individual source files to object files
cc $CFLAGS -c -o main.o main.c
cc $CFLAGS -c -o lib.o lib.c

# Link the object files into an executable
cc -o app main.o lib.o

Forget to add a cc command to build a source file? Now you’re linking with an old version of the file that you compiled by hand.

Using modern bash features, you could improve the script significantly.

#!/bin/bash

CFLAGS="-Wall"
SRCS = "main.c lib.c"
OBJS = ${SRCS/.c/.o}

for file in $SRCS; do
        cc $CFLAGS -c -o ${file/.c/.o} $file
done

cc -o app $OBJS

Using a bash variable expansion to replace .c with .o allows us to use re-use the list of sources in both the compile commands and the linker command. For a small example program, this approach works, but it doesn’t scale well.

An equivalent makefile would be

CFLAGS = -Wall
SRCS = main.c lib.c
OBJS = $(SRCS:.c=.o)

app: $(OBJS)
        $(CC) -o $@ $(OBJS)

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

The similarities are quite obvious. The most significant difference between the script and the makfile is what we describe. The script is an imperative procedure: it lays out the steps that need to be accomplished to build the final binary, and executes them all in sequence, every time. The makefile describes the dependencies between inputs and outputs. This allows the makefile to skip steps that are redundant because the input has not changed.

The cost of this change is syntax. The build script is quite readable but the makefile is full of _magic_ tokens. What are $@, and $<? To an experienced practitioner, they are obvious. For me, they require a trip to google each time (or if I actually remember, a trip into The Sum of All Knowledge, my knowledgebase in`Obsidian`_).

Compare this with an equivalent CMake script

cmake_minimum_required(VERSION 3.10)
project(app C)

add_executable(app main.c lib.c)

Without knowing anything about CMake, the goal of the script is quite clear. The knowledge of how to actually build an executable or a library is hidden which is a shame, but the intent is clear.

Make’s mistake

The fundamental mistake of Make is that it describes the edges of the build graph, not the nodes. It describes the operations required to transform one file into another, but never describes the goal of the transformation.

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

To build a file, we say that there exists a node %.c and a node %.o, and that to go from %.c to %.o, it is necessary to apply $(CC) $(CFLAGS) -c -o $@ $< to %.c. A no point does this say anything about what we are trying to achieve.

In CMake, to build an executable, we use add_executable(app main.c lib.c). This describes the end goal, not the transformation. This is not to say that CMake is the perfect build-system, far from that, but it is at least easier to follow.

Build-systems that describe intent, and not transformations, have one property that most Makefiles in the wild lack: they work reliably when run in parallel. Most makefiles I have had the misfortune of encountering fail when run in parallel. To build reliably, build scripts become

make -j$(nproc) all || make -j$(nproc) all || make -j$(nproc) all

This is definitely a skill issue. But a tool too complicated for the average C programmer inside a boring company is no longer a good tool.

Re-inventing the wheel with make

Make aficionados love to tell new victims how great their makefiles are: they are invariably better than whatever sub-par build system they have begrudgingly accepted to use at their workplace.

However, if my experience is representative, their makefiles still suffer from the edges-not-nodes issue discussed above, but more problematically: they have accumulated just as much complexity as other build systems, whilst having written none of the documentation that would be required to explain their bespoke build system to others.

Need to add a new library target? Need to add a custom target for code-generation, doxygen, a formatter, a linter, … ? jump on a call and ask them to walk you though it.

And after all that, you still end up rm -rf build/ at every other build because you don’t trust the damn thing …

And because it doesn’t actually work when run in parallel, the compile times are agonising …