Another in a very short "series" about make.
If you need a small make refresher, see
this earlier entry.
Here we consider a way to write complex (multi-parameter) "subroutines" for GNU Make; this is important for code reuse.
Introduction
foo.o : foo.c
gcc -O -c foo.c -o foo.o
"If foo.c is newer than foo.o, rebuild foo.o by running
gcc -O -c foo.c". Files. Timestamps. Scripts (Bourne shell).
If make were nothing but that, it would be useful but
turgidly repetitive. For example, in the Makefile for a C
program with 100 C files, you would have 100
nearly-identical stanzas like the example above.
If you decided to change from gcc -O to gcc -O2, you
would have 100 stanzas to change.
The first way we improve things is to lift out the
constants, using make variables; our example stanza might
then become:
CC = gcc
CFLAGS = -O
foo.o : foo.c
$(CC) $(CFLAGS) -c foo.c -o foo.o
Now we can change from -O to -O2 with a single keystroke.
Make also has a bunch of "automatic variables", which take
on certain values in the context of a specific target. The
most important are:
$@ the name of the target
$< the name of the first prerequisite
Our example now becomes:
foo.o : foo.c
$(CC) $(CFLAGS) -c $< -o $@
Simple Subroutines
Imagine we were concerned with compiling two C files; we might have:
foo.o : foo.c
$(CC) $(CFLAGS) -c $< -o $@
bar.o : bar.c
$(CC) $(CFLAGS) -c $< -o $@
The two stanzas are identical except for the target-file "stem". Make lets us common-up all such stanzas with a single pattern rule:
%.o : %.c
$(CC) $(CFLAGS) -c $< -o $@
The bit of the filename matched by the % in the pattern is
called the "stem" and is available in the automatic variable
$*; so the rule could also be written as:
%.o : %.c
$(CC) $(CFLAGS) -c $*.c -o $*.o
A useful way to think of a pattern rule is as a "make subroutine" with exactly one parameter (the stem), which you have to hide in the target filename. (Pretty horrible programming-language syntax, but...)
Pattern rules are a good idea in 100% of the cases where they apply.
Complex Subroutines
In our EDA world, tool invocation is rarely simple enough to be susceptible to the wiles of a ("single parameter") pattern rule.
Here's how you might compile a bunch of Verilog with Icarus:
a.out : $(SRCS_V)
iverilog -o $@ -Idir1 -Idir2 -y dir1 -y dir2 $(SRCS_V)
After we lift out constants, we might get something like (and this is still simplified compared to Real Life...):
IVL = iverilog
INCDIRS = dir1 dir2
LIBDIRS = $(INCDIRS)
a.out : $(SRCS_V)
$(IVL) -o $@ $(INCDIRS:%=-I%) $(LIBDIRS:%=-y%) $(SRCS_V)
(Note: $(INCDIRS:%=-I%) means "take the value of the
variable INCDIRS and put a -I in front of every word".)
The problem here is that the "rule" for compiling Verilog with Icarus has several "parameters":
- the name of the desired output (
a.out) - the include directories required (
INCDIRS) - the library directories required (
LIBDIRS) - the source files to feed in (
SRCS_V)
There could easily be a few more. There is simply no way to
squeeze all those parameters through a normal make pattern
rule at once. (Well, you could... You could encode all
needed information in the target name. You might say:
compile : compile++a.out++INCDIRS=dir1+dir2++LIBDIRS=dir1+dir2++
and then have a pattern rule:
compile% : # now $* includes all the extra info
<fancy script that unpicks $* and then does what it likes>
But that's really, really horrible!)
What we want is to be able to vary the value of the
"parameter variables" depending on the target that make is
trying to rebuild. Happily, GNU Make provides an obscure
feature to do this: target-specific make variables.
I propose the convention that target-specific variables are in lower case, so they stand out from regular variables which are (by convention) in upper case.
You can make a very simple Makefile to see target-specific variables in action:
a : foo = a_value
b : foo = b_value
a :
@echo foo=$(foo)
b :
@echo foo=$(foo)
c :
@echo foo=$(foo)
When you run make a b c, you will see:
foo=a_value
foo=b_value
foo=
Back to our Icarus Verilog example. We might end up with a rule something like:
%.icarus : $(srcs_v)
$(IVL) -o $@ $(incdirs:%=-I%) $(libdirs:%=-y%) $(srcs_v)
This is, in effect, a "subroutine" for GNU Make with three parameters. We can now invoke this "subroutine" for two (or more) different Icarus runs:
foo.icarus : srcs_v = foo_top.v
foo.icarus : incdirs = include
foo.icarus : libdirs = lib
bar.icarus : srcs_v = bar_top.v bar_extra.v
bar.icarus : incdirs = wibble wobble
bar.icarus : libdirs = $(incdirs)
Nobody said it was pretty, but it does mean that an
arbitrarily-complex script for doing a piece of an EDA flow can
be captured by a pattern rule (using target-specific make
variables) -- in exactly one place. This can only be good for
increasing the robustness of any make-based build system.
[An earlier version of this note appeared in Verilab's internal newsletter.]
