dribs and drabs for makefile knowledge

archive_files.md

Archive files are files containing named sub-files called members; they are maintained with the program ar and their main use is as subroutine libraries for linking.

####Archive Members as Targets#### An individual member of an archive file can be used as a target or prerequisite in make.

archive(member)

This construct is available only in targets and prerequisites, not in recipes! Most programs that you might use in recipes do not support this syntax and cannot act directly on archive members. Only ar and other programs specifically designed to operate on archives can do so. Therefore, valid recipes to update an archive member target probably must use ar.

foolib(hack.o) : hack.o
        ar cr foolib hack.o

In fact, nearly all archive member targets are updated in just this way and there is an implicit rule to do it for you. Please note: The ‘c’ flag to ar is required if the archive file does not already exist.

To specify several members in the same archive, you can write all the member names together between the parentheses. For example:

foolib(hack.o kludge.o)

You can also use shell-style wildcards in an archive member reference.

####Implicit Rule for Archive Member Targets#### Recall that a target that looks like a(m) stands for the member named m in the archive file a.

When make looks for an implicit rule for such a target, as a special feature it considers implicit rules that match (m), as well as those that match the actual target a(m).

This causes one special rule whose target is (%) to match. This rule updates the target a(m) by copying the file m into the archive. For example, it will update the archive member target foo.a(bar.o) by copying the file bar.o into the archive foo.a as a member named bar.o.

When this rule is chained with others, the result is very powerful. Thus, ‘make "foo.a(bar.o)"’ (the quotes are needed to protect the ‘(’ and ‘)’ from being interpreted specially by the shell) in the presence of a file bar.c is enough to cause the following recipe to be run, even without a makefile:

cc -c bar.c -o bar.o
ar r foo.a bar.o
rm -f bar.o

Here make has envisioned the file bar.o as an intermediate file.

Implicit rules such as this one are written using the automatic variable ‘$%’.

####Updating Archive Symbol Directories#### An archive file that is used as a library usually contains a special member named __.SYMDEF that contains a directory of the external symbol names defined by all the other members. After you update any other members, you need to update __.SYMDEF so that it will summarize the other members properly. This is done by running the ranlib program:

ranlib archivefile

Normally you would put this command in the rule for the archive file, and make all the members of the archive file prerequisites of that rule. For example,

libfoo.a: libfoo.a(x.o) libfoo.a(y.o) …
        ranlib libfoo.a

The effect of this is to update archive members x.o, y.o, etc., and then update the symbol directory member __.SYMDEF by running ranlib. The rules for updating the members are not shown here; most likely you can omit them and use the implicit rule which copies files into the archive, as described in the preceding section.

This is not necessary when using the GNU ar program, which updates the __.SYMDEF member automatically.

automatic_variables.md

It’s very important that you recognize the limited scope in which automatic variable values are available: they only have values within the recipe. In particular, you cannot use them anywhere within the target list of a rule; they have no value there and will expand to the empty string. Also, they cannot be accessed directly within the prerequisite list of a rule. A common mistake is attempting to use $@ within the prerequisites list; this will not work. However, there is a special feature of GNU make, secondary expansion , which will allow automatic variable values to be used in prerequisite lists.

####$@#### The file name of the target of the rule. If the target is an archive member, then ‘$@’ is the name of the archive file. In a pattern rule that has multiple targets, ‘$@’ is the name of whichever target caused the rule’s recipe to be run.

####$%#### The target member name, when the target is an archive member. For example, if the target is foo.a(bar.o) then ‘$%’ is bar.o and ‘$@’ is foo.a. ‘$%’ is empty when the target is not an archive member.

####$<#### The name of the first prerequisite. If the target got its recipe from an implicit rule, this will be the first prerequisite added by the implicit rule.

####$?#### The names of all the prerequisites that are newer than the target, with spaces between them. For prerequisites which are archive members, only the named member is used.

lib: foo.o bar.o lose.o win.o
        ar r lib $?

####$^##### The names of all the prerequisites, with spaces between them. For prerequisites which are archive members, only the named member is used . A target has only one prerequisite on each other file it depends on, no matter how many times each file is listed as a prerequisite. So if you list a prerequisite more than once for a target, the value of $^ contains just one copy of the name. This list does not contain any of the order-only prerequisites; for those see the ‘$|’ variable, below.

####$+#### This is like ‘$^’, but prerequisites listed more than once are duplicated in the order they were listed in the makefile. This is primarily useful for use in linking commands where it is meaningful to repeat library file names in a particular order.

####$|#### The names of all the order-only prerequisites, with spaces between them.

####$*#### The stem with which an implicit rule matches. If the target is dir/a.foo.b and the target pattern is a.%.b then the stem is dir/foo. The stem is useful for constructing names of related files.

In a static pattern rule, the stem is part of the file name that matched the ‘%’ in the target pattern.

In an explicit rule, there is no stem; so ‘$’ cannot be determined in that way. Instead, if the target name ends with a recognized suffix, ‘$’ is set to the target name minus the suffix. For example, if the target name is ‘foo.c’, then ‘$’ is set to ‘foo’, since ‘.c’ is a suffix. GNU make does this bizarre thing only for compatibility with other implementations of make. **You should generally avoid using ‘$’ except in implicit rules or static pattern rules.** If the target name in an explicit rule does not end with a recognized suffix, ‘$*’ is set to the empty string for that rule.

---

Of the variables listed above, four have values that are single file names, and three have values that are lists of file names. These seven have variants that get just the file’s directory name or just the file name within the directory. The variant variables’ names are formed by appending ‘D’ or ‘F’, respectively. These variants are semi-obsolete in GNU make since the functions dir and notdir can be used to get a similar effect. Note, however, that the ‘D’ variants all omit the trailing slash which always appears in the output of the dir function.

####‘$(@D)’#### The directory part of the file name of the target, with the trailing slash removed. If the value of ‘$@’ is dir/foo.o then ‘$(@D)’ is dir. This value is . if ‘$@’ does not contain a slash.

####‘$(@F)’#### The file-within-directory part of the file name of the target. If the value of ‘$@’ is dir/foo.o then ‘$(@F)’ is foo.o. ‘$(@F)’ is equivalent to ‘$(notdir $@)’.

####‘$(*D)’#### ####‘$(*F)’#### The directory part and the file-within-directory part of the stem; dir and foo in this example.

####‘$(%D)’#### ####‘$(%F)’#### The directory part and the file-within-directory part of the target archive member name. This makes sense only for archive member targets of the form archive(member) and is useful only when member may contain a directory name.

####‘$(<D)’#### ####‘$(<F)’#### The directory part and the file-within-directory part of the first prerequisite.

####‘$(^D)’##### ####‘$(^F)’##### Lists of the directory parts and the file-within-directory parts of all prerequisites.

####‘$(+D)’#### ####‘$(+F)’#### Lists of the directory parts and the file-within-directory parts of all prerequisites, including multiple instances of duplicated prerequisites.

####‘$(?D)’#### ####‘$(?F)’#### Lists of the directory parts and the file-within-directory parts of all prerequisites that are newer than the target.

functions.md

####foreach### $(foreach var,words,text) Evaluate text with var bound to each word in words, and concatenate the results.

####wildcard####

####subst#### $(subst from,to,text) Replace from with to in text.

####patsubst### $(patsubst pattern,replacement,text) Replace words matching pattern with replacement in text.

####filter#### $(filter pattern…,text) Select words in text that match one of the pattern words.

####filter-out#### $(filter-out pattern…,text) Select words in text that do not match any of the pattern words.

####word### $(word n,text) Extract the nth word (one-origin) of text.

####words#### $(words text) Count the number of words in text.

####shell#### $(shell command) Execute a shell command and return its output.

####eval#### $(eval text) Evaluate text then read the results as makefile commands. Expands to the empty string.

Multiple_Rules_for_One_Target.md

An extra rule with just prerequisites can be used to give a few extra prerequisites to many files at once. For example, makefiles often have a variable, such as objects, containing a list of all the compiler output files in the system being made. An easy way to say that all of them must be recompiled if config.h changes is to write the following:

objects = foo.o bar.o
foo.o : defs.h
bar.o : defs.h test.h
$(objects) : config.h

This could be inserted or taken out without changing the rules that really specify how to make the object files, making it a convenient form to use if you wish to add the additional prerequisite intermittently.

Another wrinkle is that the additional prerequisites could be specified with a variable that you set with a command line argument to make

extradeps=
$(objects) : $(extradeps)

means that the command ‘make extradeps=foo.h’ will consider foo.h as a prerequisite of each object file, but plain ‘make’ will not.

order-only_prerequisites.md

There are actually two different types of prerequisites understood by GNU make: normal prerequisites and order-only prerequisites.

Occasionally, however, you have a situation where you want to impose a specific ordering on the rules to be invoked without forcing the target to be updated if one of those rules is executed. In that case, you want to define order-only prerequisites. Order-only prerequisites can be specified by placing a pipe symbol (|) in the prerequisites list: any prerequisites to the left of the pipe symbol are normal; any prerequisites to the right are order-only:

targets : normal-prerequisites | order-only-prerequisites

Consider an example where your targets are to be placed in a separate directory, and that directory might not exist before make is run. In this situation, you want the directory to be created before any targets are placed into it but, because the timestamps on directories change whenever a file is added, removed, or renamed, we certainly don’t want to rebuild all the targets whenever the directory’s timestamp changes. One way to manage this is with order-only prerequisites: make the directory an order-only prerequisite on all the targets:

OBJDIR := objdir
OBJS := $(addprefix $(OBJDIR)/,foo.o bar.o baz.o)

$(OBJDIR)/%.o : %.c
        $(COMPILE.c) $(OUTPUT_OPTION) $<

all: $(OBJS)

$(OBJS): | $(OBJDIR)

$(OBJDIR):
        mkdir $(OBJDIR)

Now the rule to create the objdir directory will be run, if needed, before any ‘.o’ is built, but no ‘.o’ will be built because the objdir directory timestamp changed.

special_built-in_target_names.md

####.NOTPARALLEL#### If .NOTPARALLEL is mentioned as a target, then this invocation of make will be run serially, even if the ‘-j’ option is given. Any recursively invoked make command will still run recipes in parallel (unless its makefile also contains this target). Any prerequisites on this target are ignored.

.PHONY: all clean

all: a.txt b.txt c.txt d.txt

.NOTPARALLEL: 

%.txt: 
        sleep 2; touch $@ 

clean: 
        $(RM) *.txt 

####.SECONDARY#### The targets which .SECONDARY depends on are treated as intermediate files, except that they are never automatically deleted. .SECONDARY with no prerequisites causes all targets to be treated as secondary (i.e., no target is removed because it is considered intermediate).

%.txt: foo.log
    # pass

.SECONDARY: foo.log

%.log:
    # pass

####.PRECIOUS#### The targets which .PRECIOUS depends on are given the following special treatment: if make is killed or interrupted during the execution of their recipes, the target is not deleted. Also, if the target is an intermediate file, it will not be deleted after it is no longer needed, as is normally done. In this latter respect it overlaps with the .SECONDARY special target. You can also list the target pattern of an implicit rule (such as ‘%.o’) as a prerequisite file of the special target .PRECIOUS to preserve intermediate files created by rules whose target patterns match that file’s name.

%.txt: foo.log
    # pass

.PRECIOUS: %.log

%.log:
    # pass

####.SECONDEXPANSION#### If .SECONDEXPANSION is mentioned as a target anywhere in the makefile, then all prerequisite lists defined after it appears will be expanded a second time after all makefiles have been read in.

The true power of this feature only becomes apparent when you discover that secondary expansions always take place within the scope of the automatic variables for that target. This means that you can use variables such as $@, $*, etc. during the second expansion and they will have their expected values, just as in the recipe. All you have to do is defer the expansion by escaping the $. Also, secondary expansion occurs for both explicit and implicit (pattern) rules. Knowing this, the possible uses for this feature increase dramatically.

.SECONDEXPANSION:
main_OBJS := main.o try.o test.o
lib_OBJS := lib.o api.o

main lib: $$($$@_OBJS)

variables_reference.md

####Substitution References#### $(var:a=b) or ${var:a=b} To take the value of the variable var, replace every a at the end of a word with b in that value, and substitute the resulting string.

foo := a.o b.o c.o
bar := $(foo:.o=.c)

foo := a.o b.o c.o
bar := $(foo:%.o=%.c)

A substitution reference is actually an abbreviation for use of the patsubst expansion function.

####Computed Variable Names (nested variable reference)#### Variables may be referenced inside the name of a variable.

x = variable1
variable2 := Hello
y = $(subst 1,2,$(x))
z = y
a := $($($(z)))