A Makefile practical example

It's not uncommon in a project to have a standard rule for compiling files (perhaps even using the built-in GNU Make rule) and to need to have a slightly different version of that rule for a specific file, or set of files, that otherwise use the same command.

For example, here's a Makefile that builds all the C files in two subdirectories (lib1 and lib2) using a pattern rule.

lib1_SRCS := $(wildcard lib1/*.c)
lib2_SRCS := $(wildcard lib2/*.c)

lib1_OBJS := $(lib1_SRCS:.c=.o)
lib2_OBJS := $(lib2_SRCS:.c=.o)

.PHONY: all
all: $(lib1_OBJS) $(lib2_OBJS)

%.o: %.c
   @$(COMPILE.C) -o $@ $<

First the Makefile gets the list of all C files in lib1 in the variable lib1_SRCS and the C files in lib2 in lib2_SRCS and then it converts those to a list of object files to build using a substitution reference to change .c to .o creating lib1_OBJS and lib2_OBJS.

The pattern rule uses the GNU Make built-in variable COMPILE.C to run a compiler that compiles a .c into a .o.   The Makefile knows to build all the objects in lib1_OBJS and lib2_OBJS because they are prerequisites of all.

This works fine if all the .c files have the same compilation options.

Now suppose that the C file lib1/special.c requires the -Wcomment option to prevent the compiler from warning about an oddly written comment.   Obviously is would be possible to change the value of CPPFLAGS globally by adding

CPPFLAGS += -Wcomment

in the Makefile.  But that change affects every compilation and is probably undesirable.

Luckily, a target-specific variable can be used to just alter the value of CPPFLAGS for that single file.  By writing

lib1/special.o: CPPFLAGS += -Wcomment

the value of CPPFLAGS will be altered just for the creation of lib1/special.o.

Now suppose that an entire subdirectory requires a special CPPFLAGS option to maximize optimization for speed (the -fast option to gcc, for example).

Here a pattern-specific macro definition is ideal.  Adding

lib1/%.o: CPPFLAGS += -fast

does the trick.  Any .o files that are built in lib1/ will have the -fast command-line option.

Conclusion

Target-specific and pattern-specific macros are worth reading about because they are a very handy feature of GNU Make when a small change is needed for a limited set of targets.

Further reading can be found in the GNU Make manual sections 'Target-specific Variable Values' (http://www.gnu.org/software/make/manual/make.html#Target_002dspecific) and 'Pattern-specific Variable Values' (http://www.gnu.org/software/make/manual/make.html#Pattern_002dspecific).

Makefiles: pattern-specific example

Pattern-specific macros work in a similar manner to target-specific macros, but instead of being defined for a target they are defined for a pattern and then will be applied to all targets that match that pattern.

The below example shows a pattern-specific macro.  The last line says that for any target that begins with f followed by anything (that's the % wildcard) VAR has the value starts with f.

.PHONY: all foo bar baz

VAR = global scope

all: foo bar
   @echo In $@ VAR is $(VAR)

foo:
   @echo In $@ VAR is $(VAR)

bar: VAR = local scope
bar: baz
   @echo In $@ VAR is $(VAR)

baz:
   @echo In $@ VAR is $(VAR)

f%: VAR = starts with f

Now if you run make you get the following output:

In foo VAR is starts with f
In baz VAR is local scope
In bar VAR is local scope
In all VAR is global scope

This is the same as above except that in the rule for foo the value of VAR has been set to starts with f by the pattern-specific definition.

It's worth noting that this is unrelated to normal GNU Make pattern rules.  The pattern-specific macro definition can be used to change the value of a macro in a normal rule (as above).  It can also be used with a pattern rule.

For example, you could change the value of DEBUG to 1 within all %.o files (that could be built using the standard %.o: %.c pattern rule) by writing:

%.o: DEBUG = 1

Makefile: target-specific example

As always, let's start with a simple example that illustrates the difference between global and local scope in GNU Make.  The following Makefile has four targets: all, foo, bar, baz.  All four targets are phony; since I'm only interested in illustrating global and local scope I've ignored actually building any files.

all requires that foo and bar be built and bar needs baz.  The commands for each target all do the same thing.  They print the value of macro VAR using a shell echo.

.PHONY: all foo bar baz

VAR = global scope

all: foo bar
    @echo In $@ VAR is $(VAR)

foo:
    @echo In $@ VAR is $(VAR)

bar: VAR = local scope
bar: baz
    @echo In $@ VAR is $(VAR)

baz:
    @echo In $@ VAR is $(VAR)

VAR is initially defined to have the value global scope.  That's the value VAR will have anywhere in the Makefile; unless, of course, that value is overriden using a target- or pattern-specific macro.

So illustrate local scope I've redefined VAR to local scope for the rule that creates bar.

A target-specific macro definition is exactly like a normal macro definition (it uses the same =, :=, += and ?= operators) but it is preceded by the name of the target (and its colon) for which the macro should be defined.

In the Makefile above VAR is set to local scope for the bar rule by writing:

bar: VAR = local scope

If you run make on this Makefile you'll get the following output:

In foo VAR is global scope
In baz VAR is local scope
In bar VAR is local scope
In all VAR is global scope

You can clearly see that GNU Make is following its standard depth-first, left-to-right search pattern building foo (it's the first prerequisite of all), then baz (which is a prerequisite of bar which is the second prerequisite of all), then bar and finally all.

And sure enough within the rule for bar the value of VAR is local scope.  And, as you expect since there's no local definition of VAR for all and foo, VAR has the value global scope in those rules.

But what about baz.  The Makefile output shows that in baz the value of VAR is local scope, yet there was no explicit target-specific definition of VAR for baz.

baz has the same locally scoped macros as bar because baz is a prerequisite of bar.  In fact, target-specific variables are defined for a target and all prerequisites of that target and all their prerequisites and so on.    A target-specific variable's scope is the entire tree of targets starting from the target for which the variable was defined.

Makefiles - Compile all .cpp files object .o files

Suppose I have project directory looks like this:

/project
    Makefile
    main
    /src
        main.cpp
        foo.cpp
        foo.h
        bar.cpp
        bar.h
    /obj
        main.o
        foo.o
        bar.o

What I would like my makefile to do would be to compile all .cpp files in the /src folder to .o files in the /obj folder, then link all the .o files in /obj into the output binary in the root folder /project.

So, the makefile part will be as easy as below:

Makefile

CPP_FILES := $(wildcard src/*.cpp)
OBJ_FILES := $(addprefix obj/,$(notdir $(CPP_FILES:.cpp=.o)))
LD_FLAGS := ...
CC_FLAGS := ...

main.exe: $(OBJ_FILES)
   g++ $(LD_FLAGS) -o $@ $^

obj/%.o: src/%cpp
   g++ $(CC_FLAGS) -c -o $@ $<

Makefiles

Makefiles
Make searches the current directory for the makefile to use, e.g. GNU make searches files in order for a file named one of GNUmakefile, makefile, Makefile and then runs the specified (or default) target(s) from (only) that file.

The makefile language is similar to declarative programming. This class of language, in which necessary end conditions are described but the order in which actions are to be taken is not important, is sometimes confusing to programmers used to imperative programming.
One problem in build automation is the tailoring of a build process to a given platform. For instance, the compiler used on one platform might not accept the same options as the one used on another. This is not well handled by Make. This problem is typically handled by generating platform specific build instructions, which in turn are processed by Make. Common tools for this process are Autoconf and CMake.

Rules
A makefile consists of rules. Each rule begins with a textual dependency line which defines a target followed by a colon (:) and optionally an enumeration of components (files or other targets) on which the target depends. The dependency line is arranged so that the target (left hand of the colon) depends on components (right hand of the colon). It is common to refer to components as prerequisites of the target.

For example, a C .o object file is created from .c files, so you need to have .c files first (i.e. specific object file target depends on a C source file and header files). Because Make itself does not understand, recognize or distinguish different kinds of files, this opens up a possibility for human error. A forgotten or an extra dependency may not be immediately obvious and may result in subtle bugs in the generated software. It is possible to write makefiles which generate these dependencies by calling third-party tools, and some makefile generators, such as the Automake toolchain provided by the GNU Project, can do so automatically.

After each dependency line, a series of command lines may follow which define how to transform the components (usually source files) into the target (usually the "output"). If any of the components have been modified, the command lines are run.

Make can decide where to start through topological sorting.
Each command line must begin with a tab character to be recognized as a command. The tab is a whitespace character, but the space character does not have the same special meaning. This is problematic, since there may be no visual difference between a tab and a series of space characters. This aspect of the syntax of makefiles is often subject to criticism.

Each command is executed by a separate shell or command-line interpreter instance. Since operating systems use different command-line interpreters this can lead to unportable makefiles. For instance, GNU Make by default executes commands with /bin/sh, where Unix commands like cp are normally used. In contrast to that, Microsoft's nmake executes commands with cmd.exe where batch commands like copy are available but not necessarily cp.

    target [target ...]: [component ...]
    [<TAB>command 1]
           .
           .
           .
    [<TAB>command n]

Usually each rule has a single unique target, rather than multiple targets.
A rule may have no command lines defined. The dependency line can consist solely of components that refer to targets, for example:

    realclean: clean distclean

The command lines of a rule are usually arranged so that they generate the target. An example: if "file.html" is newer, it is converted to text. The contents of the makefile:

    file.txt: file.html
            lynx -dump file.html > file.txt

The above rule would be triggered when Make updates "file.txt". In the following invocation, Make would typically use this rule to update the "file.txt" target if "file.html" were newer.

    make file.txt

Command lines can have one or more of the following three prefixes:
a hyphen-minus (-), specifying that errors are ignored
an at sign (@), specifying that the command is not printed to standard output before it is executed
a plus sign (+), the command is executed even if Make is invoked in a "do not execute" mode
Ignoring errors and silencing echo can alternatively be obtained via the special targets ".IGNORE" and ".SILENT".[8]
Microsoft's NMAKE has predefined rules that can be omitted from these makefiles, e.g. "c.obj $(CC)$(CFLAGS)".

Macros
A makefile can contain definitions of macros. Macros are usually referred to as variables when they hold simple string definitions, like "CC=gcc". Macros in makefiles may be overridden in the command-line arguments passed to the Make utility. Environment variables are also available as macros.
Macros allow users to specify the programs invoked and other custom behavior during the build process. For example, the macro "CC" is frequently used in makefiles to refer to the location of a C compiler, and the user may wish to specify a particular compiler to use.
New macros (or simple "variables") are traditionally defined using capital letters:

    MACRO = definition

A macro is used by expanding it. Traditionally this is done by enclosing its name inside $(). A rarely used but equivalent form uses curly braces rather than parenthesis, i.e. ${}.
    NEW_MACRO = $(MACRO)-$(MACRO2)
Macros can be composed of shell commands by using the command substitution operator, denoted by backticks (`).
    YYYYMMDD  = ` date `
The content of the definition is stored "as is". Lazy evaluation is used, meaning that macros are normally expanded only when their expansions are actually required, such as when used in the command lines of a rule. An extended example:
    PACKAGE   = package
    VERSION   = ` date +"%Y.%m%d" `
    ARCHIVE   = $(PACKAGE)-$(VERSION)

    dist:
            #  Notice that only now macros are expanded for shell to interpret:
            #      tar -cf package-`date +"%Y%m%d"`.tar

            tar -zcf $(ARCHIVE).tar .
The generic syntax for overriding macros on the command line is:
    make MACRO="value" [MACRO="value" ...] TARGET [TARGET ...]
Makefiles can access any of a number of predefined internal macros, with '?' and '@' being the most common.
    target: component1 component2
            echo $? contains those components, which need attention (i.e. they ARE YOUNGER than current TARGET).
            echo $@ evaluates to current TARGET name from among those left of the colon.

Suffix rules
Suffix rules have "targets" with names in the form .FROM.TO and are used to launch actions based on file extension. In the command lines of suffix rules, POSIX specifies[9] that the internal macro $< refers to the prerequisite and $@ refers to the target. In this example, which converts any HTML file into text, the shell redirection token > is part of the command line whereas $< is a macro referring to the HTML file:

    .SUFFIXES: .txt .html

    # From .html to .txt
    .html.txt:
            lynx -dump $<   >   $@

When called from the command line, the above example expands.

    $ make -n file.txt
    lynx -dump file.html > file.txt

Other elements
Single-line comments are started with the hash symbol (#).
Some directives in makefiles can include other makefiles.
Line continuation is indicated with a backslash \ character at the end of a line.

    target: component \
            component
    <TAB>command ;          \
    <TAB>command |          \
    <TAB>piped-command

Example makefiles
Makefiles are traditionally used for compiling code (*.c, *.cc, *.C, etc.), but they can also be used for providing commands to automate common tasks. One such makefile is called from the command line:

    make                        # Without argument runs first TARGET
    make help                   # Show available TARGETS
    make dist                   # Make a release archive from current dir

The makefile:

    PACKAGE      = package
    VERSION      = ` date "+%Y.%m%d%" `
    RELEASE_DIR  = ..
    RELEASE_FILE = $(PACKAGE)-$(VERSION)

    # Notice that the variable LOGNAME comes from the environment in
    # POSIX shells.
    #
    # target: all - Default target. Does nothing.
    all:
            echo "Hello $(LOGNAME), nothing to do by default"
            # very rarely: echo "Hello ${LOGNAME}, nothing to do by default"
            echo "Try 'make help'"

    # target: help - Display callable targets.
    help:
            egrep "^# target:" [Mm]akefile

    # target: list - List source files
    list:
            # Won't work. Each command is in separate shell
            cd src
            ls

            # Correct, continuation of the same shell
            cd src; \
            ls

    # target: dist - Make a release.
    dist:
            tar -cf  $(RELEASE_DIR)/$(RELEASE_FILE) && \
            gzip -9  $(RELEASE_DIR)/$(RELEASE_FILE).tar


Below is a very simple makefile that by default (the "all" rule is listed first) compiles a source file called "helloworld.c" using the gcc C compiler and also provides a "clean" target to remove the generated files if the user desires to start over. The $@ and $< are two of the so-called internal macros (also known as automatic variables) and stand for the target name and "implicit" source, respectively. In the example below, $^ expands to a space delimited list of the prerequisites. There are a number of other internal macros.

    CC     = gcc
    CFLAGS = -g

    all: helloworld

    helloworld: helloworld.o
            # Commands start with TAB not spaces
            $(CC) $(LDFLAGS) -o $@ $^

    helloworld.o: helloworld.c
            $(CC) $(CFLAGS) -c -o $@ $<

    clean: FRC
            rm -f helloworld helloworld.o

    # This pseudo target causes all targets that depend on FRC
    # to be remade even in case a file with the name of the target exists.
    # This works with any make implementation under the assumption that
    # there is no file FRC in the current directory.
    FRC:


Many systems come with predefined Make rules and macros to specify common tasks such as compilation based on file suffix. This allows user to omit the actual (often unportable) instructions of how to generate the target from the source(s). On such a system the above makefile could be modified as follows:

    all: helloworld

    helloworld: helloworld.o
        $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $^

    clean: FRC
        rm -f helloworld helloworld.o

    # This is an explicit suffix rule. It may be omitted on systems
    # that handle simple rules like this automatically.
    .c.o:
        $(CC) $(CFLAGS) -c $<

    FRC:
    .SUFFIXES: .c

That "helloworld.o" depends on "helloworld.c" is now automatically handled by Make. In such a simple example as the one illustrated here this hardly matters, but the real power of suffix rules becomes evident when the number of source files in a software project starts to grow. One only has to write a rule for the linking step and declare the object files as prerequisites. Make will then implicitly determine how to make all the object files and look for changes in all the source files.
Simple suffix rules work well as long as the source files do not depend on each other and on other files such as header files. Another route to simplify the build process is to use so-called pattern matching rules that can be combined with compiler-assisted dependency generation. As a final example requiring the gcc compiler and GNU Make, here is a generic makefile that compiles all C files in a folder to the corresponding object files and then links them to the final executable. Before compilation takes place, dependencies are gathered in makefile-friendly format into a hidden file ".depend" that is then included to the makefile.

    # Generic GNUMakefile

    # Just a snippet to stop executing under other make(1) commands
    # that won't understand these lines
    ifneq (,)
    This makefile requires GNU Make.
    endif

    PROGRAM = foo
    C_FILES := $(wildcard *.c)
    OBJS := $(patsubst %.c, %.o, $(C_FILES))
    CC = cc
    CFLAGS = -Wall -pedantic
    LDFLAGS =

    all: $(PROGRAM)

    $(PROGRAM): .depend $(OBJS)
        $(CC) $(CFLAGS) $(OBJS) $(LDFLAGS) -o $(PROGRAM)

    depend: .depend

    .depend: cmd = gcc -MM -MF depend $(var); cat depend >> .depend;
    .depend:
        @echo "Generating dependencies..."
        @$(foreach var, $(C_FILES), $(cmd))
        @rm -f depend

    -include .depend

    # These are the pattern matching rules. In addition to the automatic
    # variables used here, the variable $* that matches whatever % stands for
    # can be useful in special cases.
    %.o: %.c
        $(CC) $(CFLAGS) -c $< -o $@

    %: %.c
        $(CC) $(CFLAGS) -o $@ $<

    clean:
        rm -f .depend *.o

    .PHONY: clean depend