Scrolls
6 min read
On this page

Makefiles & Build Systems

As a C project grows beyond a handful of files, typing compiler commands by hand becomes impractical. Build systems automate compilation, track dependencies, and rebuild only what has changed. Make is the classic tool. CMake and Meson are modern alternatives that generate build files for you. Understanding build systems is not optional — every serious C project uses one.

Make Fundamentals

Make reads a file called Makefile that describes how to build your project. A Makefile consists of rules, each with a target, dependencies, and a recipe.

target: dependencies
	recipe

The recipe lines must be indented with a tab character, not spaces. This is the most common Makefile syntax error.

A Minimal Makefile

program: main.o utils.o parser.o
	gcc -o program main.o utils.o parser.o

main.o: main.c utils.h parser.h
	gcc -c main.c

utils.o: utils.c utils.h
	gcc -c utils.c

parser.o: parser.c parser.h utils.h
	gcc -c parser.c

Running make builds the first target (program). Make checks timestamps: if main.c is newer than main.o, it recompiles main.o. If main.o is newer than program, it relinks. This is incremental building — only changed files are reprocessed.

How Make Decides What to Rebuild

Make compares the modification time of each target against its dependencies. If any dependency is newer than the target, the recipe runs. If all dependencies are older, the target is up to date and nothing happens.

$ touch main.c     # Update main.c timestamp
$ make
gcc -c main.c      # Only main.o is rebuilt
gcc -o program main.o utils.o parser.o  # Relink because main.o changed

Automatic Variables

Make provides special variables to avoid repeating file names.

program: main.o utils.o parser.o
	gcc -o $@ $^

%.o: %.c
	gcc -c $< -o $@
  • $@ — the target name (program or the .o file)
  • $< — the first dependency (main.c, utils.c, etc.)
  • $^ — all dependencies (all .o files for the program target)

Pattern Rules

The %.o: %.c rule is a pattern rule. The % matches any stem, so this single rule replaces separate rules for every .c file. When Make needs utils.o, it matches the pattern with % = utils, checks if utils.c exists, and runs the recipe.

A Production Makefile

A realistic Makefile for a C project uses variables for compiler flags, tracks header dependencies automatically, and includes phony targets for cleaning.

CC = gcc
CFLAGS = -Wall -Wextra -Wpedantic -std=c17 -g
LDFLAGS =
LDLIBS = -lm

SRCS = main.c utils.c parser.c network.c
OBJS = $(SRCS:.c=.o)
DEPS = $(SRCS:.c=.d)
TARGET = program

.PHONY: all clean

all: $(TARGET)

$(TARGET): $(OBJS)
	$(CC) $(LDFLAGS) -o $@ $^ $(LDLIBS)

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

clean:
	rm -f $(OBJS) $(DEPS) $(TARGET)

-include $(DEPS)

The -MMD -MP flags tell GCC to generate dependency files (.d) that list which headers each .c file includes. The -include $(DEPS) line tells Make to read those files. Now if you change a header, Make knows which object files depend on it and rebuilds them.

Phony Targets

A phony target does not correspond to a file. The .PHONY declaration tells Make not to check for a file with that name.

.PHONY: all clean test install

all: $(TARGET)

clean:
	rm -f $(OBJS) $(DEPS) $(TARGET)

test: $(TARGET)
	./run_tests.sh

install: $(TARGET)
	cp $(TARGET) /usr/local/bin/

Without .PHONY, if a file named clean existed in the directory, make clean would say "clean is up to date" and do nothing.

Variables & Conventions

CC = gcc          # C compiler
CXX = g++         # C++ compiler
CFLAGS = -Wall -g # C compiler flags
CXXFLAGS = -Wall  # C++ compiler flags
LDFLAGS = -L/usr/local/lib  # Linker search paths
LDLIBS = -lm -lpthread      # Libraries to link

These variable names are conventions understood by Make's built-in rules. If you use them consistently, your Makefile works with implicit rules and other developers know what each variable controls.

CMake: The Modern Build System Generator

CMake does not build your code directly. It generates build files for other systems: Makefiles on Linux, Xcode projects on macOS, Visual Studio solutions on Windows. This makes CMake the standard choice for cross-platform C projects.

A Minimal CMakeLists.txt

cmake_minimum_required(VERSION 3.16)
project(myproject C)

set(CMAKE_C_STANDARD 17)
set(CMAKE_C_STANDARD_REQUIRED ON)

add_compile_options(-Wall -Wextra -Wpedantic)

add_executable(program
    main.c
    utils.c
    parser.c
    network.c
)

target_link_libraries(program m pthread)

Building with CMake:

mkdir build
cd build
cmake ..
make

CMake generates a Makefile in the build directory. The source tree stays clean. Out-of-source builds are one of CMake's key advantages over plain Make.

CMake Libraries

add_library(mylib STATIC
    utils.c
    parser.c
)

add_executable(program main.c)
target_link_libraries(program mylib)

CMake handles the ar commands for static libraries and the -fPIC and -shared flags for shared libraries automatically. You describe what you want, not how to build it.

Finding External Libraries

find_package(OpenSSL REQUIRED)
target_link_libraries(program OpenSSL::SSL OpenSSL::Crypto)

CMake's find_package searches for installed libraries and sets up include paths and linker flags. This is significantly easier than manually specifying -I and -L paths.

Meson: A Newer Alternative

Meson is a build system designed for speed and simplicity. It uses a Python-like syntax and generates Ninja build files (which are faster than Make).

project('myproject', 'c',
    default_options: ['c_std=c17', 'warning_level=3'])

src = files('main.c', 'utils.c', 'parser.c', 'network.c')

executable('program', src,
    dependencies: [dependency('threads')])

Building with Meson:

meson setup build
cd build
ninja

Meson enforces out-of-source builds, handles cross-compilation well, and has excellent dependency management. It is used by projects like GNOME, systemd, and Mesa.

Why Build Systems Matter

Reproducibility

A Makefile or CMakeLists.txt is a complete, executable description of how to build the project. Any developer on any machine can clone the repository and build the project with one command. Without a build system, build instructions are tribal knowledge.

Incremental Builds

Recompiling one file out of hundreds takes seconds. Recompiling everything takes minutes. Build systems track what changed and rebuild only what is necessary. For large projects, this is the difference between a productive workflow and constant waiting.

Cross-Platform Support

CMake and Meson generate platform-specific build files from a single description. One CMakeLists.txt produces Makefiles on Linux, Xcode projects on macOS, and MSBuild files on Windows. Without a portable build system, you maintain separate build configurations per platform.

Dependency Management

Build systems track which source files depend on which headers. When you change a header, only the source files that include it are recompiled. Manual compilation misses these dependencies and produces stale object files with mismatched declarations.

A Real-World Build Example

A project with a library, an executable, and tests:

CC = gcc
CFLAGS = -Wall -Wextra -Wpedantic -std=c17 -g
AR = ar

SRCS_LIB = src/parser.c src/utils.c src/network.c
OBJS_LIB = $(SRCS_LIB:.c=.o)

SRCS_MAIN = src/main.c
OBJS_MAIN = $(SRCS_MAIN:.c=.o)

SRCS_TEST = tests/test_parser.c tests/test_utils.c
OBJS_TEST = $(SRCS_TEST:.c=.o)

.PHONY: all clean test

all: program

libproject.a: $(OBJS_LIB)
	$(AR) rcs $@ $^

program: $(OBJS_MAIN) libproject.a
	$(CC) $(LDFLAGS) -o $@ $^ $(LDLIBS)

test_runner: $(OBJS_TEST) libproject.a
	$(CC) $(LDFLAGS) -o $@ $^ $(LDLIBS)

test: test_runner
	./test_runner

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

clean:
	rm -f $(OBJS_LIB) $(OBJS_MAIN) $(OBJS_TEST) libproject.a program test_runner
	rm -f $(SRCS_LIB:.c=.d) $(SRCS_MAIN:.c=.d) $(SRCS_TEST:.c=.d)

-include $(SRCS_LIB:.c=.d) $(SRCS_MAIN:.c=.d) $(SRCS_TEST:.c=.d)

This Makefile builds a static library from shared code, links it into both the main program and the test runner, tracks header dependencies automatically, and cleans up all generated files.

Common Pitfalls

  • Spaces instead of tabs — Make requires tab characters for recipe indentation. Spaces cause cryptic "missing separator" errors. Configure your editor to use tabs in Makefiles.
  • Missing header dependencies — Without -MMD or manual dependency tracking, changing a header does not trigger recompilation of files that include it. This leads to subtle bugs from stale object files.
  • Library link order — Libraries must come after the object files that reference them. gcc main.o -lm works; gcc -lm main.o may not find math symbols.
  • Not using out-of-source builds — Building in the source tree mixes generated files with source files. CMake and Meson enforce out-of-source builds. With Make, create a build/ directory and adjust paths.
  • Hardcoding compiler paths — Use $(CC) instead of gcc so the build works with different compilers. Set CC=clang to switch compilers without editing the Makefile.
  • Ignoring build system warnings — CMake deprecation warnings and Make error messages indicate real problems. Fix them rather than adding flags to suppress them.

Key Takeaways

  • Make automates compilation using rules with targets, dependencies, and recipes. It rebuilds only what has changed by comparing file timestamps.
  • Automatic variables ($@, $<, $^) and pattern rules (%.o: %.c) eliminate repetition in Makefiles.
  • Phony targets (clean, all, test) run commands rather than building files. Always declare them with .PHONY.
  • CMake generates platform-specific build files from a single CMakeLists.txt. It is the standard for cross-platform C projects.
  • Meson is a faster, simpler alternative to CMake that generates Ninja build files.
  • Build systems provide reproducibility, incremental builds, cross-platform support, and automatic dependency tracking. Every C project beyond a single file needs one.