11. Using make to Update Archive Files

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

11.1 Archive Members as Targets		Archive members as targets.
11.2 Implicit Rule for Archive Member Targets		The implicit rule for archive member targets.
11.3 Dangers When Using Archives		Dangers to watch out for when using archives.
11.4 Suffix Rules for Archive Files		You can write a special kind of suffix rule for updating archives.

11.1 Archive Members as Targets

An individual member of an archive file can be used as a target or prerequisite in make. You specify the member named member in archive file archive as follows:

archive(member)

This construct is available only in targets and prerequisites, not in commands! Most programs that you might use in commands 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 commands to update an archive member target probably must use ar. For example, this rule says to create a member `hack.o' in archive `foolib' by copying the file `hack.o':

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. 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)

is equivalent to:

foolib(hack.o) foolib(kludge.o)

You can also use shell-style wildcards in an archive member reference. See section Using Wildcard Characters in File Names. For example, `foolib(*.o)' expands to all existing members of the `foolib' archive whose names end in `.o'; perhaps `foolib(hack.o) foolib(kludge.o)'.

11.2 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 commands 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. See section Chains of Implicit Rules.

Implicit rules such as this one are written using the automatic variable `$%'. See section Automatic Variables.

An archive member name in an archive cannot contain a directory name, but it may be useful in a makefile to pretend that it does. If you write an archive member target `foo.a(dir/file.o)', make will perform automatic updating with this command:

ar r foo.a dir/file.o

which has the effect of copying the file `dir/file.o' into a member named `file.o'. In connection with such usage, the automatic variables %D and %F may be useful.

11.2.1 Updating Archive Symbol Directories

How to update archive symbol directories.

11.2.1 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.

11.3 Dangers When Using Archives

It is important to be careful when using parallel execution (the -j switch; see section Parallel Execution) and archives. If multiple ar commands run at the same time on the same archive file, they will not know about each other and can corrupt the file.

Possibly a future version of make will provide a mechanism to circumvent this problem by serializing all commands that operate on the same archive file. But for the time being, you must either write your makefiles to avoid this problem in some other way, or not use -j.

11.4 Suffix Rules for Archive Files

You can write a special kind of suffix rule for dealing with archive files. See section 10.7 Old-Fashioned Suffix Rules, for a full explanation of suffix rules. Archive suffix rules are obsolete in GNU make, because pattern rules for archives are a more general mechanism (see section 11.2 Implicit Rule for Archive Member Targets). But they are retained for compatibility with other makes.

To write a suffix rule for archives, you simply write a suffix rule using the target suffix `.a' (the usual suffix for archive files). For example, here is the old-fashioned suffix rule to update a library archive from C source files:

.c.a: $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o $(AR) r $@ $*.o $(RM) $*.o

This works just as if you had written the pattern rule:

(%.o): %.c $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o $(AR) r $@ $*.o $(RM) $*.o

In fact, this is just what make does when it sees a suffix rule with `.a' as the target suffix. Any double-suffix rule `.x.a' is converted to a pattern rule with the target pattern `(%.o)' and a prerequisite pattern of `%.x'.

Since you might want to use `.a' as the suffix for some other kind of file, make also converts archive suffix rules to pattern rules in the normal way (see section 10.7 Old-Fashioned Suffix Rules). Thus a double-suffix rule `.x.a' produces two pattern rules: `(%.o): %.x' and `%.a: %.x'.