Multi-Directory Projects
Recursive and non-recursive Make for projects with several directories: $(MAKE) -C, module.mk includes, out-of-tree builds, static libraries, and install with PREFIX and DESTDIR.
By The Dark DebuggerUpdated 26 min read
Real projects outgrow a single directory: a library in one place, the program that uses it in
another, tests in a third. This article builds the same three-directory C project two ways,
first with a Makefile in every directory (recursive make), then with one Makefile that
includes a fragment from each directory (non-recursive make), and shows with real failures why
the second is usually the better design. Along the way we build a static library with ar,
keep all build output out of the source tree, and write install and uninstall targets that
packagers can use. You should know pattern rules,
built-in functions and
conditionals; no deep C knowledge is needed.
The project
csvstat reads a CSV file and prints the count, minimum, maximum and mean of one numeric
column. The parsing and statistics live in a small library, libstats, so other programs (and
the tests) can reuse them:
.
├── app
│ └── main.c
├── data
│ └── orders.csv
├── lib
│ ├── csv.c
│ ├── csv.h
│ ├── stats.c
│ └── stats.h
└── tests
└── test_stats.cThe finished program does this:
./build/bin/csvstat 3 < data/orders.csvcount 5 min 15.00 max 310.00 mean 118.13The dependency graph is what matters for the build. app/main.c and tests/test_stats.c
both include headers from lib/, and both programs link against libstats.a. Any change in
lib/ has to flow into the other two directories.
Recursive make: a Makefile per directory
The traditional layout gives each directory its own Makefile that only knows about that
directory, plus a top-level Makefile that runs the others. Here is lib/Makefile:
CFLAGS ?= -O2 -Wall -Wextra
libstats.a: stats.o csv.o
$(AR) rcs $@ $^
stats.o: stats.c stats.h
csv.o: csv.c csv.h
.PHONY: clean
clean:
rm -f *.o libstats.aThe object rules have no recipes: Make's built-in rule for .o from .c compiles them, and
these lines just add the header prerequisites. app/Makefile points at the library with a
relative path:
CFLAGS ?= -O2 -Wall -Wextra
CPPFLAGS += -I../lib
csvstat: main.o ../lib/libstats.a
$(CC) $(LDFLAGS) $^ -o $@
main.o: main.c ../lib/stats.h ../lib/csv.h
.PHONY: clean
clean:
rm -f *.o csvstattests/Makefile is the same shape, building test_stats and adding a check target that runs
it. The top-level Makefile only delegates:
SUBDIRS := lib app tests
.PHONY: all check clean $(SUBDIRS)
all: $(SUBDIRS)
$(SUBDIRS):
$(MAKE) -C $@
app tests: lib
check: tests
$(MAKE) -C tests check
clean:
for d in $(SUBDIRS); do $(MAKE) -C $$d clean || exit 1; doneEach directory name is a phony target whose recipe runs a second Make inside that directory.
app tests: lib says the library must be finished before either of the others starts.
makemake -C lib
make[1]: Entering directory '[…]/csvstat/lib'
cc -O2 -Wall -Wextra -c -o stats.o stats.c
cc -O2 -Wall -Wextra -c -o csv.o csv.c
ar rcs libstats.a stats.o csv.o
make[1]: Leaving directory '[…]/csvstat/lib'
make -C app
make[1]: Entering directory '[…]/csvstat/app'
cc -O2 -Wall -Wextra -I../lib -c -o main.o main.c
cc main.o ../lib/libstats.a -o csvstat
make[1]: Leaving directory '[…]/csvstat/app'
make -C tests
make[1]: Entering directory '[…]/csvstat/tests'
cc -O2 -Wall -Wextra -I../lib -c -o test_stats.o test_stats.c
cc test_stats.o ../lib/libstats.a -o test_stats
make[1]: Leaving directory '[…]/csvstat/tests'(I've shortened the absolute paths in the "Entering directory" lines.) make[1] is a Make
started by Make, one level down. -C dir changes into dir before reading its Makefile, so
every sub-make sees paths relative to its own directory.
Always $(MAKE), never make
The recipe says $(MAKE) -C $@, not make -C $@. $(MAKE) expands to the exact Make
program that is running, and it marks the line as a recursive call, so command-line flags
like -j, -k and -n are passed down properly. Here's the top-level Makefile with a plain
make in the recipe, run with two jobs:
SUBDIRS := lib app tests
.PHONY: all $(SUBDIRS)
all: $(SUBDIRS)
$(SUBDIRS):
make -C $@
app tests: libmake -j2make -C lib
make[1]: warning: jobserver unavailable: using -j1. Add '+' to parent make rule.
make[1]: Entering directory '[…]/csvstat/lib'
[…]GNU Make shares one pool of -j job slots between all levels (the jobserver). A sub-make
started through a plain make isn't connected to it and falls back to running one job at a
time. The build still worked here, but every directory was built serially.
Passing variables to sub-makes
Variables set on the command line reach every sub-make automatically, through the MAKEFLAGS
environment variable that Make sets for its children:
make CFLAGS="-O0 -g"make -C lib
make[1]: Entering directory '[…]/csvstat/lib'
cc -O0 -g -c -o stats.o stats.c
cc -O0 -g -c -o csv.o csv.c
[…]
cc -O0 -g -I../lib -c -o main.o main.c
[…]Variables set inside the top-level Makefile don't. I added CFLAGS := -O0 -g -Wall to the
top-level Makefile and ran plain make: every sub-make still compiled with its own
-O2 -Wall -Wextra. A sub-make is a separate process, and it only sees what arrives through
the environment or its command line. To pass a Makefile variable down, export it:
export CFLAGS := -O0 -g -Wallmake -C lib
make[1]: Entering directory '[…]/csvstat/lib'
cc -O0 -g -Wall -c -o stats.o stats.c
cc -O0 -g -Wall -c -o csv.o csv.c
[…]The sub-makes' CFLAGS ?= ... lines then see a value from the environment and keep it.
Another option is to pass the value explicitly on the sub-make's command line,
$(MAKE) -C $@ CFLAGS='$(CFLAGS)', which also overrides plain = assignments in the sub-make.
| Where the variable is set | Reaches sub-makes? |
|---|---|
On the command line (make CFLAGS=...) | Yes, via MAKEFLAGS, overriding sub-make assignments |
In the environment (CFLAGS=... make) | Yes, as an environment variable |
| In the parent Makefile | Only if exported, or passed on the $(MAKE) command line |
Why recursive make is considered harmful
Peter Miller's 1997 paper Recursive Make Considered Harmful gave this section its title. The argument is simple: each sub-make sees only a fragment of the dependency graph, so none of them can make correct decisions about the whole project. Two experiments show what that means.
A developer works inside app/. That's the natural thing to do in a recursive layout.
They change the library version string in lib/stats.c, then rebuild the program they're
working on:
sed -i 's/"1.0"/"1.1"/' lib/stats.c
cd app && make; ./csvstat --version; cd ..make: 'csvstat' is up to date.
csvstat 1.4 (libstats 1.0)The program is stale and Make says everything is fine. app/Makefile knows that csvstat
depends on ../lib/libstats.a, but it has no idea that the library depends on stats.c; that
knowledge lives in a different Makefile that this Make never read. Only a top-level build
fixes it:
make
./app/csvstat --versionmake -C lib
make[1]: Entering directory '[…]/csvstat/lib'
cc -O2 -Wall -Wextra -c -o stats.o stats.c
ar rcs libstats.a stats.o csv.o
make[1]: Leaving directory '[…]/csvstat/lib'
make -C app
make[1]: Entering directory '[…]/csvstat/app'
cc main.o ../lib/libstats.a -o csvstat
make[1]: Leaving directory '[…]/csvstat/app'
make -C tests
make[1]: Entering directory '[…]/csvstat/tests'
cc test_stats.o ../lib/libstats.a -o test_stats
make[1]: Leaving directory '[…]/csvstat/tests'
csvstat 1.4 (libstats 1.1)The ordering line goes missing. The cross-directory dependencies exist only in the
hand-written app tests: lib line at the top. Delete it (it's easy to forget when adding a
directory), and a serial build still works because lib comes first in SUBDIRS. A parallel
build doesn't:
make -j3make -C lib
make -C app
make[1]: Entering directory '[…]/csvstat/lib'
cc -O2 -Wall -Wextra -c -o stats.o stats.c
make -C tests
make[1]: Entering directory '[…]/csvstat/app'
cc -O2 -Wall -Wextra -I../lib -c -o main.o main.c
make[1]: Entering directory '[…]/csvstat/tests'
cc -O2 -Wall -Wextra -I../lib -c -o test_stats.o test_stats.c
make[1]: *** No rule to make target '../lib/libstats.a', needed by 'csvstat'. Stop.
make[1]: *** Waiting for unfinished jobs....
make[1]: *** No rule to make target '../lib/libstats.a', needed by 'test_stats'. Stop.
[…]
make: *** [Makefile:7: app] Error 2
ar rcs libstats.a stats.o csv.o
make[1]: Leaving directory '[…]/csvstat/lib'All three sub-makes started at once. app and tests needed the library before lib had
finished building it, and they had no rule to build it themselves. I ran this three times on a
clean tree and it failed all three times. In a bigger project the race is intermittent, which
is worse: it fails on the CI machine with more cores and never on yours.
Those are the core costs of recursive make:
- Incomplete graphs. Cross-directory dependencies are either missing (stale builds) or duplicated by hand in a top-level ordering list (which rots).
- Limited parallelism.
libmust finish completely beforeappstarts, even thoughapp/main.odoesn't need the library at all, only its headers. - Repeated work. Every sub-make starts a process, reads its Makefile and stats its files, even when nothing changed. With hundreds of directories, a no-op build takes seconds.
Recursive make is still a reasonable choice when the subdirectories are genuinely independent projects, like several services in a monorepo that share nothing at build time. For one program split across directories, use a single dependency graph.
Non-recursive make: one graph, many fragments
The non-recursive design keeps per-directory files, so each directory still describes its own
contents, but they're included into one Make instead of run as separate ones. Each directory
has a module.mk:
# lib/module.mk: the libstats static library.
LIB_SRCS := lib/stats.c lib/csv.c
LIB_OBJS := $(LIB_SRCS:%.c=$(BUILD)/%.o)
LIBSTATS := $(BUILD)/lib/libstats.a
OBJS += $(LIB_OBJS)
$(LIBSTATS): $(LIB_OBJS)
$(AR) rcs $@ $^# app/module.mk: the csvstat program.
APP_OBJS := $(BUILD)/app/main.o
OBJS += $(APP_OBJS)
PROGRAMS += $(BUILD)/bin/csvstat
$(BUILD)/bin/csvstat: $(APP_OBJS) $(LIBSTATS)
@mkdir -p $(@D)
$(CC) $(LDFLAGS) $^ -o $@# tests/module.mk: unit tests for libstats.
TEST_OBJS := $(BUILD)/tests/test_stats.o
OBJS += $(TEST_OBJS)
TESTS += $(BUILD)/tests/test_stats
$(BUILD)/tests/test_stats: $(TEST_OBJS) $(LIBSTATS)
$(CC) $(LDFLAGS) $^ -o $@And one top-level Makefile ties them together:
# csvstat: one non-recursive Makefile for lib/, app/ and tests/.
# Objects and binaries go to $(BUILD); the source tree stays clean.
BUILD ?= build
CFLAGS ?= -O2 -Wall -Wextra
CPPFLAGS += -Ilib
PREFIX ?= /usr/local
DESTDIR ?=
# The module.mk files append to these.
PROGRAMS :=
TESTS :=
OBJS :=
# Without this, the first rule in lib/module.mk would be the default goal.
.DEFAULT_GOAL := all
include lib/module.mk
include app/module.mk
include tests/module.mk
.PHONY: all check install uninstall clean
all: $(PROGRAMS) $(TESTS)
# One compile rule for every directory. -MMD -MP writes a .d file
# listing the headers each object includes.
$(BUILD)/%.o: %.c
@mkdir -p $(@D)
$(CC) $(CPPFLAGS) $(CFLAGS) -MMD -MP -c $< -o $@
-include $(OBJS:.o=.d)
check: $(TESTS)
@for t in $(TESTS); do echo "running $$t"; ./$$t || exit 1; done
install: all
install -d $(DESTDIR)$(PREFIX)/bin $(DESTDIR)$(PREFIX)/lib $(DESTDIR)$(PREFIX)/include
install -m 755 $(PROGRAMS) $(DESTDIR)$(PREFIX)/bin/
install -m 644 $(LIBSTATS) $(DESTDIR)$(PREFIX)/lib/
install -m 644 lib/stats.h lib/csv.h $(DESTDIR)$(PREFIX)/include/
uninstall:
rm -f $(DESTDIR)$(PREFIX)/bin/csvstat $(DESTDIR)$(PREFIX)/lib/libstats.a
rm -f $(DESTDIR)$(PREFIX)/include/stats.h $(DESTDIR)$(PREFIX)/include/csv.h
clean:
rm -rf $(BUILD)The rules that make this work:
- Paths are relative to the top directory, even inside
lib/module.mk. There's only one Make, and it runs from the top, so the fragment sayslib/stats.c, notstats.c. - All variables are global. Two modules that both used
SRCS :=would silently overwrite each other. Prefix module variables (LIB_,APP_,TEST_) and use+=for the shared lists (OBJS,PROGRAMS,TESTS). - Include order matters, because prerequisite lists are expanded when Make reads a rule.
app/module.mkuses$(LIBSTATS), solib/module.mkmust be included first. See Common mistakes for what happens otherwise. .DEFAULT_GOAL := all. The first time I ran this design,makebuilt the library and stopped: the first rule Make read was$(LIBSTATS)inlib/module.mk, which made it the default goal.- Header dependencies come from the compiler.
-MMD -MPmakes GCC write a.dfile next to each object, listing the headers it included, and-includereads them on the next run. Parallel Builds, Dependency Generation, and Debugging explains these flags in detail; here's one of the files:
cat build/app/main.dbuild/app/main.o: app/main.c lib/csv.h lib/stats.h
lib/csv.h:
lib/stats.h:From the top, the whole project builds with one Make and no "Entering directory" noise:
make
make
make checkcc -Ilib -O2 -Wall -Wextra -MMD -MP -c app/main.c -o build/app/main.o
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c lib/stats.c -o build/lib/stats.o
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c lib/csv.c -o build/lib/csv.o
ar rcs build/lib/libstats.a build/lib/stats.o build/lib/csv.o
cc build/app/main.o build/lib/libstats.a -o build/bin/csvstat
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c tests/test_stats.c -o build/tests/test_stats.o
cc build/tests/test_stats.o build/lib/libstats.a -o build/tests/test_stats
make: Nothing to be done for 'all'.
running build/tests/test_stats
test_stats: all tests passedThe same experiments, now correct
Edit the library and rebuild. Make knows the whole chain from stats.c to both programs:
sed -i 's/"1.0"/"1.1"/' lib/stats.c
make
./build/bin/csvstat --versioncc -Ilib -O2 -Wall -Wextra -MMD -MP -c lib/stats.c -o build/lib/stats.o
ar rcs build/lib/libstats.a build/lib/stats.o build/lib/csv.o
cc build/app/main.o build/lib/libstats.a -o build/bin/csvstat
cc build/tests/test_stats.o build/lib/libstats.a -o build/tests/test_stats
csvstat 1.4 (libstats 1.1)Only stats.o was recompiled; main.o and test_stats.o were reused and simply relinked.
Touching the header instead recompiles everything that includes it, in every directory,
thanks to the .d files:
touch lib/stats.h
makecc -Ilib -O2 -Wall -Wextra -MMD -MP -c app/main.c -o build/app/main.o
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c lib/stats.c -o build/lib/stats.o
ar rcs build/lib/libstats.a build/lib/stats.o build/lib/csv.o
cc build/app/main.o build/lib/libstats.a -o build/bin/csvstat
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c tests/test_stats.c -o build/tests/test_stats.o
cc build/tests/test_stats.o build/lib/libstats.a -o build/tests/test_statsAnd a parallel build from scratch can't race, because the graph contains the real dependencies:
make clean
make -j4rm -rf build
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c app/main.c -o build/app/main.o
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c lib/stats.c -o build/lib/stats.o
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c lib/csv.c -o build/lib/csv.o
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c tests/test_stats.c -o build/tests/test_stats.o
ar rcs build/lib/libstats.a build/lib/stats.o build/lib/csv.o
cc build/tests/test_stats.o build/lib/libstats.a -o build/tests/test_stats
cc build/app/main.o build/lib/libstats.a -o build/bin/csvstatAll four compiles ran at once, including app/main.c and tests/test_stats.c, which only need
the library's headers. The links waited for ar. That's the parallelism recursive make
couldn't give us.
You lose one thing: you can't run make inside app/ any more. Run it from the top, or from
anywhere with make -C path/to/project, and name a specific target if you only want one
program: make build/bin/csvstat.
Out-of-tree builds
Every output goes under $(BUILD), mirroring the source layout (build/lib/stats.o comes from
lib/stats.c). Two pieces make that work: the pattern rule $(BUILD)/%.o: %.c, where %
matches a path like lib/stats, and @mkdir -p $(@D), which creates the object's directory
($(@D) is the directory part of $@). The payoffs:
- The source tree never contains build products. This finds nothing:
find . -name '*.o' -not -path './build/*'make cleanisrm -rf build, and can't delete a source file by accident.- Several configurations can coexist. Because
BUILDuses?=, it's a command-line knob:
make BUILD=build-debug CFLAGS="-O0 -g -Wall -Wextra"
tree --noreport build-debugcc -Ilib -O0 -g -Wall -Wextra -MMD -MP -c app/main.c -o build-debug/app/main.o
cc -Ilib -O0 -g -Wall -Wextra -MMD -MP -c lib/stats.c -o build-debug/lib/stats.o
cc -Ilib -O0 -g -Wall -Wextra -MMD -MP -c lib/csv.c -o build-debug/lib/csv.o
ar rcs build-debug/lib/libstats.a build-debug/lib/stats.o build-debug/lib/csv.o
cc build-debug/app/main.o build-debug/lib/libstats.a -o build-debug/bin/csvstat
cc -Ilib -O0 -g -Wall -Wextra -MMD -MP -c tests/test_stats.c -o build-debug/tests/test_stats.o
cc build-debug/tests/test_stats.o build-debug/lib/libstats.a -o build-debug/tests/test_stats
build-debug
├── app
│ ├── main.d
│ └── main.o
├── bin
│ └── csvstat
├── lib
│ ├── csv.d
│ ├── csv.o
│ ├── libstats.a
│ ├── stats.d
│ └── stats.o
└── tests
├── test_stats
├── test_stats.d
└── test_stats.oThe Linux kernel offers the same thing as make O=/path/to/output, which is how people keep
one source checkout and several kernel configurations side by side.
Building and linking a static library
A static library is an archive of object files. ar rcs creates it: r inserts (or replaces)
members, c creates the archive without a warning if it's new, and s writes a symbol index
so the linker can find functions quickly. You can look inside with ar t and nm:
ar t build/lib/libstats.a
nm build/lib/libstats.astats.o
csv.o
stats.o:
0000000000000000 r .LC0
0000000000000000 T stats_version
0000000000000010 T summarize
csv.o:
U __stack_chk_fail
0000000000000000 T csv_number
U strchr
U strtodT marks a function defined in that member, U one it needs from elsewhere (here the C
library). When the program is linked, the linker copies only the members that resolve
something the program uses, straight into the executable. Nothing from libstats.a is needed
at run time, which is why install puts the archive and headers in place for other programs
to build against, not for csvstat itself.
Two linking details:
- Order matters. The linker reads inputs left to right and only pulls from an archive
what earlier inputs still need.
$^in our link rule expands tobuild/app/main.o build/lib/libstats.a, objects first, which is correct. With the archive first, you'd get "undefined reference" errors. -Land-lare the alternative spelling.-Lbuild/lib -lstatsfindslibstats.a(or a sharedlibstats.so, which the linker prefers if both exist). Listing the archive path directly, as we do, is simpler inside one project, and it lets Make see the library as a prerequisite, so a rebuilt library triggers a relink.
install and uninstall: PREFIX and DESTDIR
The GNU conventions for install targets are followed by nearly every Unix package, and
packaging tools depend on them:
PREFIX(often spelledprefix) is where the software will live when it's running:/usr/localby default,/usrfor distribution packages,/opt/nameor~/.localfor other setups. A program may bake it into the binary, for example to find its data files.DESTDIRis a staging directory prepended to every install path, and only at install time. Package builders install into an emptyDESTDIR, then archive what appeared there. It's empty by default, so a plainmake installwrites to the real paths.
The install command copies a file and sets its mode in one step (-m 755 for programs,
-m 644 for headers and libraries), and install -d creates directories. Here's a packager's
run, staging a /usr install into pkgroot/:
make install PREFIX=/usr DESTDIR=pkgroot
tree --noreport pkgrootinstall -d pkgroot/usr/bin pkgroot/usr/lib pkgroot/usr/include
install -m 755 build/bin/csvstat pkgroot/usr/bin/
install -m 644 build/lib/libstats.a pkgroot/usr/lib/
install -m 644 lib/stats.h lib/csv.h pkgroot/usr/include/
pkgroot
└── usr
├── bin
│ └── csvstat
├── include
│ ├── csv.h
│ └── stats.h
└── lib
└── libstats.auninstall must remove exactly what install put in place, using the same variables:
make uninstall PREFIX=/usr DESTDIR=pkgroot
find pkgroot -type frm -f pkgroot/usr/bin/csvstat pkgroot/usr/lib/libstats.a
rm -f pkgroot/usr/include/stats.h pkgroot/usr/include/csv.hfind printed nothing: every installed file is gone. (It leaves the directories; removing
directories that other packages may share is the package manager's job.) Keep the two targets
next to each other in the Makefile, so that whoever adds a file to one sees the other.
Note install: all. Installing builds first if needed, which is why distribution packaging
recipes boil down to make && make install DESTDIR=....
Where you'll use this
- C and C++ projects with a library and its users. Git, for example, builds all of its C
code from one large top-level Makefile, recursing only for side projects such as the
documentation and test suite, and installs with the same
prefix/DESTDIRconventions you just used. - Linux distribution packaging. Debian and RPM build recipes run the project's
make install DESTDIR=<staging dir>and package whatever lands there. A Makefile that ignoresDESTDIRis the first thing a packager has to patch. - Monorepos of independent services. Here recursive make is fine: a top-level Makefile
with
$(MAKE) -C services/billing testgives one entry point to projects that don't share build outputs. Make as a Task Runner covers that style. - Large trees with generated code. One graph means a generated header in one directory is built before anything in any other directory includes it, with no hand-written ordering.
Here is the complete flow a CI job or package build runs for this project, from a clean tree to a staged install:
make clean && make -j4 && make check && make install PREFIX=/usr DESTDIR=pkgrootrm -rf build
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c lib/stats.c -o build/lib/stats.o
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c app/main.c -o build/app/main.o
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c lib/csv.c -o build/lib/csv.o
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c tests/test_stats.c -o build/tests/test_stats.o
ar rcs build/lib/libstats.a build/lib/stats.o build/lib/csv.o
cc build/tests/test_stats.o build/lib/libstats.a -o build/tests/test_stats
cc build/app/main.o build/lib/libstats.a -o build/bin/csvstat
running build/tests/test_stats
test_stats: all tests passed
install -d pkgroot/usr/bin pkgroot/usr/lib pkgroot/usr/include
install -m 755 build/bin/csvstat pkgroot/usr/bin/
install -m 644 build/lib/libstats.a pkgroot/usr/lib/
install -m 644 lib/stats.h lib/csv.h pkgroot/usr/include/Common mistakes
The default goal is a library
Covered above, but worth repeating because it happens the moment you start including module
files. Without .DEFAULT_GOAL := all, my first non-recursive build did this:
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c lib/stats.c -o build/lib/stats.o
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c lib/csv.c -o build/lib/csv.o
ar rcs build/lib/libstats.a build/lib/stats.o build/lib/csv.oand a second make printed make: 'build/lib/libstats.a' is up to date. No error, just a
build that quietly did a third of the work. Set .DEFAULT_GOAL, or put an empty all: rule
before the first include.
Including modules in the wrong order
I swapped the includes so that app/module.mk came before lib/module.mk:
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c app/main.c -o build/app/main.o
cc build/app/main.o -o build/bin/csvstat
[…]/ld: build/app/main.o: in function `main':
main.c:(.text.startup+0x9d): undefined reference to `csv_number'
[…]/ld: main.c:(.text.startup+0xbc): undefined reference to `summarize'
[…]/ld: main.c:(.text.startup+0x118): undefined reference to `stats_version'
collect2: error: ld returned 1 exit status
make: *** [app/module.mk:8: build/bin/csvstat] Error 1Look at the link line: there's no library on it. When Make read the rule
$(BUILD)/bin/csvstat: $(APP_OBJS) $(LIBSTATS), LIBSTATS wasn't defined yet, so it expanded
to nothing, and prerequisite lists are expanded immediately. "Undefined reference" with a
suspiciously short link line almost always means a variable was empty when the rule was read.
Include modules in dependency order (libraries first), or define shared names like LIBSTATS
in the top-level Makefile before any include.
"No rule to make target '../lib/libstats.a'"
In a recursive build this means a sub-make needed a file that another directory produces, and
that directory hadn't produced it yet. Usually it's a missing ordering line at the top
(app: lib) exposed by -j, as shown earlier. Adding the line fixes the symptom; moving to a
single graph fixes the cause.
"Permission denied" from make install
make installinstall -d /usr/local/bin /usr/local/lib /usr/local/include
install -m 755 build/bin/csvstat /usr/local/bin/
install: cannot create regular file '/usr/local/bin/csvstat': Permission denied
make: *** [Makefile:38: install] Error 1/usr/local belongs to root. Either install somewhere you own (make install PREFIX=$HOME/.local)
or build as yourself and install with sudo make install. Don't run the whole build with
sudo: root-owned files in build/ will then break your next normal build.
Summary
- Recursive make runs
$(MAKE) -C dirper directory. Always use$(MAKE)so-jand other flags (and the shared jobserver) reach the sub-makes. - Command-line variables reach sub-makes automatically; Makefile variables only if
exported or passed on the$(MAKE)line. - Each recursive sub-make sees a fragment of the graph: building inside one directory misses
changes elsewhere, and cross-directory ordering must be written by hand and breaks under
-j. - Non-recursive make
includes amodule.mkper directory into one graph. Paths are relative to the top, variables are global (prefix them), includes go in dependency order, and.DEFAULT_GOALmust be set. - A
$(BUILD)/%.o: %.crule withmkdir -p $(@D)gives out-of-tree builds;BUILD=...on the command line gives separate trees per configuration. ar rcsbuilds a static library; list objects before archives when linking, and list the archive as a prerequisite so a changed library triggers a relink.installhonoursPREFIX(where it will run) andDESTDIR(a staging root for packaging);uninstallremoves exactly the same files.
Exercises
Without editing anything, build the tests into build/debug with -O0 -g and run them, in a
single command. Which files are compiled, and which aren't?
Show Solution
make check BUILD=build/debug CFLAGS="-O0 -g -Wall -Wextra"cc -Ilib -O0 -g -Wall -Wextra -MMD -MP -c tests/test_stats.c -o build/debug/tests/test_stats.o
cc -Ilib -O0 -g -Wall -Wextra -MMD -MP -c lib/stats.c -o build/debug/lib/stats.o
cc -Ilib -O0 -g -Wall -Wextra -MMD -MP -c lib/csv.c -o build/debug/lib/csv.o
ar rcs build/debug/lib/libstats.a build/debug/lib/stats.o build/debug/lib/csv.o
cc build/debug/tests/test_stats.o build/debug/lib/libstats.a -o build/debug/tests/test_stats
running build/debug/tests/test_stats
test_stats: all tests passedcheck only depends on the test program, so app/main.c wasn't compiled: Make builds exactly
the part of the graph the goal needs, across directories. The release objects in build/ were
untouched.
Add a tools/ directory with a second program, csvcount, that prints how many rows have a
number in a given column. It uses csv_number() from the library. Make it build with
make, without touching lib/ or app/. Here's the program:
#include <stdio.h>
#include <stdlib.h>
#include "csv.h"
/* Count the rows whose COLUMN holds a number. */
int main(int argc, char **argv)
{
if (argc != 2) {
fprintf(stderr, "usage: csvcount COLUMN < file.csv\n");
return 2;
}
int col = atoi(argv[1]);
char line[4096];
double v;
long n = 0;
while (fgets(line, sizeof line, stdin))
if (csv_number(line, col, &v) == 0)
n++;
printf("%ld\n", n);
return 0;
}Show Solution
tools/module.mk:
# tools/module.mk: csvcount, a second program built on libstats.
TOOLS_OBJS := $(BUILD)/tools/csvcount.o
OBJS += $(TOOLS_OBJS)
PROGRAMS += $(BUILD)/bin/csvcount
$(BUILD)/bin/csvcount: $(TOOLS_OBJS) $(LIBSTATS)
@mkdir -p $(@D)
$(CC) $(LDFLAGS) $^ -o $@and one line in the top-level Makefile, after the library's include:
include tests/module.mk
include tools/module.mkmake
./build/bin/csvcount 3 < data/orders.csvcc -Ilib -O2 -Wall -Wextra -MMD -MP -c app/main.c -o build/app/main.o
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c lib/stats.c -o build/lib/stats.o
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c lib/csv.c -o build/lib/csv.o
ar rcs build/lib/libstats.a build/lib/stats.o build/lib/csv.o
cc build/app/main.o build/lib/libstats.a -o build/bin/csvstat
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c tools/csvcount.c -o build/tools/csvcount.o
cc build/tools/csvcount.o build/lib/libstats.a -o build/bin/csvcount
cc -Ilib -O2 -Wall -Wextra -MMD -MP -c tests/test_stats.c -o build/tests/test_stats.o
cc build/tests/test_stats.o build/lib/libstats.a -o build/tests/test_stats
5The shared compile rule, header tracking and install (through $(PROGRAMS)) all picked up
the new program automatically. Adding a directory is a new five-line file plus one include.
Back in the recursive version, change app/Makefile so that running make inside app/
after editing lib/stats.c rebuilds the library and relinks csvstat. Then explain what this
does not fix.
Hint
app/Makefile can't know when the library is out of date, but lib/Makefile can. Give the
library a rule in app/Makefile that always asks lib/ to bring it up to date.
Show Solution
CFLAGS ?= -O2 -Wall -Wextra
CPPFLAGS += -I../lib
csvstat: main.o ../lib/libstats.a
$(CC) $(LDFLAGS) $^ -o $@
main.o: main.c ../lib/stats.h ../lib/csv.h
# Let lib/Makefile decide whether the library is up to date.
../lib/libstats.a: FORCE
$(MAKE) -C ../lib
.PHONY: clean FORCE
clean:
rm -f *.o csvstatsed -i 's/"1.0"/"1.1"/' lib/stats.c
cd app && make; ./csvstat --version; cd ..make -C ../lib
make[1]: Entering directory '[…]/csvstat/lib'
cc -O2 -Wall -Wextra -c -o stats.o stats.c
ar rcs libstats.a stats.o csv.o
make[1]: Leaving directory '[…]/csvstat/lib'
cc main.o ../lib/libstats.a -o csvstat
csvstat 1.4 (libstats 1.1)FORCE is an empty phony target, so the library's recipe runs every time and delegates the
decision to lib/Makefile; Make then re-checks the archive's timestamp and relinks only if it
changed. What it doesn't fix: tests/Makefile needs the same patch, every build now pays for an
extra sub-make, and in a parallel top-level build app and tests can each start a
make -C ../lib at the same moment, two Makes writing the same files. Patching recursive make
tends to go like this, one workaround per symptom.
Other projects find libraries through pkg-config files. Create lib/libstats.pc.in:
prefix=@PREFIX@
libdir=${prefix}/lib
includedir=${prefix}/include
Name: libstats
Description: Summary statistics for CSV columns
Version: 1.1
Libs: -L${libdir} -lstats
Cflags: -I${includedir}Extend install to write libstats.pc into lib/pkgconfig/ under the install prefix, with
@PREFIX@ replaced. Test with PREFIX=/opt/csvstat DESTDIR=pkgroot. Which of the two
variables belongs in the file, and why?
Show Solution
Two lines at the end of the install recipe:
install -d $(DESTDIR)$(PREFIX)/lib/pkgconfig
sed 's|@PREFIX@|$(PREFIX)|' lib/libstats.pc.in > $(DESTDIR)$(PREFIX)/lib/pkgconfig/libstats.pcmake install PREFIX=/opt/csvstat DESTDIR=pkgroot
cat pkgroot/opt/csvstat/lib/pkgconfig/libstats.pcinstall -d pkgroot/opt/csvstat/bin pkgroot/opt/csvstat/lib pkgroot/opt/csvstat/include
install -m 755 build/bin/csvstat build/bin/csvcount pkgroot/opt/csvstat/bin/
install -m 644 build/lib/libstats.a pkgroot/opt/csvstat/lib/
install -m 644 lib/stats.h lib/csv.h pkgroot/opt/csvstat/include/
install -d pkgroot/opt/csvstat/lib/pkgconfig
sed 's|@PREFIX@|/opt/csvstat|' lib/libstats.pc.in > pkgroot/opt/csvstat/lib/pkgconfig/libstats.pc
prefix=/opt/csvstat
libdir=${prefix}/lib
includedir=${prefix}/include
Name: libstats
Description: Summary statistics for CSV columns
Version: 1.1
Libs: -L${libdir} -lstats
Cflags: -I${includedir}(csvcount is there because I did this on top of Exercise 2.) The file contains PREFIX
only. DESTDIR is a temporary staging location that disappears once the package is built; a
path containing it would point at a directory that doesn't exist on the machine where the
package is installed. The location of the file uses both, the content uses PREFIX. The
| delimiter in the sed expression avoids clashing with the slashes in the path. Remember to
add a matching rm -f line to uninstall.
Tested with: GNU Make 4.3, GCC 13.3.0 and GNU binutils 2.42 (ar, nm) on Ubuntu 24.04
(WSL2), November 2026. Every Makefile and command above was run as shown. I shortened the
absolute paths in Make's "Entering directory" lines and the linker's path to […], and
trimmed repeated sub-make output where marked. The parallel recursive build failed the same way
on three runs out of three on an 8-core machine; on yours the interleaving of lines will
differ. sudo make install and PREFIX=$HOME/.local were not run, to keep the test machine's
system directories untouched.
Written by The Dark Debugger
Engineer documenting the things that took me too long to learn, so they take you less time. Every Makefile tutorial here is tested end to end before publishing.