Using a Makefile for compiling your program

Compiling your source code files can be tedious, especially when you want to include several source/header files and have to type the compiling command every time you have made a small change to the source. On Linux, commonly the make program is used to handle this task. Make looks for a Makefile in your folder and then executes it.

To illustrate the usage of make, we provide an example where we have a small program which does some matrix calculations. We will use the following directory structure:

.
|-- Makefile
|-- bin
|   `-- matrix
|-- include
|   `-- matrix.h
|-- obj
|   |-- main.o
|   `-- matrix.o
`-- src
    |-- main.cpp
    `-- matrix.cpp

In the bin folder, we will store our executable. Every .cpp file will be stored in the src folder, the .o files in the obj (objects) folder, and the header files in the inc (include) folder. We want make to execute the following compile instructions

• Every .cpp file in the src folder should be compiled to an object file in the obj folder.
• When compiling .cpp files, the compiler should look for header/include files in the src and inc folders.
• After compilation, all the object files should be linked to generate an executable in the bin folder.
• There should be a "clean" algorithm for removing all object files and the executable.
• Everything should be modular, that is, if either a single file name of directory name is changed, there should be a minimum number of changes in the source code to address this change.

Without further adieu, our Makefile looks like this:

# set compiler and compile options
EXEC = matrix
CXX = g++             # use the GNU C++ compiler
OPTS = -O2 -Wall -g   # use some optimization, report all warnings and enable debugging
CFLAGS = $(OPTS)      # add compile flags
LDFLAGS =             # specify link flags here

# set a list of directories
INCDIR =./include
OBJDIR = ./obj
BINDIR = ./bin
SRCDIR = ./src

# set the include folder where the .h files reside
CFLAGS += -I$(INCDIR) -I$(SRCDIR)

# add here the source files for the compilation
SOURCES = main.cpp matrix.cpp

# create the obj variable by substituting the extension of the sources
# and adding a path
_OBJ = $(SOURCES:.cpp=.o)
OBJ = $(patsubst %,$(OBJDIR)/%,$(_OBJ))

all: $(BINDIR)/$(EXEC)

$(BINDIR)/$(EXEC): $(OBJ)
        $(CXX) -o $(BINDIR)/$(EXEC) $(OBJ) $(LDFLAGS)

$(OBJDIR)/%.o: $(SRCDIR)/%.cpp
        $(CXX) -c -o $@ $< $(CFLAGS)

clean:
        rm -vf $(BINDIR)/$(EXEC) $(OBJ)

Commonly, you define your variables at the top of the script. This way, you don't have to scroll down too much to change any compilation parameters. At the top, we have defined the name of our executable, the compiler and compilation flags. Next, we define all the folder where the source files are kept or where we want our compiled files to go. Thereafter, we add some additional instructions to the compiler flags, namely the folders where the includes files are kept in. Note that we append this information to an already existing variable using the += operator. The real magic comes next, where we use a very handy substitution method for setting the values to our variables. We take each item in the $(SOURCES) variable and convert the .cpp extension to an .o extension and prepend these files with the obj path. This gives us a list of object files that we need to generate and where the executable depends on.

The last lines are the real compilation instructions. These are set up in such a way that you first define what you want to compile, followed by a colon (:) and then the dependencies the compiled file depends on. You indent the next line with a tab and then define there exactly the compilation instructions. For example, we set in the script that our executable depends on all the object files and in order to generate the executable, all these object files need to be linked. Likewise, every one of the object files depend on its corresponding .cpp file and needs to be compiled using only that particular .cpp file. Lastly, if we want to clean up all the object files and executables (for instance if we want to make a backup of only the source files), we provide a "clean" instructions which simply deletes all the compiled files using rm.

I hope it is now clear how handy Make is. Extending the above script to use for instance external libraries to link against is very easy. There are many good tutorials and instructions available on the internet. (Google is your friend!) I have made a short list of resources below I have often used when I ran into trouble writing my Makefiles.

• http://mrbook.org/tutorials/make/
• A tutorial provided by the Computer Science Department Colby College
• https://www.cs.umd.edu/class/fall2002/cmsc214/Tutorial/makefile.html
• The official manual