Practical Makefiles, by example

Author: John Tsiombikas Contact: nuclear@member.fsf.org Date: 9 Feb 2015

1 Rationale The purpose of this document is to explain how to write practical makefiles for your everyday hacks and projects. I want to illustrate, how easy it is to use make for building your programs, and doing so, dispel the notion that resorting to big clunky graphical IDEs, or makefile generators such as autotools or cmake, is the way to focus on your code faster. The purpose of this document is certainly not, to teach you how to write user-friendly, all-encompassing, release-quality build systems. You can certainly arrive to that by extending a simple makefile, and I'll give you a few pointers about that sort of thing in the end, but I will not focus on complexity and completeness, but rather on simplicity and practicality. Finally, it's worth spelling out up front that when I say "make", I'm really referring to the GNU implementation of make, which is packed with useful features, not necessarily found in other make programs out there. It might be interesting to write a follow-up article, providing similar examples for other make implementations out there, such as BSD make, Watcom make, Borland make, or Microsoft's nmake. But I'll leave that for another time.

2 Building C/C++ programs First let's consider an example C program, and how to build it without make. In order to escape the trap of an oversimplified toy program, let's assume we're making a small computer game. Our game is made up of the following source and header files: main.c entry point and system event loop game.h & game.c event handlers and game update/redraw loop player.h & player.c player state and input level.h & level.c game world state enemy.h & enemy.c enemy state and AI renderer.h & renderer.c graphics algorithms / game drawing vecmath.h & vecmath.c vector & matrix math needed for simulation and rendering image.h & image.c image loading for textures mesh.h & mesh.c 3D mesh data structures & loading Also, our game depends on a number of 3rd party libraries: OpenGL Low level graphics library GLUT Cross-platform OpenGL window setup & event handling libpng PNG image file format reader/decoder zlib Needed by libpng for lz77 decompression To build this program we would first have to run the compiler on each source file, generating a corresponding object code file: cc -c main.c cc -c game.c cc -c level.c ... Then, we would have to feed all the object files to the linker (possibly still using the C compiler front-end for convenience), instructing it to link all the libraries we need as well: cc -o mygame *.o -lGL -lglut -lpng -lz -lm Obviously, such tediousness could be automated with a shell script. However, that would be a grossly sub-optimal solution, as it would recompile all source files from scratch, every time we try to build with it.

3 Enter make Make is a much more elegant solution to our building problems. We create a file named Makefile , which contains a set of rules describing build products, their dependencies, and which commands are needed to build them. Then when we ask make to build our program binary, it recursively traverses the dependency graph to figure out which parts need to be re-created, based on the last-modified timestamps of the target file, and its dependency files. Warning: do not run away terrified by the first makefile example. It's only meant to illustrate how make works, so it's needlessly verbose. If you're easily scared, skip to section: "A makefile for 99% of your programs". Back to our game example, the binary mygame , obviously depends on main.o (among other object files). main.o in turn, is created by compiling main.c . So, let's define two make rules for creating these two files: mygame : main . o player . o enemy . o renderer . o vecmath . o image . o mesh . o cc -o mygame main.o player.o enemy.o renderer.o vecmath.o image.o mesh.o -lGL -lglut -lpng -lz -lm main.o : main . c cc -c main.c player.o : player . c cc -c player.c Essentially for each rule, the part before the colon is the filename we want to build when this rule is executed, the part after the colon is the list of dependencies, i.e. what is needed to create this rule's target. And finally, in subsequent lines, we just type the commands needed to make this happen. Note that each line in the commands part of a rule needs to begin with a leading tab. Spaces will not work, it really has to be a tab character, so pay extra attention to your text editor settings, about how it treats any tabs you enter. So, if we modify main.c , and then type make (which means: build the first rule in the makefile), make will try to build the file named mygame . In order to build it, make will have to use the declared dependency files, so it will execute each rule corresponding to those files in turn, starting from main.o . To build main.o , make sees that it needs main.c , which having been modified more recently than main.o , is deemed out of date and must be re-created by executing the command specified in this rule. Similarly, returning to the initial rule, since now main.o is newer than the old mygame binary, the binary will be rebuilt by running the linking command, after visiting each object file rule in turn and determining that none of them needs rebuilding, since we didn't touch any of their dependencies.

4 Simpler makefile Obviously, having to type rules for each of our source files is tedious, and thankfully unnecessary. Make actually knows how to create object code from C source files, so we can skip the object file rules, and also provides some handy variables for referring to the target or dependency files in rule commands without having to re-type everything. So here is a slightly simpler makefile for the same task: myprog : main . o game . o level . o player . o enemy . o renderer . o vecmath . o image . o mesh . o cc -o $@ $^ -lGL -lglut -lpng -lz -lm @ is a built-in make variable containing the target of each rule (myprog in this case), and ^ is another built-in variable containing all the dependencies of each rule (so the list of object files in this case). Similarly, although not useful for this particular rule, there is also the < variable, which contains only the first element of the dependencies (so main.o if we used it in the rule above). We substitute the value of any variable (built-in or not) by prepending a dollar sign to its name. However, one peculiarity of the make syntax, as opposed to say the bourne shell syntax, is that only the first character following the dollar sign is considered to be the variable name. If we want to use longer names, we have to parenthesize the name before applying the dollar sign to extract its value. So for instance if we had defined a variable: obj = main.o game.o level.o ... (etc) ... , then to substitute its contents we have to use parentheses: $(obj) . If we instead tried to use $obj then make would try to expand a variable named "o", and then append the string "bj" to the result.

5 A makefile for 99% of your programs There's one last thing bugging me in the last example. I hate having to type manually the list of object files needed to build the program. Thankfully it turns out we don't need to do that either. See the following example: src = $( wildcard *.c ) obj = $( src:.c = .o ) LDFLAGS = -lGL -lglut -lpng -lz -lm myprog : $( obj ) $( CC ) -o $@ $^ $( LDFLAGS ) .PHONY : clean clean : rm -f $( obj ) myprog The first line of this example collects all source files in the current directory in the src variable. Then, the second line transforms the contents of the src variable, changing all file suffixes from .c to .o , thus constructing the object file list we need. I also used a new variable called LDFLAGS for the list of libraries required during linking ( LDFLAGS is conventionally used for this usage, while similarly CFLAGS and CXXFLAGS can be used to pass flags to the C and C++ compilers respectively). Finally, I added a new rule for cleaning up every target, in order to rebuild the whole program from scratch. The clean rule is marked as phony, because its target is not an actual file that will be generated, but just an arbitrary name that we wish to use for executing this rule. In order to run any rule other than the first one, the user needs to pass the target name as a command-line argument to make. So, for instance, to clean everything in this example, just type make clean .

6 Further improvements The makefile listed above is sufficient for most small programs you'll ever write. In this section, I'll go over a few improvements for larger projects. 6.1 Multiple source directories Let's say you have some source files under src/ , other source files under, src/engine , and some more source files under src/audio . Also, to make it more interesting, let's assume that your code is a mix of C and C++ in any of these directories. Here's a very simple modification which handles this situation: csrc = $( wildcard src/*.c ) \ $( wildcard src/engine/*.c ) \ $( wildcard src/audio/*.c ) ccsrc = $( wildcard src/*.cc ) \ $( wildcard src/engine/*.cc ) \ $( wildcard src/audio/*.cc ) obj = $( csrc:.c = .o ) $( ccsrc:.cc = .o ) LDFLAGS = -lGL -lglut -lpng -lz -lm mygame : $( obj ) $( CXX ) -o $@ $^ $( LDFLAGS ) The rest is exactly the same as previously. Note that I used the CXX built-in variable, which defaults to c++ instead of cc , to invoke the linker in the correct way for C++ programs, automatically linking libstdc++ with it. Also, backslashes at the end of lines serve to merge multiple lines together by escaping the newline character. 6.2 Handling cross-platform differences So far, in all the examples, I've linked OpenGL and GLUT by passing the -lGL -lglut flags to the linker. That's how reasonable UNIX systems do it, but what if we want to build our project on vaguely UNIX-like abominations like MacOSX, where you have to use the following command-line arguments: -framework OpenGL -framework GLUT (since OpenGL and GLUT they are "frameworks" and not just libraries ... *sigh*) ? Simple; use uname -s to figure out if we're building on MacOSX, and modify the LDFLAGS variable accordingly: LDFLAGS = $( libgl ) -lpng -lz -lm libgl = -framework OpenGL -framework GLUT libgl = -lGL -lglut The order of defining libgl and defining LDFLAGS doesn't matter, as long as they're both before the first rule which uses either of them, since LDFLAGS won't be evaluated (and thus require substitution of the libgl variable) until it's used in a rule. A slightly more elegant, but not exactly equivalent way of doing the above would be the following instead: LDFLAGS = $( libgl_ $( shell uname -s )) -lpng -lz -lm libgl_Linux = -lGL -lglut libgl_Darwin = -framework OpenGL -framework GLUT I said not exactly equivalent, because in this way we would have to enumerate all possible UNIX systems we'd like to support instead of just handling them in the else part of the conditional statement. 6.3 Wildcard rules As I mentioned above, make knows how to compile C and C++ source files to create object code, and you don't have to explicitly write rules of the form: main.o : main . c $( CC ) $( CFLAGS ) -o $@ -c $< But let's say you want to compile code for a new language, which make knows nothing about. There is a mechanism to write generic rules, so that you won't have to laboriously type specific rules for each file you wish to compile. If you wish to inform make, on the generic form of rules for building object files out of source files in a fictitious foo language, which are commonly in files with a .foo suffix, and compiled by running fooc -c , you can write the following wildcard rule: %.o : %. foo fooc $( FOOFLAGS ) -o $@ -c $< Then, whenever make needs to build xyzzy.o , and there is a file named xyzzy.foo , it will use that rule to compile it. 6.4 Automatic #include dependency tracking Update: it turns out there's a better way to do this, make sure to also read the next section for an improved version. Thanks to Dan Raymond for pointing it out. I'm keeping this section in the document for posterity, and because I don't want to reformulate the explanations of how this works and why it's necessary, which are still valid. The built-in rule for compiling C source files, is similar to: %.o : %. c $( CC ) $( CFLAGS ) -o $@ -c $< Which means, that if we change foo.c , foo.o will be out of date and will be rebuilt automatically. There are, however, usually many more dependencies that need to be considered to determine if foo.o needs rebuilding, which fall through the cracks in this simple but generic scheme. Specifically, if foo.c also includes foo.h and bar.h , then if we fail to rebuild foo.o when either of these header files change, will result in a potentially incorrect program, and depending on the nature of the modifications, possibly memory corruption, and hopefully segmentation faults at runtime. For simple hacks with a couple of source and header files, we can afford to just clean and rebuild any time we change header files significantly, for larger programs however, we'd really like to have our build system track dependencies due to header file inclusion too. Make can't possibly know what constitutes a dependency, and include a syntactic analyzer to detect it for each and every language, which is why this doesn't happen automatically. However with the help of our compiler's pre-processor, we can create the necessary rules to do it. We'll write a wildcard rule to generate makefile fragments with an explicit rule for each source file in our project, which also includes header files in the dependency list. Then we'll instruct make to include these makefile fragments in our makefile as if we wrote them by hand. Any missing makefile fragments will be automatically generated with our wildcard rule during this inclusion. Finally we'll add a rule to clean all these dependency files (the makefile fragments). src = $( wildcard *.c ) obj = $( src:.c = .o ) dep = $( obj:.o = .d ) LDFLAGS = -lGL -lglut -lpng -lz -lm mygame : $( obj ) $( CC ) -o $@ $^ $( LDFLAGS ) -include $( dep ) %.d : %. c @ $( CPP ) $( CFLAGS ) $< -MM -MT $( @:.d = .o ) > $@ .PHONY : clean clean : rm -f $( obj ) mygame .PHONY : cleandep cleandep : rm -f $( dep ) The added lines are marked with comments in the example above. To see exactly what the C preprocessor outputs when instructed to write dependency information, try running the following in a file with a single include statement: cpp foo.c -MM -MT foo.o That's right, it just outputs a single makefile rule! Which is exactly what we need for make to track all the dependencies correctly. 6.5 Improved automatic dependency tracking The dependency generation mechanism described in the previous section, is slightly more complicated than necessary, and requires a separate (although automatic) pass through the source files to generate the dependency files, which consumes significant time on older machines or huge projects. There's a way to instruct the compiler (GCC and clang supports this, more compilers might do so too), to generate the necessary makefile fragment ( .d file) at the same time as it compiles each source file. This is done by passing the -MMD option to the compiler. The absence of the .d files during the first make will not be detrimental, because at that point we're doing a full build anyway, and subsequent make invocations will have the necessary makefile fragments included to aid in deciding which source files need to be rebuilt because a header file has changed. This approach, apart from reducing initial build times, also simplifies our makefile from the previous section slightly, since there's no need for a custom %.d: %.c rule for generating the dependency files: src = $( wildcard *.c ) obj = $( src:.c = .o ) dep = $( obj:.o = .d ) CFLAGS = -MMD LDFLAGS = -lGL -lglut -lpng -lz -lm mygame : $( obj ) $( CC ) -o $@ $^ $( LDFLAGS ) -include $( dep ) .PHONY : clean clean : rm -f $( obj ) mygame .PHONY : cleandep cleandep : rm -f $( dep ) The only changes from the previous example, is the removal of the wildcard rule, and the addition of -MMD in CFLAGS . 6.6 Building sub-projects Consider the following case: our game has source files in src/ , but we also need to use an external library called libfoo , which is not a system-wide installed library, but one we want to carry with our source tree under libs/foo . How would we integrate that in our build system? Very simply, instruct make to first build libfoo , by running make after changing to the libs/foo directory, and then link it as usual: src = $( wildcard src/*.c ) obj = $( src:.c = .o ) LDFLAGS = -Llibs/foo -lfoo -lGL -lglut -lpng -lz -lm mygame : $( obj ) libfoo $( CC ) -o $@ $^ $( LDFLAGS ) .PHONY : clean rm -f $( obj ) mygame .PHONY : libfoo libfoo : $( MAKE ) -C libs/foo By adding the phony libfoo rule as a dependency to our binary linking rule, we essentially force make to always change into libs/foo and run make before linking our binary. If there is no need to actually rebuild libfoo because it has no changes, that makefile will do nothing and return immediately, so there's no harm in trying every time. Arbitrarily complex programs can be built by using a similar approach, to build various modules as separate libraries. So this little snippet really scales our simple build system to easily handle huge projects as well.