--- make-doc-non-dfsg-3.81.orig/doc/make/make_11.html
+++ make-doc-non-dfsg-3.81/doc/make/make_11.html
@@ -0,0 +1,392 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
+<html>
+<!-- This file documents the GNU make utility, which determines
+automatically which pieces of a large program need to be recompiled,
+and issues the commands to recompile them.
+
+This is Edition 0.70, last updated 1 April 2006,
+of The GNU Make Manual, for GNU make version 3.81.
+
+Copyright C 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
+1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006
+Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being "A GNU Manual,"
+and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled "GNU Free Documentation
+License."
+
+(a) The FSF's Back-Cover Text is: "You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development."
+
+ -->
+<!-- Created on August, 17 2009 by texi2html 1.78 -->
+<!--
+Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
+ Karl Berry <karl@freefriends.org>
+ Olaf Bachmann <obachman@mathematik.uni-kl.de>
+ and many others.
+Maintained by: Many creative people.
+Send bugs and suggestions to <texi2html-bug@nongnu.org>
+
+-->
+<head>
+<title>GNU make: 11. Using make to Update Archive Files</title>
+
+<meta name="description" content="GNU make: 11. Using make to Update Archive Files">
+<meta name="keywords" content="GNU make: 11. Using make to Update Archive Files">
+<meta name="resource-type" content="document">
+<meta name="distribution" content="global">
+<meta name="Generator" content="texi2html 1.78">
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<style type="text/css">
+<!--
+a.summary-letter {text-decoration: none}
+pre.display {font-family: serif}
+pre.format {font-family: serif}
+pre.menu-comment {font-family: serif}
+pre.menu-preformatted {font-family: serif}
+pre.smalldisplay {font-family: serif; font-size: smaller}
+pre.smallexample {font-size: smaller}
+pre.smallformat {font-family: serif; font-size: smaller}
+pre.smalllisp {font-size: smaller}
+span.roman {font-family:serif; font-weight:normal;}
+span.sansserif {font-family:sans-serif; font-weight:normal;}
+ul.toc {list-style: none}
+-->
+</style>
+
+
+</head>
+
+<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
+
+<a name="Archives"></a>
+<a name="SEC128"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="make_10.html#SEC127" title="Previous section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC129" title="Next section in reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="make_10.html#SEC113" title="Beginning of this chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="make.html#SEC_Top" title="Up section"> Up </a>]</td>
+<td valign="middle" align="left">[<a href="make_12.html#SEC134" title="Next chapter"> >> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="make.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="make_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
+</tr></table>
+<h1 class="chapter"> 11. Using <code>make</code> to Update Archive Files </h1>
+
+<p><em>Archive files</em> are files containing named subfiles called
+<em>members</em>; they are maintained with the program <code>ar</code> and their
+main use is as subroutine libraries for linking.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC129">11.1 Archive Members as Targets</a></td><td> </td><td align="left" valign="top"> Archive members as targets.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC130">11.2 Implicit Rule for Archive Member Targets</a></td><td> </td><td align="left" valign="top"> The implicit rule for archive member targets.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC132">11.3 Dangers When Using Archives</a></td><td> </td><td align="left" valign="top"> Dangers to watch out for when using archives.
+</td></tr>
+<tr><td align="left" valign="top"><a href="#SEC133">11.4 Suffix Rules for Archive Files</a></td><td> </td><td align="left" valign="top"> You can write a special kind of suffix rule
+ for updating archives.
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="Archive-Members"></a>
+<a name="SEC129"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC128" title="Previous section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC130" title="Next section in reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC128" title="Beginning of this chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC128" title="Up section"> Up </a>]</td>
+<td valign="middle" align="left">[<a href="make_12.html#SEC134" title="Next chapter"> >> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="make.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="make_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
+</tr></table>
+<h2 class="section"> 11.1 Archive Members as Targets </h2>
+
+<p>An individual member of an archive file can be used as a target or
+prerequisite in <code>make</code>. You specify the member named <var>member</var> in
+archive file <var>archive</var> as follows:
+</p>
+<table><tr><td> </td><td><pre class="example"><var>archive</var>(<var>member</var>)
+</pre></td></tr></table>
+
+<p>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 <code>ar</code> and
+other programs specifically designed to operate on archives can do so.
+Therefore, valid commands to update an archive member target probably must
+use <code>ar</code>. For example, this rule says to create a member
+‘<tt>hack.o</tt>’ in archive ‘<tt>foolib</tt>’ by copying the file ‘<tt>hack.o</tt>’:
+</p>
+<table><tr><td> </td><td><pre class="example">foolib(hack.o) : hack.o
+ ar cr foolib hack.o
+</pre></td></tr></table>
+
+<p>In fact, nearly all archive member targets are updated in just this way
+and there is an implicit rule to do it for you. <strong>Please note:</strong> The
+‘<samp>c</samp>’ flag to <code>ar</code> is required if the archive file does not
+already exist.
+</p>
+<p>To specify several members in the same archive, you can write all the
+member names together between the parentheses. For example:
+</p>
+<table><tr><td> </td><td><pre class="example">foolib(hack.o kludge.o)
+</pre></td></tr></table>
+
+<p>is equivalent to:
+</p>
+<table><tr><td> </td><td><pre class="example">foolib(hack.o) foolib(kludge.o)
+</pre></td></tr></table>
+
+<a name="IDX629"></a>
+<p>You can also use shell-style wildcards in an archive member reference.
+See section <a href="make_4.html#SEC34">Using Wildcard Characters in File Names</a>. For
+example, ‘<samp>foolib(*.o)</samp>’ expands to all existing members of the
+‘<tt>foolib</tt>’ archive whose names end in ‘<samp>.o</samp>’; perhaps
+‘<samp>foolib(hack.o) foolib(kludge.o)</samp>’.
+</p>
+<hr size="6">
+<a name="Archive-Update"></a>
+<a name="SEC130"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC129" title="Previous section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC131" title="Next section in reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC128" title="Beginning of this chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC128" title="Up section"> Up </a>]</td>
+<td valign="middle" align="left">[<a href="make_12.html#SEC134" title="Next chapter"> >> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="make.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="make_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
+</tr></table>
+<h2 class="section"> 11.2 Implicit Rule for Archive Member Targets </h2>
+
+<p>Recall that a target that looks like ‘<tt><var>a</var>(<var>m</var>)</tt>’ stands for the
+member named <var>m</var> in the archive file <var>a</var>.
+</p>
+<p>When <code>make</code> looks for an implicit rule for such a target, as a special
+feature it considers implicit rules that match ‘<tt>(<var>m</var>)</tt>’, as well as
+those that match the actual target ‘<tt><var>a</var>(<var>m</var>)</tt>’.
+</p>
+<p>This causes one special rule whose target is ‘<tt>(%)</tt>’ to match. This
+rule updates the target ‘<tt><var>a</var>(<var>m</var>)</tt>’ by copying the file <var>m</var>
+into the archive. For example, it will update the archive member target
+‘<tt>foo.a(bar.o)</tt>’ by copying the <em>file</em> ‘<tt>bar.o</tt>’ into the
+archive ‘<tt>foo.a</tt>’ as a <em>member</em> named ‘<tt>bar.o</tt>’.
+</p>
+<p>When this rule is chained with others, the result is very powerful.
+Thus, ‘<samp>make "foo.a(bar.o)"</samp>’ (the quotes are needed to protect the
+‘<samp>(</samp>’ and ‘<samp>)</samp>’ from being interpreted specially by the shell) in
+the presence of a file ‘<tt>bar.c</tt>’ is enough to cause the following
+commands to be run, even without a makefile:
+</p>
+<table><tr><td> </td><td><pre class="example">cc -c bar.c -o bar.o
+ar r foo.a bar.o
+rm -f bar.o
+</pre></td></tr></table>
+
+<p>Here <code>make</code> has envisioned the file ‘<tt>bar.o</tt>’ as an intermediate
+file. See section <a href="make_10.html#SEC117">Chains of Implicit Rules</a>.
+</p>
+<p>Implicit rules such as this one are written using the automatic variable
+‘<samp>$%</samp>’. See section <a href="make_10.html#SEC121">Automatic Variables</a>.
+</p>
+<p>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 ‘<tt>foo.a(dir/file.o)</tt>’, <code>make</code> will perform
+automatic updating with this command:
+</p>
+<table><tr><td> </td><td><pre class="example">ar r foo.a dir/file.o
+</pre></td></tr></table>
+
+<p>which has the effect of copying the file ‘<tt>dir/file.o</tt>’ into a member
+named ‘<tt>file.o</tt>’. In connection with such usage, the automatic variables
+<code>%D</code> and <code>%F</code> may be useful.
+</p>
+<table class="menu" border="0" cellspacing="0">
+<tr><td align="left" valign="top"><a href="#SEC131">11.2.1 Updating Archive Symbol Directories</a></td><td> </td><td align="left" valign="top"> How to update archive symbol directories.
+</td></tr>
+</table>
+
+<hr size="6">
+<a name="Archive-Symbols"></a>
+<a name="SEC131"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC130" title="Previous section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC132" title="Next section in reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC128" title="Beginning of this chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC130" title="Up section"> Up </a>]</td>
+<td valign="middle" align="left">[<a href="make_12.html#SEC134" title="Next chapter"> >> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="make.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="make_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
+</tr></table>
+<h3 class="subsection"> 11.2.1 Updating Archive Symbol Directories </h3>
+
+<p>An archive file that is used as a library usually contains a special member
+named ‘<tt>__.SYMDEF</tt>’ 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 ‘<tt>__.SYMDEF</tt>’ so that it will summarize the
+other members properly. This is done by running the <code>ranlib</code> program:
+</p>
+<table><tr><td> </td><td><pre class="example">ranlib <var>archivefile</var>
+</pre></td></tr></table>
+
+<p>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,
+</p>
+<table><tr><td> </td><td><pre class="example">libfoo.a: libfoo.a(x.o) libfoo.a(y.o) …
+ ranlib libfoo.a
+</pre></td></tr></table>
+
+<p>The effect of this is to update archive members ‘<tt>x.o</tt>’, ‘<tt>y.o</tt>’,
+etc., and then update the symbol directory member ‘<tt>__.SYMDEF</tt>’ by
+running <code>ranlib</code>. 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.
+</p>
+<p>This is not necessary when using the GNU <code>ar</code> program, which
+updates the ‘<tt>__.SYMDEF</tt>’ member automatically.
+</p>
+<hr size="6">
+<a name="Archive-Pitfalls"></a>
+<a name="SEC132"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC131" title="Previous section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC133" title="Next section in reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC128" title="Beginning of this chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC128" title="Up section"> Up </a>]</td>
+<td valign="middle" align="left">[<a href="make_12.html#SEC134" title="Next chapter"> >> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="make.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="make_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
+</tr></table>
+<h2 class="section"> 11.3 Dangers When Using Archives </h2>
+
+<p>It is important to be careful when using parallel execution (the
+<code>-j</code> switch; see section <a href="make_5.html#SEC64">Parallel Execution</a>) and archives.
+If multiple <code>ar</code> commands run at the same time on the same archive
+file, they will not know about each other and can corrupt the file.
+</p>
+<p>Possibly a future version of <code>make</code> 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 <code>-j</code>.
+</p>
+<hr size="6">
+<a name="Archive-Suffix-Rules"></a>
+<a name="SEC133"></a>
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC132" title="Previous section in reading order"> < </a>]</td>
+<td valign="middle" align="left">[<a href="make_12.html#SEC134" title="Next section in reading order"> > </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="#SEC128" title="Beginning of this chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="#SEC128" title="Up section"> Up </a>]</td>
+<td valign="middle" align="left">[<a href="make_12.html#SEC134" title="Next chapter"> >> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="make.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="make_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
+</tr></table>
+<h2 class="section"> 11.4 Suffix Rules for Archive Files </h2>
+
+<p>You can write a special kind of suffix rule for dealing with archive
+files. See section <a href="make_10.html#SEC126">Old-Fashioned Suffix Rules</a>, for a full explanation of suffix rules.
+Archive suffix rules are obsolete in GNU <code>make</code>, because pattern
+rules for archives are a more general mechanism (see section <a href="#SEC130">Implicit Rule for Archive Member Targets</a>). But they are retained for compatibility with other
+<code>make</code>s.
+</p>
+<p>To write a suffix rule for archives, you simply write a suffix rule
+using the target suffix ‘<samp>.a</samp>’ (the usual suffix for archive files).
+For example, here is the old-fashioned suffix rule to update a library
+archive from C source files:
+</p>
+<table><tr><td> </td><td><pre class="example">.c.a:
+ $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
+ $(AR) r $@ $*.o
+ $(RM) $*.o
+</pre></td></tr></table>
+
+<p>This works just as if you had written the pattern rule:
+</p>
+<table><tr><td> </td><td><pre class="example">(%.o): %.c
+ $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
+ $(AR) r $@ $*.o
+ $(RM) $*.o
+</pre></td></tr></table>
+
+<p>In fact, this is just what <code>make</code> does when it sees a suffix rule
+with ‘<samp>.a</samp>’ as the target suffix. Any double-suffix rule
+‘<samp>.<var>x</var>.a</samp>’ is converted to a pattern rule with the target
+pattern ‘<samp>(%.o)</samp>’ and a prerequisite pattern of ‘<samp>%.<var>x</var></samp>’.
+</p>
+<p>Since you might want to use ‘<samp>.a</samp>’ as the suffix for some other kind
+of file, <code>make</code> also converts archive suffix rules to pattern rules
+in the normal way (see section <a href="make_10.html#SEC126">Old-Fashioned Suffix Rules</a>). Thus a double-suffix rule
+‘<samp>.<var>x</var>.a</samp>’ produces two pattern rules: ‘<samp>(%.o):
+%.<var>x</var></samp>’ and ‘<samp>%.a: %.<var>x</var></samp>’.
+</p>
+<hr size="6">
+<table cellpadding="1" cellspacing="1" border="0">
+<tr><td valign="middle" align="left">[<a href="#SEC128" title="Beginning of this chapter or previous chapter"> << </a>]</td>
+<td valign="middle" align="left">[<a href="make_12.html#SEC134" title="Next chapter"> >> </a>]</td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left"> </td>
+<td valign="middle" align="left">[<a href="make.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
+<td valign="middle" align="left">[<a href="make_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
+<td valign="middle" align="left">[<a href="make_19.html#SEC148" title="Index">Index</a>]</td>
+<td valign="middle" align="left">[<a href="make_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
+</tr></table>
+<p>
+ <font size="-1">
+ This document was generated by <em>Manoj Srivastava</em> on <em>August, 17 2009</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html 1.78</em></a>.
+ </font>
+ <br>
+
+</p>
+</body>
+</html>
![[patchlogo]](http://patch-tracker.debian.org/static/img/swirlpatch.png)