As most projects just copy theirs from another project or a “one-size-fits all” makefile in order to get it to work - or even worse, generate one - that comes as no surprise.

These heirlooms are often huge, hard to read and near-impossible to debug, thereby contributing a great deal to make’s reputation as a bad build system in some circles and scaring away people interested in learning how things work.

The biggest source of trouble and complexities is the variety of implementations of the basic makefile convention, resulting in different feature sets being supported across systems. This can be circumvented by concentrating on the GNU implementation of make, which is supported on pretty much any system and provides arguably the widest range of features.

Other than that, I have been very happy with a broadly supported, minimally intrusive build system that has stood the tests of time and is still considered by many to be THE major build automation tool there is.

• It works
• Easy to set up in new and existing projects
• Your system probably ships with a version of make
  • or it can be easily installed
• It’s tiny (and doesn’t depend on much)
• makefiles can be short, succinct and beautiful
• Does not need mysterious working or resource folders
• No opaque magic performed

Most projects, be they software development, writing a book or publishing a blog, at some point need to generate “end products” (of some kind) from manually created raw files.

The point of a build (automation) system is to encode how to do that for one item, and apply that rule to one or more objects of the same type, updating only what’s changed.

One non-software example would be rendering changed book chapters to PDFs and subsequently concatenating them to form the final book.

Of course, this can be (and often is) done via a custom script, written in any one programming language, but make’s powerful rule-based system greatly simplifies the process of doing that.

Sometimes it may be useful to run some tools (for example, a test suite or a spell checker) against the complete project, and the built-in bash-like scripting support allows to do that, too.

Let’s get to discussing how make works by starting with some basic terms and a simple makefile.

Starting out, let’s create an empty file named makefile (with capital or lowercase M, make accepts both).

The content of a basic makefile can be thought of as rules describing:

• If any of these files change
  • This file should, too

In make terminology, the second item is called a target - a file to be made by somehow processing some or all of the prerequisites, which form the first item.

The aforementioned rules for processing the prerequisites can be arbitrarily complex, and can consist of calling out to other tools such as compilers, parsers, etc.

The basic syntax for defining a target is

target: prereq1 prereq2 ...
    command1
    command2
    ...
    <blank line>

Note that you need to indent the command section with tabs, not spaces.

The commands tell make what to do to create the target file. They are executed when we ask to create or update the target file and make concludes that the prerequisites have changed or the target file does not yet exist.

In most cases, you will want to process multiple files of the same type according to the same rules. One example of this would be creating HTML pages from markdown articles. This is done with a pattern rule. Pattern rules are one of the main things that set make apart from just scripting the whole thing in bash.

Start make in a directory by running

make

If there is a makefile present, the first target make can find will be created (built). If there is no makefile (or one does exist, but contains no targets), make will complain about that.

To request a specific target, run

make target

One interesting feature right of the bat is that make is able to try to infer, using it’s built-in rules, what to do even without having any further information.

Try it by creating a test.c file in an empty folder and running make test. make will then try to build a target named test, recognize that it can do so by compiling test.c using a built-in pattern rule and do that. This even works over multiple steps of generated intermediate files.

In most makefiles in the wild, you’ll find a couple of special targets. Most commonly seen are probably

• all to build the entire project
• clean to remove all generated artefacts
• install to install the generated files to the system
• release or dist for preparing release-ready or distributable files (such as packages or tarballs)

Keep in mind that these targets are not required to be present in a makefile, but most build processes in the software world expect at least the first three to work.

These special targets obviously do not produce files named all or clean. Since make normally decides whether to run anything at all based on its view of whether the target would change, creating such a file would prevent make from doing anything at all for these targets.

To prevent that, GNU make allows us to mark these targets as phony in order to have them run anyway. We can do this by adding these targets as prerequisites to the internal .PHONY target like so:

.PHONY: all clean run

The all target normally simply has the main executable in it’s prerequisite - sometimes with some additional commands to post-process the generated files. Since you’ll want the all target to be the one executed by default in most cases, it should also be the first in the file.

For the clean target, you’ll normally add a command list removing all generated files - which can be greatly simplified using variables, which we will learn about in the next section.

Just as in most programming languages, makefiles can be made more readable by using variables.

make also imports it’s environment, allowing us to assign variables inside the makefile from the outside by passing them with the invocation or setting them in the external environment.

You can assign and reference variables with the syntax

NAME = value
FOO = baz
bar = $(FOO) frob

References to variables are made in the form $(NAME) or ${NAME}, with both being exactly the same. When omitting the braces, make assumes that the variable name is one character long.

Variables can be appended to with the += operator. We can also set variables conditionally (only if they do not already have a value) with the ?= operator. This is extremely useful to allow the external environment to overwrite a variable while still providing a default value.

Finally, most implementations of make allow us to set a variable to the output of a shell command with the != operator. This comes at the cost of one subshell spawn per operation.

Up to this point we have seen some of the built-in pattern rules in action, though they always ran the same basic commands. Of course build requirements are not always the same, and tools may require different flags for different things to be done.

For example, a software project might want to link against different libraries or with different optimizations for a release build than a debug build.

make also keeps some common programs in variables, primarily for the purposes of being able to overwrite them in special conditions.

The most important one of these is $(MAKE), which should be used when calling make from within a makefile (called a recursive make). It takes into considerations such things as command line arguments from the original invocation.

In a clean target, where your main job is to remove files, consider using the $(RM) variable instead of directly calling rm. $(RM) expands to rm -f (at least in GNU make), providing a safer rm call and the ability to, for example, substitute shred.

Variables can be referenced in just about any context within a makefile. You could even construct the name of an executable to call from within a command list by concatenating multiple variables.

This enables us to use variables as targets or as prerequisites as we see fit, allowing for succinct and easy-to-understand constructs such as the following:

OBJECTS = $(patsubst %.c,%.o,$(wildcard *.c))
all: $(OBJECTS)

The above makefile creates a list of all C source files in the directory, replaces their .c suffix with .o using the $(patsubst …) function and then goes on to use that list of files as prerequisite list for the all target. When running make, it will try to build the all target because it’s the first one defined. Since the target depends on a bunch of object files that may not yet exist (or may need updates), and make knows how to make these from C source files, all requested files are built.

This makes for an extremely powerful tool in combination with pattern rules, as we can automatically gather prerequisites, which are then implicitly used as new targets.

In order to be compatible with other implementations, GNU make provides an alternative syntax for a limited call to the $(patsubst …) function called a substitution reference. This feature allows us to substitute suffixes of a list-of-words with another suffix.

The makefile from the previous example could be expressed in a style that would work on almost any implementation like so:

FILES != echo *.c
OBJS = $(FILES:.c=.o)
all: $(OBJS)

Note the use of the != assignment operator instead of the $(wildcard …) function.

Another interesting feature leading to a great saving in lines of code are target-specific variables, which allow us to set variables to different values depending on the current target.

FOO = bar
target1: FOO = frob
target2: FOO += baz

The previous example would have set $(FOO) to bar globally, to frob within target1 and to bar baz in target2.

As you can see, we can use any variable assignment operator conditionally, allowing us for example to create a release target with a different set of compiler flags by simply setting the $(CFLAGS) variable differently for that target.

The syntax for writing a pattern rule is a lot like the normal target syntax. The major difference comes in using the the wildcard % in the target name. This wildcard will match what is called the stem of a target.

The wildcard may also be used in the prerequisite list, where it will be replaced by the stem to form implicit prerequisites. One of the more interesting things you can do is to extend the prerequisite list of a pattern rule with explicit prerequisites. These work just as if you would have added them to any target using the rule.

You can also simply overwrite any of the built-in rules by defining a rule with the same target and prerequisites.

Of course, since a pattern rule needs to be written to be independent of the actual file names it is called with, make provides some special variables within a pattern rule definition. These are called automatic variables.

Suffix rules are an older way of defining something that works a lot like pattern rules, though their syntax is a lot less expressive. When using GNU make, defining pattern rules as explained in this article is far preferrable, as we’ll see.

However, the POSIX standard and the BSD implementation only support suffix rules, so I’ll give a short introduction.

Suffix rules operate in a fashion similar to a basic pattern rule where the stem does not exclude any prefixes of the file name and thus contains everything up to the file’s suffix.

A suffix rule is then declared by concatenating the prerequisite suffix and the target suffix to form the suffix rule target name. In order to have make recognize this as a suffix rule and not just a weird target name, the suffixes used must be added as prerequisites to the special .SUFFIXES target.

For example, the previous example of converting markdown articles to HTML would look as follows

.SUFFIXES: .md .htm
.md.htm:
    markdown $^ > $@

In the previous sections, you have learned some of the more complex things you can do with makefiles. The moderately complex, but still useful makefile for the articles on this website reads like this

make tries to minimize it’s workload by only building targets whose prerequisites have changed. It does this by looking at the filesystem timestamps for all files involved. The response nothing to be done implies that make did not think anything would change in the target files if were to run the rules. This could have several reasons.

If target relies on a pattern rule

It the target uses a pattern rule, a prerequisite is automatically inferred even if the prerequisite list contains other files already. For an example, consider this makefile trying to compile a binary named test from foo.c:

test: foo.c

The built-in pattern rule to compile binaries from C source will generate an additional prerequisite called test.c from the stem, which may not exist, causing make to ignore the pattern rule from consideration (since it does not match). make continues to search for rules that apply and, failing to find any, does nothing.

To solve this, use the stem of the primary source file (the first prerequisite) as the output prefix to have the built-in pattern rule match. Use additional prerequisites to trigger a rebuild when they are being changed.

If target does not use a pattern rule or contains a command list

If a target with an empty prerequisite list does not match an internal pattern rule (which infer some prerequisites automatically), the only source of information available to make is the target file itself. The timestamp on this file is then of course comparable to only itself and therefore found not to be in need of an update.

GNU make is arguably the most feature-complete implementation of make. Many of the advanced things that make life easier and makefiles less ugly started life as a GNU extension to the core make specification and have been gradually picked up by other implementations.

Conversely, GNU make also took up many features first seen in other implementations, not only in order to stay compatible to a wide range of other makefiles, but also to extend what is possible with a makefile.

Regrettably, this also means that if you want your makefile to stay compatible to the widest possible range of implementations, you will have to forgo using some functionality. Non-portable functionality mentioned in the article should have a note next to it. Please remind me to add one if you find functionality that does not work with some implementations.

Another possibility of supporting as many implementations as possible is to create multiple makefiles for your project. GNU make will first search for a file named GNUmakefile, in order to support exactly this scenario.

As most implementations choose to support at least some extensions to the basic protocol, there is no pure implementation of only POSIX-mandated functionality (unless strict POSIX compliance is enforced by defining the .POSIX target). I will therefore focus this comparison on the differences to BSD make, which is one of the more restrictive ones.

As noted in the article, POSIX does not mandate variable functions, as useful as they are, and BSD does not implement them. Most functionality provided by this feature can potentially be replaced by calls to the shell (using the != operator) at the cost of additional subshell executions.

Most prominently, the $(wildcard …) function may be replaced by a call to either of the following commands

find . -type f -name '*.suff'
echo *.suff

The build process under Windows is generally a bit more involved than under Unix-like systems, as Windows users are usually accustomed to a much higher level of tooling integration (ie. expect their projects to be able to build using Visual Studio).

You’ve made it to the end of this article. Thanks for reading! I’ve aggregated some links to further details, if this tickled your interest.

Once you get accustomed to the terminology, the GNU make manual is a very good read. In addition to the sections already linked from their context in the article, the following parts are a good source of interesting information: