Make

From miki
Jump to navigation Jump to search

make is an utility that determines automatically which pieces of a program need to be recompiled, and issues the commands to rebuild them. make uses a file called Makefile, which describes the relationships among files in the program.

References

  • Recursive Make Considered Harmful
    This papers explains that cutting big projects into smaller Makefiles that are called recursively greatly increase the build time, even when nothing changed. Instead it advices to include smaller Makefiles in a master one, such that the dependency tree is complete.


Tools related to Make:

  • ccache, a compiler cache.
  • CMake, a cross-platform Make.

Some alternatives to Make:

Quick Reference

Automatic Variables

Make Automatic Variables (most frequent)
$@ Target of the rule (if multi target, the one that cause the rule's command to run)
$% Target member name, when target is an archive member
$< Name of 1st prerequisite
$? All newer prerequisites (more recent than the target)
$^ All prerequisites
$+ All prerequisites, incl. duplicates
$* The stem with which the rule matched (e.g. if target is dir/a.foo.b, a pattern like a.%.b gives a stem dir/foo)
Automatic Variables - F and D variants:
$(@D) $(@F) Resp. the directory (w/o trailing /) and filename part of the target
$(*D) $(*F) Resp. the directory (w/o trailing /) and filename part of the stem
$(<D) $(<F) Resp. the directory (w/o trailing /) and filename part of the 1st prerequisite
$(^D) $(^F) Resp. the directory (w/o trailing /) and filename part of the all prerequisite
$(+D) $(+F) Resp. the directory (w/o trailing /) and filename part of the all prerequisites, incl. duplicates
$(?D) $(?F) Resp. the directory (w/o trailing /) and filename part of the newer prerequisites

How to Use Variables

Recursive vs. simple expansion
# Recursive expansion
CFLAGS = $(INCLUDES) -O
INCLUDES = -Ifoo -Ibar

all:
	echo $(CFLAGS)           # will echo '-Ifoo -Ibar -O'

# Simple expansion
x := foo
y := $(x) bar                    # expansion occurs here, once for all (y = foo bar)
x := later                       # y still = foo bar
Substitution References
foo = a.o b.o c.o
bar = $(foo:.o=.c)               # bar = a.c b.c c.c
Using % (equiv. to $(patsubst %.c,%.o,$(foo)):
foo = a.o b.o c.o
bar = $(foo:%.o=%.c)             # bar = a.c b.c c.c
Setting variables

Variables can be defined with = (recursively expanded variable), := (simply expanded variable), ?= (set if not set) or using keyword override.

This is illustrated in the script below. 

ARG = ----
override ARGO = ----
ARGQ ?= ----
ENV = ----
override ENVO = ----
ENVQ ?= ----

all:
	@echo "       =  over  ?=    # xxxx means variable was overridden."
	@echo "ENV: $(ENV) $(ENVO) $(ENVQ)"
	@echo "ARG: $(ARG) $(ARGO) $(ARGQ)" 
	@printf "%-20s %-20s %-20s\n" "$(origin ARG)" "$(origin ARGO)" "$(origin ARGQ)"
	@printf "%-20s %-20s %-20s\n" "$(origin ENV)" "$(origin ENVO)" "$(origin ENVQ)"

This produces the following output: 

ENV=xxxx ENVO=xxxx ENVQ=xxxx make ARG=xxxx ARGO=xxxx ARGQ=xxxx
#        =  over  ?=    # xxxx means variable was overridden.
# ENV: ---- ---- xxxx
# ARG: xxxx ---- xxxx
# file                 override             environment     
# command line         override             command line

Use flag -e to have environment variables to take precedence over file variables: 

ENV=xxxx ENVO=xxxx ENVQ=xxxx make -e ARG=xxxx ARGO=xxxx ARGQ=xxxx
#        =  over  ?=    # xxxx means variable was overridden.
# ENV: xxxx ---- xxxx
# ARG: xxxx ---- xxxx
# environment override override             environment         
# command line         override             command line

Note that ?= is actually a shorthand notation: 

FOO ?= bar

# is exactly equivalent to this (see section The origin Function):

ifeq ($(origin FOO), undefined)
FOO = bar
endif

So we can get the same for simply expanded variables: 

ifeq ($(origin FOO), undefined)
FOO := bar          # aka. FOO ?:= bar
endif

Functions for Filenames

$(dir names...)
Extract the directory part
$(notdir names...)
Extract the not-directory part
$(suffix names...)
Extract the suffix of each file name (incl. the period .)
$(basename names...)
Extract the basename of each file name
$(addsuffix suffix,names...)
Append the value of suffix to each file name.
$(addsuffix .c,foo bar)        # Produces 'foo.c bar.c'
$(addprefix prefix,names...)
$(addprefix src/,foo bar)      # Produces 'src/foo src/bar'
$(join list1,list2)
$(wildcard pattern)
$(realpath names...)
$(abspath names...)

Rules

all: 
	@echo About to make distribution files    # @ : disable command echoing
	-rm $(file)                               # - : don't stop on error (ignore)

Tips

Automatic Prerequisites

A standard solution (inspired from Makefile manual): 

# - see http://www.gnu.org/software/make/manual/make.html#Automatic-Prerequisites
# - Note that .d files are automatically regenerated because of the include command below.
# - Only 1 .d file generated, indep. of defines. So if include files depend on defines, the .d files will *NOT* be updated.
# - Note that we add *both* .o and .d files as targets (-MT flag). So any changes in the dependencies will regenerate both
#   .d and .o files.

-include $(SOURCES:.cpp=.d)

%.d: %.cpp
	$(CPP) $(CFLAGS) $(INCPATHS) -MM -MT $*.o -MT $*.d -MF $@ $<

A more advanced solution, where object files are stored in directory $(VARDIR), and have a suffix $(VARIANT): 

# - see http://www.gnu.org/software/make/manual/make.html#Automatic-Prerequisites
# - Note that .d files are automatically regenerated because of the include command below.
# - Only 1 .d file generated, indep. of defines. So if include files depend on defines, the .d files will *NOT* be updated.
# - [CHANGES] .o and .d files are stored in directory $(VARDIR)/, and .o have suffix $(VARIANT)

-include $(addprefix $(VARDIR)/, $(notdir $(SOURCES:.cpp=.d) ) )

$(VARDIR)/%.d: $(SRCDIR)/%.cpp
	$(CPP) $(CFLAGS) $(INCPATHS) -MM -MT $(VARDIR)/$*$$"(VARIANT)".o -MT $*.d -MF $@ $<


Limitations and Other solutions:

  • Only one .d file generated, indep. of $(DEFINES), so if $(DEFINES) changed, and include files depends on these defines, the .d files will not be updated.
A solution would be to name the .d files according to relevant defines, as we do for the .o files
  • Instead of adding both .d and .o files to the target, one could leave the .d file as the only target, and add .d file as an extra dependency to the .o file.


Yet another solution, where .d are generated along with .o files: 

SOURCES = …
OBJECTS = $(SOURCES:.c:.o)

ifeq "$(notdir $(CC)" "armcc"
# armcc will generate windows path. We use sed to fix the paths. Unfiltered deps are written to .ud files
# so that these are never included even if makefile is interrupted right after $(CC) (e.g. compilation errors)
%.o: %.c Makefile
      $(CC) $(CFLAGS) --unix_depend_format --depend $(@:.o=.ud) -c $< -o $@
      @sed -r 's!\\!/!g; s!([a-zA-Z]):/!/cygdrive/\1/!g' $(@:.o=.ud) > $(@:.o=.d)
else
# assuming 'gcc'
%.o: %.c Makefile
      $(CC) $(CFLAGS) -MMD -c $< -o $@
endif

# Create dependency file names from object names
DEPFILES = $(OBJECTS:.o=.d)

# Include the dependency files – if these do not exists, make will ignore them
-include $(DEPFILES)

Adding prefixes

SOURCES = src/foo.c src/bar.c

all:
	@echo $(addprefix subdir/,$(SOURCES))       # Use 'addprefix' function  - clearer
	@echo $(foreach V,$(SOURCES),subdir/$(V))   # Using 'foreach'           - powerful but less clear
	@echo $(SOURCES:%=subdir/%)                 # Using substitution        - even more clear when...
	@echo $(SOURCES:%.c=obj/%.o)                #                             ... changing ext as well

Conditionals

There are several types of conditionals in make:

Functions for conditionals
These are like regular if-then instructions, and can be used along with Automatic Variables (i.e. $@ $?...).
main.zip:: nfc.zip $(JAVA_SRC) Makefile
	$(if $(filter %.java,$?),echo 'Indenting (savagely) your code...'; uncrustify --no-backup -c indent.uncrustify.prefs $(filter %.java,$?))
Conditional Parts of Makefiles
These are like conditional directives in C preprocessor. From the documentation:

make evaluates conditionals when it reads a makefile. Consequently, you cannot use automatic variables in the tests of conditionals because they are not defined until recipes are run (see Automatic Variables). 

#Conditianals in rule recipes:
libs_for_gcc = -lgnu
normal_libs =

foo: $(objects)
ifeq ($(CC),gcc)
	$(CC) -o foo $(objects) $(libs_for_gcc)
else
	$(CC) -o foo $(objects) $(normal_libs)
endif

#Conditionals in variable definitions:
ifeq ($(CC),gcc)
	libs=$(libs_for_gcc)
else
	libs=$(normal_libs)
endif
     
foo: $(objects)
	$(CC) -o foo $(objects) $(libs)

Echo while 1st pass expansion

To have make echo some information while in the 1st pass expansion phase (i.e. before running target recipe), one can use a dummy variable and $(shell ...) function: 

x := $(shell echo >&2 'ARM Based Posix system with J9DROP libraries')

However a standard echo works as well: 

$(shell echo >&2 'ARM Based Posix system with J9DROP libraries')

Alternatively one can use info: 

$(info This is an information message.)

Change directory permanently

Reference: [2] 

CHDIR_SHELL := $(SHELL)
$(info CHDIR_SHELL is $(CHDIR_SHELL))
define chdir
   $(eval _D=$(firstword $(1) $(@D)))
   $(info $(MAKE): cd $(_D)) $(eval SHELL = cd $(_D); $(CHDIR_SHELL))
endef

# Can change permanently directory during the 1st pass...
$(eval cd some_dir2; /bin/sh)
$(shell echo >&2 NOW PWD is $$PWD)

all:
# Or in a rule recipe...
	$(call chdir,some_dir)
	echo "I'm now always in some_dir"
	echo gcc -Wall -o myTest myTest.c
	echo $$PWD

some_dir/myTest:
	$(call chdir)
	echo "I'm now always in some_dir"
	echo gcc -Wall -o myTest myTest.c
	echo $$PWD

Using Function Variables

Function variables can either be defined by assigned or using define... endef construct.

Assignments must be deferred (i.e. = and not :-), so that function is not evaluated at the time it is defined but only when used. Also if it contains comment symbol (#), these must be escaped: 

makefilecfg = $(shell echo "Creating configuration file '$R$(MAKEFILE_CFG)$Z'." >&2; \
	mkdir -p $(BAD) >&2; \
	echo "\# Common Platform custom configuration file." >$(MAKEFILE_CFG) ;\
	echo "\# CP build system includes this file to know which components/variants to build." >>$(MAKEFILE_CFG); \
	echo "\# See file 'tools/checkcfg.mk' for list of available components/variants." >>$(MAKEFILE_CFG); \
	echo "CPU :=$(CPU)"  >>$(MAKEFILE_CFG); \
	echo "OSAL:=$(OSAL)" >>$(MAKEFILE_CFG); \
	echo "JAVA:=$(JAVA)" >>$(MAKEFILE_CFG); \
	echo "NFC :=$(NFC)"  >>$(MAKEFILE_CFG); \
	echo "" >&2; \
	echo "You can now run '$Gmake$Z' to build the project with this configuration," >&2; \
	echo "or first edit the configuration file to customize this build." >&2 )

all:
	@(call $(makefilecfg))

The define... endef is a bit simpler: 

define makefilecfg
	$(shell echo "Creating configuration file '$R$(MAKEFILE_CFG)$Z'." >&2;
	mkdir -p $(BAD) >&2;
	echo "# Common Platform custom configuration file." >$(MAKEFILE_CFG);
	echo "# CP build system includes this file to know which components/variants to build." >>$(MAKEFILE_CFG);
	echo "# See file 'tools/checkcfg.mk' for list of available components/variants." >>$(MAKEFILE_CFG);
	echo "CPU :=$(CPU)"  >>$(MAKEFILE_CFG);
	echo "OSAL:=$(OSAL)" >>$(MAKEFILE_CFG);
	echo "JAVA:=$(JAVA)" >>$(MAKEFILE_CFG);
	echo "NFC :=$(NFC)"  >>$(MAKEFILE_CFG) )
endef

all:
	@(call $(makefilecfg))

Use $(info ...) instead of $(shell echo ...)

Use $(info ...) instead of $(shell echo ...) to print information message. The later invokes a new shell process for each printed message, and is notably slower on Cygwin platform for instance.

Test whether a file exists

ifeq "$(wildcard $(FILENAME))" ""
  $(error File $(FILENAME) does not exist.)
endif

Substitute space character into comma

Due to make syntax rules, converting a space-separated list into a comma-separated one is not straightforward. From GNU Make manual (§8.1):

Commas and unmatched parentheses or braces cannot appear in the text of an argument as written; leading spaces cannot appear in the text of the first argument as written. These characters can be put into the argument value by variable substitution. First define variables comma and space whose values are isolated comma and space characters, then substitute these variables where such characters are wanted [...]

The trick given in the manual is as follows: 

comma:= ,
empty:=
space:= $(empty) $(empty)
foo:= a b c
bar:= $(subst $(space),$(comma),$(foo))
# bar is now 'a,b,c'.

Escaping space, comma and other characters

As seen in the previous tip, one need to use a trick to pass spaces or commas as function parameters. Make however is very liberal regarding variable name, and one can even use a variable name that consists in a space character [3]: 

# Defining the $  or $( ) variable which has the value =
empty :=
space := $(empty) $(empty)
$(space) := $(space)

# Defining the $, or $(,) variable which has the value =
comma := ,
$(comma) := ,

# Defining the $= or $(=) variable which has the value =
equals := =
$(equals) := =

# Define the $# or $(#) variable which has the value #
hash := \#
$(hash) := \#

# Define the $: or $(:) variable which has the value :
colon := :
$(colon) := :

# Define the $($$) variable which has the value $
dollar := $$
$(dollar) := $$

; := ;
% := %

For instance: 

$(info [$( )] [$ ] [$(,)] [$,] [$(=)] [$=])
bar:= $(subst $ ,$,,$(foo))

Regarding space, some developers say at [4] that the following trick does not work: 

# The following might not work (space would actually contain a newline?)
space := 
space +=

Define multi-line strings

The best method is to use the define ... endef construct and export the variable, and then reference it as a shell variable with $$VARIABLE (see [5]): 

define USAGE_TEXT
Usage: ...

Option:
  First    this and that
  Second   Can refer to make $(variable) too
endef

export USAGE_TEXT
usage:
	@echo >&2 "$$USAGE_TEXT"

Using $(USAGE_TEXT) would not work, or require escaping the end of line, add '\n', and use echo -e.

Passing target to make sub-module

The same technique is illustrated in Make Manual at §3.6. We provide a default recipe to unknown target through a catch-all pattern rule, hence catching in $@ the name of the target given on the command-line. 

# file 'Makefile'

first:
	@echo target $@

# There is always an implicit 'make Makefile' issued by make.
# We add this target so that it is not caught by generic rule below
Makefile:
	@echo special target $@

# Try 'make second; touch second; make second'
# Thanks to force, target 'second' is always done
%: force
	@echo target $@
	@$(MAKE) $@ -f Makefile.mk               # pass $@ as target to Makefile.mk

# Don't forget semi-colon
force: ;

third:
	@echo target $@

Color messages

ESC1 := ^[
ESC2 := \033
ESC3 := $(shell echo "\033")

# Some colors make a better life - The ^[ is a verbatim escape character
R := $(ESC1)[0;31m
G := $(ESC2)[0;32m
B := $(ESC3)[0;34m
Z := $(ESC1)[0;0m

$(info A $Rcolorful $Zand $Gbeautiful $Bmessage$Z!)
all:
    echo "$Rcolorful $Zand $Gbeautiful $Bmessage$Z!"

Note that using \033[0;32m only works in shell echo command. The other two commands works in both $(info ...) and shell echo command.

Silent make by default, unless verbose requested

Make by default has echoing, i.e. it prints recipe command before executing them. This can be silented by

  • Prefixing command with @
  • Using option --silent or -s
  • Using special target .SILENT

A much better way is to disable echoing by default, and print relevant commands only in some case [6]: 

#Silent unless verbose (also for sub-make calls)
ifndef VERBOSE
.SILENT:
endif

# Same but syntax trick
$(VERBOSE).SILENT:

# Same but using MAKEFLAGS
ifndef VERBOSE
MAKEFLAGS += --silent
endif

Doing a make VERBOSE=1 will print the recipe commands (unless if they are prefixed with @). All the tricks above also affect sub-make calls.

Subst a variable only if defined

Note that by default pattern substitution only occurs if the given variable is not empty: 

$(shell touch foo.ld foo.c bar.c)

FOO=foo.ld

all: foo bar

foo: foo.c foo.c $(FOO)
    @echo gcc $(FOO:%=-T %) $(filter %.c,$^) -o $@
    @echo gcc $(patsubst %,-T %,$(filter %.ld,$^)) $(filter %.c,$^) -o $@

bar: bar.c $(BAR)
    @echo gcc $(BAR:%=-T %) $(filter %.c,$^) -o $@
    @echo gcc $(patsubst %,-T %,$(filter %.ld,$^)) $(filter %.c,$^) -o $@

This produces: 

gcc -T foo.ld foo.c bar.c -o foo
gcc -T foo.ld foo.c bar.c -o foo
gcc bar.c -o bar
gcc bar.c -o bar

Enable parallel build with MAKEFLAGS

Add flags -j to MAKEFLAGS: 

export MAKEFLAGS=-j            # Or -j 4 to limit to 4 processes in parallel
make

Be careful that not all Makefile are designed to run in parallel. Ideally, to be prevent parallel execution, the Makefile must contain the .NOTPARALLEL target: 

# This will prevent parallel execution of this Makefile
.NOTPARALLEL:

Use ccache to cache build objects

See ccache.

Frequent Mistakes

Use TABS to prefix commands in rules, *NOT* SPACES
Each rule in a makefile gives the set of commands that must be executed to build a given target from a given set of dependencies. These commands MUST be indented with a TAB character, not with SPACES. So make sure that the editor does not automatically change these tabs into spaces.
Don't call sub-project Makefile, include it
Calling subproject makefiles, so-called recursive make, has a huge performance penalty however the build (see Recursive Make Considered Harmful)
Don't add space around = (equal sign) in variable substitution
Do $(SOURCES:%.c=%.o), not $(SOURCES:%.c = %.o)
Use COMMA to separate parameters in $(call), not SPACE
Do $(call FCT,$(param)), not $(call FCT $(param)). The later will fail silently!

Bugs

ABS_DIRS := $(filter /%,$(DIRS)) $(abspath $(filter-out /%,$(DIRS)))
Retrieved from "https://miki.immie.org/mediawiki/index.php?title=Make&oldid=9827"