1. A sample makefile and how it works

Let's start by looking at a sample makefile:

##############################################################################
#
#  Sample Makefile for C++ applications
#    Works for single and multiple file programs.
#    written by Robert Duvall
#    modified by Owen Astrachan
#    and by Garrett Mitchener
# 
##############################################################################

##############################################################################
# Application-specific variables
# EXEC is the name of the executable file
# SRC_FILES is a list of all source code files that must be linked
#           to create the executable
##############################################################################

EXEC      = usepix
SRC_FILES = application.cc displaycommand.cc filelister.cc menu.cc \
        menuitem.cc pixmap.cc quitcommand.cc readcommand.cc \
        usepix.cc


##############################################################################
# Where to find course related files
# COURSE_DIR is where various header files (.h) and library files (.so and .a)
# are found.  LIB_DIR is where other libraries not specific to the course
# are kept.

# for CS machines
# COURSE_DIR = /usr/project/courses/cps108/lib
# LIB_DIR     = /usr/local/lib

# for acpub machines
COURSE_DIR = /afs/acpub/users/o/l/ola/cps108/lib
LIB_DIR     = /afs/acpub/project/cps/lib

##############################################################################
# Compiler specifications
# These match the variable names given in /usr/share/lib/make/make.rules
# so that make's generic rules work to compile our files.
# gmake prefers CXX and CXXFLAGS for c++ programs
##############################################################################
# Which compiler should be used
CXX = g++
CC = $(CXX)

# What flags should be passed to the compiler

DEBUG_LEVEL     = -g
EXTRA_CCFLAGS   = -Wall
CXXFLAGS        = $(DEBUG_LEVEL) $(EXTRA_CCFLAGS)
CCFLAGS         = $(CXXFLAGS)

# What flags should be passed to the C pre-processor
#   In other words, where should we look for files to include - note,
#   you should never need to include compiler specific directories here
#   because each compiler already knows where to look for its system
#   files (unless you want to override the defaults)

CPPFLAGS        = -I. \
                  -I$(COURSE_DIR)

# What flags should be passed to the linker
#   In other words, where should we look for libraries to link with - note,
#   you should never need to include compiler specific directories here
#   because each compiler already knows where to look for its system files.

LDFLAGS         = -L. \
                  -L$(COURSE_DIR) \
                  -R $(LIB_DIR):$(COURSE_DIR)

# What libraries should be linked with.
# For example, -lm links with libm.so, the math library.
# If you make a library of your own, say, libscandir.a, you have to link it
# in by adding -lscandir here.
LDLIBS          = -lscandir

# All source files have associated object files.
# This line sets `OFILES' to have the same value as `SRC_FILES' but
# with all the .cc's changed into .o's.
O_FILES         = $(SRC_FILES:%.cc=%.o)


###########################################################################
# Additional rules make should know about in order to compile our files
###########################################################################
# all is the default rule
all: $(EXEC)


# exec depends on the object files
# It is made automagically using the LDFLAGS and LOADLIBES variables.
# The .o files are made automagically using the CXXFLAGS variable.
$(EXEC): $(O_FILES)

# to use `makedepend', the target is `depend'
depend:
   ->   makedepend -- $(CXXFLAGS) -- -Y $(SRC_FILES)



# clean up after you're done
clean:
   ->   $(RM) $(O_FILES) core *.rpo

very-clean: clean
   ->   $(RM) $(EXEC)

Note that the arrows -> represent places where you should put tab characters, not eights spaces. It hath been decreed that this shalt be a tab character. Emacs and XEmacs have a makefile mode, which you can get into by typing M-x makefile-mode if it doesn't come up automatically. In makefile mode, pressing the tab key inserts a real tab. Alternatively, the keystrokes C-q C-i or C-q tab will enter a tab character in any mode. (C-q is emacs for quote next key unprocessed.)

You should name your makefile `Makefile' with that capitalization. Make looks for that file automatically. If you don't name it that, you'll have to tell make specifically which file to use (as in gmake -f somethingelse ...).

1.1 The short answer

The short answer of how to use that makefile is this: Change the line that says SRC_FILES = so that the right-hand side of the equals sign is a list of all the .cc files in your project. Change the line that says EXEC = so that the right-hand side of the equals sign is the name of your executable.

The first time you use make, add a .cc file, or any time you change whether a .cc file includes a particular .h file, run the command:

gmake depend

To build your executable in general, run the command gmake. To clean up your directory and get rid of files you don't need, run gmake clean.

These short directions will be enough to get you through the first assignment or two, but after that, you'll probably need to start changing more stuff further down in the makefile, and to know what to do, you'll have to understand how make works. So, without further ado...

1.2 Comments

Any line which begins with a sharp sign (#) is ignored by the makefile as a comment. Comment lines can be used to leave instructions for whoever has to use your makefile (including yourself). They are also useful for allowing someone to select between alternative definitions of macros. For example, several lines of the makefile have been commented out here:

# for CS machines
# COURSE_DIR = /usr/project/courses/cps108/lib
# LIB_DIR     = /usr/local/lib

# for acpub machines
COURSE_DIR = /afs/acpub/users/o/l/ola/cps108/lib
LIB_DIR     = /afs/acpub/project/cps/lib

1.3 Continuing long lines

Continuing long lines is easy, just put a backslash at the end of the line. Make pretends the following long command is all on one line:

SRC_FILES = application.cc displaycommand.cc filelister.cc menu.cc \
        menuitem.cc pixmap.cc quitcommand.cc readcommand.cc \
        usepix.cc

1.4 Macros

In a makefile, it is very easy to define a macro, or text-substitution. These are similar to environment variables in the shell or string variables in most programming languages:

COURSE_DIR = /afs/acpub/users/o/l/ola/cps108/lib

Whenever make sees $(COURSE_DIR) in the makefile, it will substitute in the text contained in the macro COURSE_DIR. Remember, use the dollar sign and parentheses only when you want to reference the macro. Just use its name to assign it a value.

One really useful thing about macros is that they can reference other macros:

CXXFLAGS = $(DEBUG_LEVEL) $(EXTRA_CCFLAGS)

The trick is that make doesn't substitute for DEBUG_LEVEL immediately when you define CXXFLAGS. Instead, when you reference CXXFLAGS, it expands into $(DEBUG_LEVEL) $(EXTRA_CCFLAGS). Since that still has $'s in it, make expands it again into -g -Wall. Therefore, you can define macros in any order, as long as they are defined before they are actually expanded.

1.5 Special $ commands

One line of the sample makefile illustrates a special command that make provides through the $ symbol:

O_FILES = $(SRC_FILES:%.cc=%.o)

This particular line sets O_FILES to be the same as SRC_FILES but with all the .cc suffixes replaced with .o. This is useful because you can easily add a new class to your project by adding its .cc filename to the definition of SRC_FILES. Its object file will automatically be added to O_FILES. This means that adding a file to your project requires changing only one line in your makefile. Furthermore, having a list of all source and object files is quite useful, as you'll soon see.

1.6 Basic dependency rules

Dependency rules are statements that make uses to determine which files need to be brought up to date. They consist of a line declaring what target file depends on which dependencies, followed by zero or more command lines which tell it what to do to bring the target up to date. For example (from another makefile):

OBJ = menu.o application.o pixmap.o
CXX = g++
CXXFLAGS = -g -Wall

usepix: $(OBJ)
   ->   $(CXX) $(CXXFLAGS) -o usepix $(OBJ) -lm

The executable usepix is the target and all those .o files are the dependencies. The $(CXX) line turns into a command to g++ when all those macros are expanded.

Again I must say, it hath been declared that command lines shalt begin with a tab character and end with a new-line character. If the last line of your makefile is not doing anything, it may be that you forgot to push enter at the end of that line.

The dependency line states that the file usepix depends upon the files in the macro OBJ, which in this case expands to application.o, menu.o, etc. If you ask make to update usepix by entering the command gmake usepix on the shell command line, it will find this dependency line and look at all the .o files usepix depends upon. If one of them is determined to be out of date, it is updated. If after all that one of those .o files is newer than usepix, or if usepix doesn't exist, make will execute the compilation command underneath the dependency line and build an up-to-date version of usepix. You may have as many command lines as you want, as long as they all begin with tab characters. You may also have zero command lines, which is useful for pseudo-targets and implicit rules, which I will explain later. All those macros are fully expanded before make looks at any dependencies.

1.7 Special dependency rules

The first dependency is magic. When you execute make, it expects you to give it the name of a target to update on the command line, ie.gmake usepix. If you don't give a target, it simply updates the first target it comes to. In the first sample makefile, it's all, and in the smaller second example, it's usepix, but in a larger project, there might be several test programs, libraries, and so on. It's therefore common to have a first target called `all' which depends on the files you want to update most frequently. No file named `all' ever really exists because it is a pseudo-target. Which brings us to the next item...

Pseudo-targets are really useful. A pseudo-target is a file which never really exists. It has a dependency section in the makefile, and if you tell make to update that target, it will do its normal stuff and update all the dependencies, then run any commands underneath the dependency line.

Here's an example that uses a pseudo-target to effectively combine two other targets so that you can update them with one command:

testsuite: test1 test2

test1: test1.o foo.o bar.o
   ->   ...
test2: test2.o foo.o bar.o
   ->   ...

Issuing the command gmake testsuite causes make to update test1 and test2.

Another way to use pseudo-targets is to have a target which has no dependencies but has a few commands listed under it. In the sample makefile, `clean' is just such a pseudo-target:

clean:
   ->   $(RM) $(O_FILES) core *.rpo

Targets which have no dependencies are always considered out of date and any commands listed under them are always executed. If you were to issue the command gmake clean using the sample makefile, make would remove all those .o files from the current directory.

Having a `cleanup' target or two is quite useful: You're not likely to mistype gmake clean and even if you did, it wouldn't be a disaster. But notice how easy it is to mistype rm -f *.o (remove all your .o files) as rm -f *>o (remove everything and re-direct any output into a file called o). Holding down the shift key a moment too long can wipe out weeks of work, and make can easily prevent such goofs.

Here are some sample pseudo-targets that are useful for lots of different things. Note that some macros are used that you'll have to define for yourself elsewhere:

all: usepix testpix toast pancake

clean:
   ->   rm -f $(OBJ)

# More about this one in the section on makedepend...
depend:
   ->   makedepend $(CXXFLAGS) -Y $(SRC)

# This is a neat way to make a compressed archive file for
# saving or submitting your project.
# Note that several commands go with this target; all will be
# executed if you run gmake archive.
archive:
   ->   rm -rf project project.tar.gz
   ->   mkdir project
   ->   cp $(SUBMISSIONS) project
   ->   tar -cf project.tar project
   ->   gzip project.tar

# This next one makes a printout of all your source code.
# The $? means all dependencies newer than the target.
# See the section on special macros

PRINTCMD = enscript -2rG -pprintout.ps

print: $(SOURCE) $(HEADERS)
   ->   echo spooling $? to printer using $(PRINTCMD)
   ->   $(PRINTCMD) $?
   ->   print printout.ps
   ->   rm printout.ps

1.8 Special macros

Now all those $@ thingees that appear in the example above and elsewhere in the makefile are clearly not plain old macros, since they're never defined and yet this makefile works quite well, I promise. The reason is that there are a number of special macros with one character names that are only useable as part of a dependency rule:

$@

The file name of the target.

$<

The name of the first dependency.

$*

The part of a filename which matched a suffix rule.

$?

The names of all the dependencies newer than the target separated by spaces.

$^

The names of all the dependencies separated by spaces, but with duplicate names removed.

$+

The names of all the dependencies separated by spaces with duplicate names included and in the same order as in the rule.

Some of these are only useful as part of suffix rules which are described in section Suffix rules.

1.9 Suffix rules

Most of the commands you use to update files are similar; to build most C++ programs, you call g++ with similar flags and really just change the name of the file you're compiling. Make allows you to define suffix rules so that you don't have to put command lines underneath all your dependencies. For example, here is the built-in suffix rule that gmake uses to compile a .cc file into a .o file:

COMPILE.cc = $(CXX) $(CXXFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c
OUTPUT_OPTION = -o $@

%.o: %.cc
   ->   $(COMPILE.cc) $< $(OUTPUT_OPTION)

With suffix rules, you can leave out the command part of a dependency rule, for example:

usepix.o: usepix.cc usepix.h pixmap.h

If make decides to update usepix.o, it sees from this line that it depends on usepix.cc, and it sees from the %.cc: %.o rule that to update it, it should run g++ using the flags defined in CXXFLAGS and to compile usepix.cc.

Make has a number of built in suffix rules, which are roughly as follows:

COMPILE.cc = $(CXX) $(CXXFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c
COMPILE.c = $(CC) $(CFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c
LINK.o = $(CC) $(LDFLAGS) $(TARGET_ARCH)
OUTPUT_OPTION = -o $@

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

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

%.o: %.cc
   ->   $(COMPILE.cc) $< $(OUTPUT_OPTION)

You can get the full list from the command gmake -p -f/dev/null/.