• GNU Make Manual.
• Recursive Make Considered Harmful, Peter Miller, 1998.
• Auto-Dependency Generation, Paul D. Smith, 2017.
• Makefile, Anonymous rm command executed at last, StackOverflow
• Writing a large build system with GNU make, by David Rothlisberger.
• Implementing non-recursive make, Emile van Bergen.

A Makefile describes how your program is built by specifying everything that it depends on and building the dependencies first. A Makefile rule looks like this:

target_1 ... target_n: prerequisite_1 ... prerequisite_m
<tab>   command_1   # NOTE that each command
<tab>   ...         # is executed in its own
<tab>   command_j   # subshell.

Here:

• Target is anything the must be made.
• Prerequisite are things that must be built before the target can be built.
• Commands are shell commands used to build the target. NOTE, each command executed in own subshell!
• Rule is what's shown above - it defines how to build a target.

To perform a build, make will construct a directed acyclic graph (DAG) from the rules. It will then do a post order traversal (visit children first), building the leaf nodes first and going back up the graph.

A very simple example is shown below:

The makefile for the above diagram would look something like this:

target: prequisite_1 prequisite_1 prequisite_1
<tab>   commands_A

prequisite_1: prequisite_4
<tab>   commands_B

prequisite_2: prequisite_5
<tab>   commands_C

prequisite_3: prequisite_5 prequisite_7
<tab>   commands_D

prequisite_4:
<tab>   commands_E

prequisite_5: prequisite_6
<tab>   commands_F

prequisite_6:
<tab>   commands_G

prequisite_7:
<tab>   commands_H

The post-order traversal is shown by the orange-background numbers.

1. Make looks at target and visits the first child, prerequisit_1. It can see that prerequisit_1 depends on prerequisit_4. So now, prerequisit_1 becomes the "target". If make determines that prerequisit_1 is newer than prerequisit_4, it will build prerequisit_4. We assume that it does and builds prerequisit_4 using commands_E.
2. Once prerequisit_4 is built, all of prerequisit_1's dependencies have been visited so prerequisit_1 can now be built using commands_B.
3. Make returns back to target and examines the next dependency, prerequisit_2. Assuming prerequisit_5 is older than prerequisit_2, and prerequisit_6 is older than prerequisit_5, the post-order traversal will result in make next trying to build prerequisit_6 using commands_F.
4. All of prerequisit_5's dependencies have been built so make can now build prerequisit_5 using commands_F.
5. All of prerequisit_2's dependencies have been built so make can now build prerequisit_2 using commands_C.
6. Make returns back to target and examines the next dependency prerequisit_3. There are two dependencies, prerequisit_5 and prerequisit_7. Make has already built prerequisit_5 so it knows that it does not need to build this again, so it ignores this path... nice! Thus all that is left is to look at prerequisit_7, assuming it is older than prerequisit_3. Assume it is, so make builds it.
7. All of prerequisit_3's dependencies have been built so it can now be built.
8. Make returns back to target and because all of its dependencies have been built, it can finally be built.

By doing this kind of traversal make ensures that everything that is need to be built is built, but not more than this. I.e., if some dependencies do not need to be refreshed, they are not rebuilt, helping to produce an efficient build. It is also the case that targets that are as new as all of their dependencies are not rebuilt.

The basic make process can be described like this:

• Make finds files indicated by the targets and prerequisites.
• If a prerequisite has a rule associated with it (i.e., make is looking at the rule target: prerequisite and the rule prerequisite: dependencies exists), make will try to update the prerequisite first.
• When considering a target, if any prerequisite is newer than the target, make will attempt to make the prequisite(s) first.

PHONY targets

How Make Locates Source Files: VPATH & vpath

VPATH = dir1 dir2 dir3 ...

vpath pattern dir-list

vpath %.h include
vpath %.c src

Make Phases

This is just a summary of some of the more commonly used automatic variables. You can find a complete list here. The automatic variables do not have very user-friendly names so I have a few memory pegs I try to use to recall what they all mean...

In the example makefile in the introduction section, each target was explicitly written down. This would be fine for a small project, but if you have more than a few source files, listing each one independently will soon get tedious and error prone. Most of the time we just want to say "and object file is generated from a c/c++ source file with the same file base name". And luckily we can... to say this we would write something like the following.

%.o: %.cpp
<tab>   ...Commands...

my-target: fileA.o fileB.o ... fileZ.o

In the above example, Make knows that to build my-target it must build the object files fileA.o through fileZ.o. So, how does it construct these objects? It looks through all of the rules it has encountered so far and tries to match each file?.o with a target. It finds %.o, where % is a wild card. The % matches the portion file? of the prerequisite (this portion is called the stem), so Make can use this rule to construct the object file.

Lets take fileA.o as an example. Make will search for the file. If the file is as new or newer than the target it knows that this prerequisite does not need to be rebuilt. However, if it does, Make searches for a rule that will tell it how to build the prerequisite.

Make finds the rule %.o: %.c; commands: fileA.o matches %.o, where the % matches fileA. The prerequisite for this rule specified %.c, which substituting in the match will become fileA.c. As long as fileA.c is just a file and not generated by some other tool, Make will find no rule to create this file, so if the file doesn't exist, then Make reports an error, otherwise it will rebuild fileA.c if it is newer than the target fileA.o.

If two or more rules match Make will prefer more specific rules over more generic ones.

Limiting Scope Of Pattern Rules

$(OBJECTS) : %.o : %.c

Implicit Rules

make -p -q | vim -
      ^  ^
      ^  Don't execute any commands
      Print rule database

OUTPUT_OPTION = -o $@

LINK.c = $(CC) $(CFLAGS) $(CPPFLAGS) $(LDFLAGS) $(TARGET_ARCH)
LINK.o = $(CC) $(LDFLAGS) $(TARGET_ARCH)

LINK.cpp = $(LINK.cc)
LINK.cc = $(CXX) $(CXXFLAGS) $(CPPFLAGS) $(LDFLAGS) $(TARGET_ARCH)

COMPILE.cpp = $(COMPILE.cc)
COMPILE.cc = $(CXX) $(CXXFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c
COMPILE.c = $(CC) $(CFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c

%: %.o
        $(LINK.o) $^ $(LOADLIBES) $(LDLIBS) -o $@

%: %.c
        $(LINK.c) $^ $(LOADLIBES) $(LDLIBS) -o $@

%.o: %.c
        $(COMPILE.c) $(OUTPUT_OPTION) $<

So, if a Makefile has a rule file1.o: file1.c, Make will find the rule %.o: %.c and execute the rule $(COMPILE.c) $(OUTPUT_OPTION) $<. This expands to $(CC) $(CFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c -o $@ $<, which expands to $(CC) $(CFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c -o file1.o file1.c.

So, what do the variables such as CFLAGS and CPPFLAGS expand to? These must be set by the makefile creator to meet the needs of their compilation!

Naming conventions

Constants or environment variables in upper snake case.

Variables internam to the make file, lower snake case.

Types

Variables are either simple expanded or recursively expanded.

Simple Expanded

Simple expanded variables are declared like so:

SIMPLE_EXPANDED := some-value
#               ^^
#               Note the colon before the equals!
#               some-value is expanded IMMEDIATELY upon reading this line

Simple expanded variables have their RHS expression expanded immediately upon being encountered, during the 1st make phase, and have the value of the expansion assigned to the variable.

Recursively Expanded

Recursively expanded variables are declared like so:

RECUSIVE_EXPANDED = some-value
#              ^^
#              Note ONLY the equals!
#              some-value is not expanded. just stored as-is in the variable without evaluating it!

A recusively expanded variable just has the RHS stored as-is in the variable without any evaluation what so ever. The value is only ever expanded when the variable is USED.

When Expansion Occurs

• LHS of variable assignments immediately expanded
• RHS of = and ?= expansion deferred until second phase
• RHS of := immediately expanded
• RHS of += immediately expanded for variables declared with :=, otherwise expansion/evaluation deferred until use
• Rule targets and prerequisites immediately expanded. Commands deferred.

Target Specific Variables

Can append to or create variables specifically for a given target:

target: my_variable (=|:=|?=|+=) value
target: prerequisites
<tab>    commands
#        ^^
#        my_variable now has a value specific to this target.

Can include functionality from other Makefiles into the main Makefile using the include directive. Importantly if any include file is updated by a file, make clears its internal database and re-reads the entire makefile! This is especially important for dependency generation.

The flow of logic that dictates when a Makefile is re-processed due to a rule-based update to an include target is shown below:

This process is especially important for dependency generation which is covered in its own section.

Notes taken from this article.

DEPDIR := .deps
DEPFLAGS = -MT $@   -MMD   -MP   -MF $(DEPDIR)/$*.d
#          ^^^^^^   ^^^^   ^^^   ^^^^^^^^^^^^^^^^^^
#          ^^^^^^   ^^^^   ^^^   Specify files to write the dependencies to
#          ^^^^^^   ^^^^   ^^^
#          ^^^^^^   ^^^^   Instructs CPP to add a phony target for each dependency
#          ^^^^^^   ^^^^   other than the main file, causing each to depend on nothing.
#          ^^^^^^   ^^^^   These dummy rules work around errors make gives if you remove
#          ^^^^^^   ^^^^   header files without updating the Makefile to match.
#          ^^^^^^   ^^^^
#          ^^^^^^   Instead of outputting the result of preprocessing, output a rule
#          ^^^^^^   suitable for make describing the dependencies of the main source
#          ^^^^^^   file. Do NOT include system header files as dependencues.
#          ^^^^^^   AND
#          ^^^^^^   Generate dependency information as a side-effect of compilation, 
#          ^^^^^^   not instead of compilation.
#          ^^^^^^
#          Change target of generated rule to $@ rather than the default that would 
#          otherwise be the name of the main input file with directories deleted and
#          suffix replaced with platform specific object suffix.

COMPILE.c = $(CC) $(DEPFLAGS) $(CFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c

%.o : %.c
%.o : %.c $(DEPDIR)/%.d | $(DEPDIR)
        $(COMPILE.c) $(OUTPUT_OPTION) $<

$(DEPDIR): ; @mkdir -p $@

DEPFILES := $(SRCS:%.c=$(DEPDIR)/%.d)
$(DEPFILES):

include $(wildcard $(DEPFILES))
# ^^
# As seen in prev section if any of the include targets (i.e., the DEPFILES) were 
# updated by the rules the makefile is reloaded with a cleared db.

CMake calls this sort of the out-of-source-builds. Need these to cope with multiple targets and multiple builds per target, for example. To accomplish need to have source and output binaries in separate locations!