Your Canonical Build System — make

It is about as easy to get started with make as it is to get started with C. Hopefully, it takes a bit less forbearance to become proficient in make, than it takes to become proficient in C.

To get started, create an empty directory and navigate to it:

Consider a simple program which fits on a file, which we can call main.c:

With no further work, we can already use make to compile this program:

If we instead called our file root.c we would have to compile it like this:

If we forget the program name, make will complain, not knowing what to do:

Similarly, if we misspell the program name, make will complain:

As long as we pass the command-line argument main to make, make can save us a couple keystrokes, and compile our main.c into an executable file called main on our behalf.

We can try to run our program and check its exit code:

A classical feature of make, is that it helps us avoid unnecessary recompilations.

Try to call make main again (without changing main.c):

In this basic use, make takes main.c as a prerequisite for the target main. That is, make sets up a dependency graph which can be illustrated like this:

To implement this dependency graph, make will compare the modification time of main.c with that of main. If the prerequisite was modified after the target, make will run a recipe in attempt to bring the target "up to date" with the prerequisite. The default recipe in this case, is to compile the C file.

The behaviour of calling make in a particular directory can be customized by creating a special file called Makefile in that directory. As a (de)motivating example, here is a Makefile that (in our case) will achieve the exact same effect as having no Makefile at all (except use the expected C compiler!):

A Makefile specifies a number of rules. A rule has a number of targets and prerequisites, as well as a recipe for brining the targets "up to date" with the prerequisites. A recipe is a sequence of commands which will be called in order, from top to bottom, each in their own shell.

The format of a Makefile rule goes as follows:

There is one benefit to our Makefile however: we no longer need to specify main as the command-line argument to make. It is now assumed by default:

To make our Makefile a bit more useful, let’s create a classical phony target — clean. clean will be "phony" in the sense that its recipe will not produce a file called clean. Instead, clean will clean up the mess our invocations of make have made above — in our case, just remove the main file.

A simple approach would’ve been to just add the clean target to our Makefile:

Unfortunately, if we were ever to place a file called clean into our directory, the clean target would always be considered up to date (why?). For instance, consider the following session at the terminal:

To avoid this problem (and make sure the recipe for clean is always run when we ask it to), we have to mark the clean target as .PHONY:

Continuing the terminal session from before..

If you spuriously try to play around, and try to make clean again, you’ll get to see make fail:

The recipe is failing because we’ve already removed the file called main.make then tries to be helpful and tell us that it failed on line 7 of the Makefile, in the midst of the recipe for the clean target.

A recipe fails as soon as one of its commands (executed in order from top to bottom) yields a non-zero exit code.

This is what rm does for a nonexistent file. We can add a -f command-line argument to rm in our recipe to make rm ignore nonexistent files:

Now we can go on a command spree again!

Mental exercise: Can you come up with other ways of solving the problem with the clean target?

Another useful phony target is a test target to perform the tests we have thus far been doing manually. This target has a main executable as a prerequisite, and the recipe should run the executable and check its exit code. test is a good example of a phony target with prerequisites.

One naïve approach could go as follows:

Let’s try to make test and see what happens:

So ./main yields the expected exit code alright, but it is ill practice to designate a test error as a success.

A better Makefile could go as follows:

We can try to make test to make sure that things work as expected:

Note, the test target lists main as a prerequisite. So the dependency graph deduced by make can be illustrated as follows:

To see how make implements this dependency graph, let’s try to make clean and make test:

Out of mere interest, let us try to introduce an error into our program and see how make will handle a compilation error:

Perhaps as you had already expected, make stopped processing the dependency graph as soon as it encountered an error in one of the recipes.

You might’ve noticed that make with no arguments still works despite the fact that there are now multiple targets in our Makefile:

make resolves target ambiguity in a very simple way — the top target is the default target, and in our Makefile, the top target is main.

This is not a good default target for two reasons:

We can embrace both by adding a phony target all at the top of our Makefile, listing test as a prerequisite:

Let’s take the Makefile for a spin:

Consider our stack calculator from the accompanying tutorial on Getting Started with C.

There, we had a stack data structure declared in a header file stack.h, and implemented in the C file stack.c. We compiled the implementation follows:

We then had a file calc.c which implemented the actual stack calculator using the stack implementation above. calc.c contained a main function. So we then compiled the program as follows:

Perhaps a natural Makefile for our stack calculator would then go as follows:

The dependency graph deduced by make in this case, can be illustrated as follows:

Our Makefile is starting to get a little cryptic and a little fragile. Good software development practice tells us not to repeat ourselves. We are repeating ourselves with all those compiler flags, and the compiler flags obscuring our recipes.

Makefile variables let us solve this in a straight-forward way. Makefile variables work a bit like simple C macros in that they are merely placeholders for text. Variables are typically declared at the top of the Makefile, named in ALL CAPS, with words occasionally separated by _.

For instance, here’s a Makefile that resolves our problems above:

We can use make to make sure to build the elements of our software project in proper order, and put common software development tasks at our fingertips. We can use Makefile variables to keep our recipes consistent, to the point, and flexible.

We call make "canonical" because it is widely available in Unix-like programming environments. It is often used in large software projects, and is especially ubiquitous in the open-source and free software communities.

make is old. Originally developed in 1977, it has had many derivatives. GNU make, the version of make we’ve encouraged you to use here, is the standard implementation of make on most Linux and OS X systems. On Windows, the standard implementation is nmake, and comes as part of Visual Studio.

The rogue nature of make has also inspired the development of many alternative tools and companions. For instance, SCons, CMake, and Mk. Each come with their own benefits and setbacks.

A most notable critique of make is that it demands of you to manually manage your dependencies. Integrated Development Environments, such as Eclipse, Xcode, and Visual Studio, as well as many modern programming languages, such as Go and Rust, often come with their own build-automation tools, which automatically deduce dependencies from source-code. This results in unwarranted dependence on particular languages and tools.

In today’s world, make is reserved for those who want to exert grand control over the build process, and projects which depend on a great variety of untamed languages and tools. make is widespread till this day.

This tutorial is by no means a comprehensive introduction to make. Most notably, we’ve focused on programming in C, and forgotten to mention that make can be made to build dependencies in parallel, and that special, magic-looking makefile variables can be used to write terse recipes.

There’s probably more that we’ve forgotten. If you want to know more, here are a couple good resources for further study: