Return to make.texinfo CVS log

Up to [Early binutils] / binutils

Annotation of binutils/make.texinfo, revision 1.1

1.1     ! root        1: \input texinfo @c -*- Texinfo -*-
        !             2: @setfilename make.info
        !             3: @synindex vr fn
        !             4: 
        !             5: @c $Header: make.texinfo,v 2.9 88/07/10 17:52:55 mcgrath Rel $
        !             6: 
        !             7: @ifinfo
        !             8: This file documents the GNU Make utility.
        !             9: 
        !            10: Copyright (C) 1988 Free Software Foundation, Inc.
        !            11: 
        !            12: Permission is granted to make and distribute verbatim copies of
        !            13: this manual provided the copyright notice and this permission notice
        !            14: are preserved on all copies.
        !            15: 
        !            16: @ignore
        !            17: Permission is granted to process this file through TeX and print the
        !            18: results, provided the printed document carries copying permission
        !            19: notice identical to this one except for the removal of this paragraph
        !            20: (this paragraph not being relevant to the printed manual).
        !            21: 
        !            22: @end ignore
        !            23: Permission is granted to copy and distribute modified versions of this
        !            24: manual under the conditions for verbatim copying, provided also that
        !            25: the section entitled ``Copying Conditions'' is included exactly as in
        !            26: the original, and provided that the entire resulting derived work is
        !            27: distributed under the terms of a permission notice identical to this
        !            28: one.
        !            29: 
        !            30: Permission is granted to copy and distribute translations of this
        !            31: manual into another language, under the above conditions for modified
        !            32: versions, except that the text of the translations of the section
        !            33: entitled ``Copying Conditions'' must be approved for accuracy by the
        !            34: Foundation.
        !            35: @end ifinfo
        !            36: @c
        !            37: @setchapternewpage odd
        !            38: @settitle Make
        !            39: 
        !            40: @titlepage
        !            41: @sp 6
        !            42: @center @titlefont{GNU Make}
        !            43: @sp 1
        !            44: @center A Program for Directing Recompilation
        !            45: @sp 2
        !            46: @center April 1988
        !            47: @sp 5
        !            48: @center Richard M. Stallman, Roland McGrath
        !            49: @page
        !            50: @vskip 0pt plus 1filll
        !            51: Copyright @copyright{} 1988 Free Software Foundation, Inc.
        !            52: 
        !            53: Permission is granted to make and distribute verbatim copies of
        !            54: this manual provided the copyright notice and this permission notice
        !            55: are preserved on all copies.
        !            56: 
        !            57: Permission is granted to copy and distribute modified versions of this
        !            58: manual under the conditions for verbatim copying, provided also that
        !            59: the section entitled ``Copying Conditions'' is included exactly as in
        !            60: the original, and provided that the entire resulting derived work is
        !            61: distributed under the terms of a permission notice identical to this
        !            62: one.
        !            63: 
        !            64: Permission is granted to copy and distribute translations of this
        !            65: manual into another language, under the above conditions for modified
        !            66: versions, except that the text of the translation of the section
        !            67: entitled ``Copying Conditions'' must be approved for accuracy by the
        !            68: Foundation.
        !            69: @end titlepage
        !            70: @page
        !            71: 
        !            72: @node Copying, Bugs, Top, Top
        !            73: @unnumbered Copying Conditions
        !            74: @center (Clarified 11 Feb 1988)
        !            75: 
        !            76: The license agreements of most software companies keep you at the mercy of
        !            77: those companies.  By contrast, our general public license is intended to
        !            78: give everyone the right to share GNU Make.  To make sure that you get the
        !            79: rights we want you to have, we need to make restrictions that forbid anyone
        !            80: to deny you these rights or to ask you to surrender the rights.  Hence this
        !            81: license agreement.
        !            82: 
        !            83: Specifically, we want to make sure that you have the right to give away
        !            84: copies of GNU Make, that you receive source code or else can get it if you
        !            85: want it, that you can change GNU Make or use pieces of it in new free
        !            86: programs, and that you know you can do these things.
        !            87: 
        !            88: To make sure that everyone has such rights, we have to forbid you to
        !            89: deprive anyone else of these rights.  For example, if you distribute copies
        !            90: of GNU Make, you must give the recipients all the rights that you have.
        !            91: You must make sure that they, too, receive or can get the source code.  And
        !            92: you must tell them their rights.
        !            93: 
        !            94: Also, for our own protection, we must make certain that everyone finds out
        !            95: that there is no warranty for GNU Make.  If GNU Make is modified by someone
        !            96: else and passed on, we want its recipients to know that what they have is
        !            97: not what we distributed, so that any problems introduced by others will not
        !            98: reflect on our reputation.
        !            99: 
        !           100: Therefore we (Richard Stallman and the Free Software Foundation,
        !           101: Inc.) make the following terms which say what you must do to be
        !           102: allowed to distribute or change GNU Make.
        !           103: 
        !           104: @unnumberedsec Copying Policies
        !           105: 
        !           106: @enumerate
        !           107: @item
        !           108: You may copy and distribute verbatim copies of GNU Make source code as
        !           109: you receive it, in any medium, provided that you conspicuously and
        !           110: appropriately publish on each copy a valid copyright notice
        !           111: ``Copyright @copyright{} 1988 Free Software Foundation, Inc.'' (or
        !           112: with whatever year is appropriate), and include following the
        !           113: copyright notice a verbatim copy of the above disclaimer of warranty
        !           114: and of this License.  You may charge a distribution fee for the
        !           115: physical act of transferring a copy.
        !           116: 
        !           117: @item
        !           118: You may modify your copy or copies of GNU Make or any portion of it,
        !           119: and copy and distribute such modifications under the terms of
        !           120: Paragraph 1 above, provided that you also do the following:
        !           121: 
        !           122: @itemize @bullet
        !           123: @item
        !           124: cause the modified files to carry prominent notices stating
        !           125: that you changed the files and the date of any change; and
        !           126: 
        !           127: @item
        !           128: cause the whole of any work that you distribute or publish, that
        !           129: in whole or in part contains or is a derivative of Bison or any
        !           130: part thereof, to be licensed at no charge to all third parties on
        !           131: terms identical to those contained in this License Agreement
        !           132: (except that you may choose to grant more extensive warranty
        !           133: protection to some or all third parties, at your option).
        !           134: 
        !           135: @item
        !           136: You may charge a distribution fee for the physical act of
        !           137: transferring a copy, and you may at your option offer warranty
        !           138: protection in exchange for a fee.
        !           139: @end itemize
        !           140: 
        !           141: Mere aggregation of another unrelated program with this program (or its
        !           142: derivative) on a volume of a storage or distribution medium does not bring
        !           143: the other program under the scope of these terms.
        !           144: 
        !           145: @item
        !           146: You may copy and distribute GNU Make (or a portion or derivative of it,
        !           147: under Paragraph 2) in object code or executable form under the terms
        !           148: of Paragraphs 1 and 2 above provided that you also do one of the
        !           149: following:
        !           150: 
        !           151: @itemize @bullet
        !           152: @item
        !           153: accompany it with the complete corresponding machine-readable
        !           154: source code, which must be distributed under the terms of
        !           155: Paragraphs 1 and 2 above; or,
        !           156: 
        !           157: @item
        !           158: accompany it with a written offer, valid for at least three
        !           159: years, to give any third party free (except for a nominal
        !           160: shipping charge) a complete machine-readable copy of the
        !           161: corresponding source code, to be distributed under the terms of
        !           162: Paragraphs 1 and 2 above; or,
        !           163: 
        !           164: @item
        !           165: accompany it with the information you received as to where the
        !           166: corresponding source code may be obtained.  (This alternative is
        !           167: allowed only for noncommercial distribution and only if you
        !           168: received the program in object code or executable form alone.)
        !           169: @end itemize
        !           170: 
        !           171: For an executable file, complete source code means all the source code
        !           172: for all modules it contains; but, as a special exception, it need not
        !           173: include source code for modules which are standard libraries that
        !           174: accompany the operating system on which the executable file runs.
        !           175: 
        !           176: @item
        !           177: You may not copy, sublicense, distribute or transfer GNU Make except as
        !           178: expressly provided under this License Agreement.  Any attempt
        !           179: otherwise to copy, sublicense, distribute or transfer GNU Make is void
        !           180: and your rights to use the program under this License agreement shall
        !           181: be automatically terminated.  However, parties who have received
        !           182: computer software programs from you with this License Agreement will
        !           183: not have their licenses terminated so long as such parties remain in
        !           184: full compliance.
        !           185: 
        !           186: @item
        !           187: If you wish to incorporate parts of GNU Make into other free programs
        !           188: whose distribution conditions are different, write to the Free Software
        !           189: Foundation at 675 Mass Ave, Cambridge, MA 02139.  We have not yet worked
        !           190: out a simple rule that can be stated here, but we will often permit this.
        !           191: We will be guided by the two goals of preserving the free status of all
        !           192: derivatives of our free software and of promoting the sharing and reuse of
        !           193: software.
        !           194: @end enumerate
        !           195: 
        !           196: Your comments and suggestions about our licensing policies and our
        !           197: software are welcome!  Please contact the Free Software Foundation, Inc.,
        !           198: 675 Mass Ave, Cambridge, MA 02139, or call (617) 876-3296.
        !           199: 
        !           200: @unnumberedsec NO WARRANTY
        !           201: 
        !           202:   BECAUSE GNU MAKE IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY NO
        !           203: WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW.  EXCEPT
        !           204: WHEN OTHERWISE STATED IN WRITING, THE FREE SOFTWARE FOUNDATION, INC,
        !           205: RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU MAKE "AS IS" WITHOUT
        !           206: WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
        !           207: LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
        !           208: A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND
        !           209: PERFORMANCE OF GNU MAKE IS WITH YOU.  SHOULD GNU MAKE PROVE DEFECTIVE, YOU
        !           210: ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
        !           211: 
        !           212:  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL RICHARD M.
        !           213: STALLMAN, THE FREE SOFTWARE FOUNDATION, INC., AND/OR ANY OTHER PARTY
        !           214: WHO MAY MODIFY AND REDISTRIBUTE GNU MAKE AS PERMITTED ABOVE, BE LIABLE TO
        !           215: YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
        !           216: SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
        !           217: INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
        !           218: BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
        !           219: FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS) GNU MAKE, EVEN
        !           220: IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR
        !           221: ANY CLAIM BY ANY OTHER PARTY.
        !           222: 
        !           223: @node Top, Copying,, (DIR)
        !           224: @chapter Overview of @code{make}
        !           225: 
        !           226: The purpose of the @code{make} utility is to determine automatically which
        !           227: pieces of a large program need to be recompiled, and issue the commands to
        !           228: recompile them.  This manual describes the GNU implementation of
        !           229: @code{make}, which was implemented by Richard Stallman and Roland McGrath.
        !           230: 
        !           231: Our examples show C programs, since they are most common, but you can use
        !           232: @code{make} with any programming language whose compiler can be run with a
        !           233: shell command.  In fact, @code{make} is not limited to programs.  You can
        !           234: use it to describe any task where some files must be updated automatically
        !           235: from others whenever the others change.
        !           236: 
        !           237: To prepare to use @code{make}, you must write a file called
        !           238: the @dfn{makefile} that describes the relationships among files
        !           239: in your program, and the states the commands for updating each file.
        !           240: In a program, typically the executable file is updated from object
        !           241: files, which are in turn made by compiling source files.@refill
        !           242: 
        !           243: Once a suitable makefile exists, each time you change some source files,
        !           244: this simple shell command:
        !           245: 
        !           246: @example
        !           247: make
        !           248: @end example
        !           249: 
        !           250: @noindent
        !           251: suffices to perform all necessary recompilations.  The @code{make} program
        !           252: uses the makefile data base and the last-modification times of the files to
        !           253: decide which of the files need to be updated.  For each of those files, it
        !           254: issues the commands recorded in the data base.
        !           255: 
        !           256: @iftex
        !           257: Command arguments to @code{make} can be used to control which files should
        !           258: be recompiled, or how.  @xref{Running}.
        !           259: @end iftex
        !           260: 
        !           261: @menu
        !           262: * Copying::    Copying conditions for GNU Make.
        !           263: * Bugs::       If you have problems, or think you've found a bug.
        !           264: * Simple::     A simple example explained.
        !           265: * Makefiles::  The data base contains rules and variable definitions.
        !           266: * Rules::      A rule says how and when to remake one file.
        !           267: * Commands::   A rule contains shell commands that say how to remake.
        !           268: * Variables::  A variable holds a text string for substitution into rules.
        !           269: * Conditionals::Makefiles that do one thing or another depending on
        !           270:                 variable values.
        !           271: * Functions::  Functions can do text-processing within @code{make}.
        !           272: 
        !           273: * Running::    How to run @code{make}; how you can adjust the way
        !           274:                 @code{make} uses the makefile.
        !           275: 
        !           276: * Implicit::   Implicit rules take over if the makefile doesn't say
        !           277:                 how a file is to be remade.
        !           278: * Archives::   How to use @code{make} to update archive files.
        !           279: 
        !           280: * Features::   GNU @code{make}'s advanced features and how GNU @code{make}
        !           281:                 relates to other versions of @code{make}.
        !           282: * Missing::    Features of other @code{make}s not supported
        !           283:                 by GNU @code{make}.
        !           284: 
        !           285: * Concept Index::Index of cross-references to where concepts are discussed.
        !           286: * Name Index:: Index of cross-references for names of @code{make}'s
        !           287:                 variables, functions, special targets and directives.
        !           288: @end menu
        !           289: 
        !           290: @node Bugs, Simple, Copying, Top
        !           291: @section Problems and Bugs
        !           292: 
        !           293: If you have problems with GNU @code{make} or think you've found a bug,
        !           294: please report it to Roland McGrath; he doesn't promise to do anything
        !           295: but he might well want to fix it.
        !           296: 
        !           297: Before reporting a bug, make sure you've actually found a real bug.
        !           298: Carefully reread the documentation and see if it really says you can do
        !           299: what you're trying to do.  If it's not clear whether you should be able
        !           300: to do something or not, report that too; it's a bug in the documentation!
        !           301: 
        !           302: Before reporting a bug or trying to fix it yourself, try to isolate it to
        !           303: the smallest possible makefile that reproduces the problem.  Then send
        !           304: us the makefile and the exact results @code{make} gave you.  Also say what
        !           305: you expected to occur; this will help us decide whether the problem
        !           306: was really in the documentation.
        !           307: 
        !           308: Once you've got a precise problem, send email to (Internet)
        !           309: @samp{bug-gnu-utils@@prep.ai.mit.edu} or (UUCP)
        !           310: @samp{mit-eddie!prep.ai.mit.edu!bug-gnu-utils}.  Please include the version
        !           311: number of @code{make} you are using.  You can get this information with the
        !           312: command @samp{make -v -f /dev/null}.@refill
        !           313: 
        !           314: Non-bug suggestions are always welcome as well.
        !           315: If you have questions about things that are unclear in the documentation
        !           316: or are just obscure features, ask Roland McGrath; he'll be happy to help
        !           317: you out (but no promises).  You can send him electronic mail at Internet
        !           318: address @samp{roland@@wheaties.ai.mit.edu} or UUCP path
        !           319: @samp{mit-eddie!wheaties.ai.mit.edu!roland}.
        !           320: 
        !           321: @node Simple, Makefiles, Bugs, Top
        !           322: @section Simple Example of @code{make}
        !           323: 
        !           324: Suppose we have a text editor consisting of eight C source files and three
        !           325: header files.  We need a makefile to tell @code{make} how to compile and
        !           326: link the editor.  Assume that all the C files include @file{defs.h}, but
        !           327: only those defining editing commands include @file{commands.h} and only low
        !           328: level files that change the editor buffer include @file{buffer.h}.
        !           329: 
        !           330: To recompile the editor, each changed C source file must be recompiled.  If
        !           331: a header file has changed, to be safe each C source file that
        !           332: includes the header file must be recompiled.  Each compilation produces an
        !           333: object file corresponding to the source file.  Finally, if any source file
        !           334: has been recompiled, all the object files, whether newly made or saved from
        !           335: previous compilations, must be linked together to produce the new
        !           336: executable editor.
        !           337: 
        !           338: Here is a straightforward makefile that describes these criteria and says
        !           339: how to compile and link when the time comes:
        !           340: 
        !           341: @example
        !           342: edit : main.o kbd.o commands.o display.o \
        !           343:        insert.o search.o files.o utils.o
        !           344:         cc -o edit main.o kbd.o commands.o display.o \
        !           345:                    insert.o search.o files.o utils.o
        !           346: 
        !           347: main.o : main.c defs.h
        !           348:         cc -c main.c
        !           349: kbd.o : kbd.c defs.h command.h
        !           350:         cc -c kbd.c
        !           351: commands.o : command.c defs.h command.h
        !           352:         cc -c commands.c
        !           353: display.o : display.c defs.h buffer.h
        !           354:         cc -c display.c
        !           355: insert.o : insert.c defs.h buffer.h
        !           356:         cc -c insert.c
        !           357: search.o : search.c defs.h buffer.h
        !           358:         cc -c search.c
        !           359: files.o : files.c defs.h buffer.h command.h
        !           360:         cc -c files.c
        !           361: utils.o : utils.c defs.h
        !           362:         cc -c utils.c
        !           363: @end example
        !           364: 
        !           365: We split each long line into two lines using a backslash-newline; this is
        !           366: like using one long line, but is easier to read.
        !           367: 
        !           368: Each file that is generated by a program---that is to say, each file except
        !           369: for source files---is the @dfn{target} of a @dfn{rule} (@pxref{Rules}).
        !           370: (In this example, these are the object files such as @file{main.o},
        !           371: @file{kbd.o}, etc., and the executable file @file{edit}.)  The target
        !           372: appears at the beginning of a line, followed by a colon.
        !           373: 
        !           374: After the colon come the target's @dfn{dependencies}: all the files that
        !           375: are used as input when the target file is updated.  A target file needs to
        !           376: be recompiled or relinked if any of its dependencies changes.  In addition,
        !           377: any dependencies that are themselves automatically generated should be
        !           378: updated first.  In this example, @file{edit} depends on each of the eight
        !           379: object files; the object file @file{main.o} depends on the source file
        !           380: @file{main.c} and on the header file @file{defs.h}.
        !           381: 
        !           382: By default, @code{make} starts with the first rule (not counting rules
        !           383: whose target names start with @samp{.}).  This is called the @dfn{default
        !           384: goal}.  Therefore, we put the rule for the executable program @file{edit}
        !           385: first.  The other rules are processed because their targets appear as
        !           386: dependencies of the goal.
        !           387: 
        !           388: After each line containing a target and dependencies come one or more lines
        !           389: of shell commands that say how to update the target file.  These lines
        !           390: start with a tab to tell @code{make} that they are command lines.  But
        !           391: @code{make} does not know anything about how the commands work.  It is up
        !           392: to you to supply commands that will update the target file properly.
        !           393: All @code{make} does is execute the commands you have specified when the
        !           394: target file needs to be updated.
        !           395: 
        !           396: @subsection How @code{make} Processes This Makefile
        !           397: 
        !           398: After reading the makefile, @code{make} begins its real work by processing
        !           399: the first rule, the one for relinking @file{edit}; but before it can fully
        !           400: process this rule, it must process the rules for the files @file{edit}
        !           401: depends on: all the object files.  Each of these files is processed
        !           402: according to its own rule.  These rules say to update the @samp{.o} file by
        !           403: compiling its source file.  The recompilation must be done if the source
        !           404: file, or any of the header files named as dependencies, is more recent than
        !           405: the object file, or if the object file does not exist.
        !           406: 
        !           407: Before recompiling an object file, @code{make} considers updating its
        !           408: dependencies, the source file and header files.  This makefile does not
        !           409: specify anything to be done for them---the @samp{.c} and @samp{.h} files
        !           410: are not the targets of any rules---so nothing needs to be done.  But
        !           411: automatically generated C programs, such as made by Yacc (or Bison), would
        !           412: be updated by their own rules at this time.
        !           413: 
        !           414: After recompiling whichever object files need it, @code{make} can now
        !           415: decide whether to relink @file{edit}.  This must be done if the file
        !           416: @file{edit} does not exist, or if any of the object files are newer than
        !           417: it.  If an object file was just recompiled, it is now newer than
        !           418: @file{edit}, so @file{edit} will be relinked.
        !           419: 
        !           420: @subsection Variables Make Makefiles Simpler
        !           421: 
        !           422: In our example, we had to list all the object files twice in the rule for
        !           423: @file{edit} (repeated here):
        !           424: 
        !           425: @example
        !           426: edit : main.o kbd.o commands.o display.o \
        !           427:               insert.o search.o files.o utils.o
        !           428:         cc -o edit main.o kbd.o commands.o display.o \
        !           429:                    insert.o search.o files.o utils.o
        !           430: @end example
        !           431: 
        !           432: @vindex objects
        !           433: Such duplication is error-prone; if a new object file is added to the
        !           434: system, we might add it to one list and forget the other.  We can eliminate
        !           435: the risk and simplify the makefile by using a @dfn{variable}.  Variables
        !           436: allow a text string to be defined once and substituted in multiple places
        !           437: later (@pxref{Variables}).
        !           438: 
        !           439: It's standard practice for every makefile to have a variable named
        !           440: @code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj} or
        !           441: @code{OBJ} which is a list of all object file names.  We would define
        !           442: such a variable @code{objects} with a line like this in the makefile:@refill
        !           443: 
        !           444: @example
        !           445: objects = main.o kbd.o commands.o display.o \
        !           446:               insert.o search.o files.o utils.o
        !           447: @end example
        !           448: 
        !           449: @noindent
        !           450: Then, each place we want to put a list of the object file names, we can
        !           451: substitute the variable's value by writing @samp{$(objects)}
        !           452: (@pxref{Variables}).  Here is how the rule for @code{edit} looks as a
        !           453: result:
        !           454: 
        !           455: @example
        !           456: edit : $(objects)
        !           457:         cc -o edit $(objects)
        !           458: @end example
        !           459: 
        !           460: @subsection Letting @code{make} Deduce the Commands
        !           461: 
        !           462: It is not necessary to spell out the commands for compiling the individual
        !           463: C source files, because @code{make} can figure them out: it has an
        !           464: @dfn{implicit rule} for updating a @samp{.o} file from a correspondingly
        !           465: named @samp{.c} file using a @samp{cc -c} command.  For example, it will
        !           466: use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into
        !           467: @file{main.o}.  We can therefore omit the commands from the rules for the
        !           468: object files.  @xref{Implicit}.@refill
        !           469: 
        !           470: When a @samp{.c} file is used automatically in this way, it is also
        !           471: automatically added to the list of dependencies.  We can therefore omit
        !           472: the @samp{.c} files from the dependencies, provided we omit the commands.
        !           473: 
        !           474: Here is the entire example, with both of these changes, and a variable
        !           475: @code{objects} as suggested above:
        !           476: 
        !           477: @example
        !           478: objects =  main.o kbd.o commands.o display.o \
        !           479:  insert.o search.o files.o utils.o
        !           480: 
        !           481: edit : $(objects)
        !           482:         cc -o edit $(objects)
        !           483: 
        !           484: main.o : defs.h
        !           485: kbd.o : defs.h command.h
        !           486: commands.o : defs.h command.h
        !           487: display.o : defs.h buffer.h
        !           488: insert.o : defs.h buffer.h
        !           489: search.o : defs.h buffer.h
        !           490: files.o : defs.h buffer.h command.h
        !           491: utils.o : defs.h
        !           492: @end example
        !           493: 
        !           494: @noindent
        !           495: This is how we would write the makefile in actual practice.
        !           496: 
        !           497: @subsection Another Style of Makefile
        !           498: 
        !           499: Since the rules for the object files specify only dependencies, no
        !           500: commands, one can alternatively combine them by dependency instead of by
        !           501: target.  Here is what it looks like:
        !           502: 
        !           503: @example
        !           504: objects =  main.o kbd.o commands.o display.o \
        !           505:  insert.o search.o files.o utils.o
        !           506: 
        !           507: edit : $(objects)
        !           508:         cc -o edit $(objects)
        !           509: 
        !           510: $(objects) : defs.h
        !           511: kbd.o commands.o files.o : command.h
        !           512: display.o insert.o search.o files.o : buffer.h
        !           513: @end example
        !           514: 
        !           515: @noindent
        !           516: Here @file{defs.h} is given as a dependency of all the object files;
        !           517: @file{commands.h} and @file{buffer.h} are dependencies of the specific
        !           518: object files listed for them.
        !           519: 
        !           520: Whether this is better is a matter of taste: it is more compact, but some
        !           521: people dislike it because they find it clearer to put all the information
        !           522: about each target in one place.
        !           523: 
        !           524: @node Makefiles, Rules, Simple, Top
        !           525: @chapter Writing Makefiles
        !           526: 
        !           527: @cindex makefile
        !           528: The information that tells @code{make} how to recompile a system comes from
        !           529: reading a data base called the @dfn{makefile}.
        !           530: 
        !           531: @menu
        !           532: * Contents: Makefile Contents.   Overview of what you put in a makefile.
        !           533: * Names: Makefile Names.        Where @code{make} finds the makefile.
        !           534: * MAKEFILES Variable::           The environment can specify extra makefiles.
        !           535: * Include::                      How one makefile can use another makefile.
        !           536: @end menu
        !           537: 
        !           538: @node Makefile Contents, Makefile Names, Makefiles, Makefiles
        !           539: @section What Makefiles Contain
        !           540: 
        !           541: Makefiles contain four kinds of things: @dfn{rules}, @dfn{variable
        !           542: definitions}, @dfn{directives} and @dfn{comments}.  Rules, variables and
        !           543: directives are described at length in later chapters.@refill
        !           544: 
        !           545: @itemize @bullet
        !           546: @item
        !           547: A rule says when and how to remake one or more files, called the rule's
        !           548: @dfn{targets}.  It lists the other files that the targets @dfn{depend on},
        !           549: and may also give commands to use to create or update the targets.
        !           550: @xref{Rules}.
        !           551: 
        !           552: @item
        !           553: A variable definition is a line that specifies a text string value for
        !           554: a @dfn{variable} that can be substituted into the text later.  The
        !           555: simple makefile example (@pxref{Simple}) shows a variable definition
        !           556: for @code{objects} as a list of all object files.  @xref{Variables},
        !           557: for full details.
        !           558: 
        !           559: @item
        !           560: A directive is a command for @code{make} to do something special while
        !           561: reading the makefile.  These include:
        !           562: 
        !           563: @itemize @bullet
        !           564: @item
        !           565: Reading another makefile (@pxref{Include}).
        !           566: 
        !           567: @item
        !           568: Deciding (based on the values of variables) whether to use or
        !           569: ignore a part of the makefile (@pxref{Conditionals}).
        !           570: 
        !           571: @item
        !           572: Defining a variable from a verbatim string containing multiple lines
        !           573: (@pxref{Defining}).
        !           574: @end itemize
        !           575: 
        !           576: @item
        !           577: @cindex comments
        !           578: @samp{#} in a line of a makefile starts a comment.  It and the rest of
        !           579: the line are ignored.  Comments may appear on any of the lines in the
        !           580: makefile, except within a @code{define} directive, and perhaps within
        !           581: commands (where the shell decides what is a comment).  A line
        !           582: containing just a comment (with perhaps spaces before it) is
        !           583: effectively blank, and is ignored.
        !           584: @end itemize
        !           585: 
        !           586: @node Makefile Names, MAKEFILES Variable, Makefile Contents, Makefiles
        !           587: @section What Name to Give Your Makefile
        !           588: 
        !           589: By default, when @code{make} looks for the makefile, it tries the names
        !           590: @file{./makefile} and @file{./Makefile} in that order.  So normally you call
        !           591: your makefile by one of these two names, and @code{make} finds it
        !           592: automatically.  We recommend @file{Makefile} because it appears prominently
        !           593: near the beginning of a directory listing (right near other important
        !           594: files such as @file{README}).@refill
        !           595: 
        !           596: If @code{make} finds neither of these two names, it does not use any
        !           597: makefile.  Then you must specify a goal with a command argument, and
        !           598: @code{make} will attempt to figure out how to remake it using only its
        !           599: built-in implicit rules.  @xref{Implicit}.
        !           600: 
        !           601: If you want to use a nonstandard name for your makefile, you can specify
        !           602: the makefile name with the @samp{-f} option.  The arguments @samp{-f
        !           603: @var{name}} tell @code{make} to read the file @var{name} as the makefile.
        !           604: If you use more than one @samp{-f} option, you can specify several
        !           605: makefiles.  All the makefiles are effectively concatenated in the order
        !           606: specified.  The default makefile names @file{./makefile} and
        !           607: @file{./Makefile} are not used if you specify @samp{-f}.@refill
        !           608: 
        !           609: @node MAKEFILES Variable, Include, Makefile Names, Makefiles
        !           610: @section The Variable @code{MAKEFILES}
        !           611: 
        !           612: @vindex MAKEFILES
        !           613: If the environment variable @code{MAKEFILES} is defined, @code{make}
        !           614: considers its value as a list of names (separated by whitespace) of
        !           615: additional makefiles to be read before the others.  This works much like
        !           616: the @code{include} directive: various directories are searched for those
        !           617: files and the default goal is never taken from them.  @xref{Include}.  In
        !           618: addition, it is not an error if the files listed in @code{MAKEFILES} are
        !           619: not found.@refill
        !           620: 
        !           621: The main use of @code{MAKEFILES} is in communication between recursive
        !           622: invocations of @code{make} (@pxref{Recursion}).  It usually isn't
        !           623: desirable to set the environment variable before a top-level invocation
        !           624: of @code{make}, because it is usually better not to mess with a makefile
        !           625: from outside.  However, if you are running @code{make} without a specific
        !           626: makefile, a makefile in @code{MAKEFILES} can do useful things to help the
        !           627: built-in implicit rules work better, such as defining search paths.
        !           628: 
        !           629: Some users are tempted to set @code{MAKEFILES} in the environment
        !           630: automatically on login, and program makefiles to expect this to be done.
        !           631: This is a very bad idea, because such makefiles will fail to work if run by
        !           632: anyone else.  It is much better to write explicit @code{include} directives
        !           633: in the makefiles.
        !           634: 
        !           635: @node Include,, MAKEFILES Variable, Makefiles
        !           636: @section Including Other Makefiles
        !           637: 
        !           638: @findex include
        !           639: The @code{include} directive tells @code{make} to suspend reading the
        !           640: current makefile and read another makefile before continuing.  The
        !           641: directive is a line in the makefile that looks like this:
        !           642: 
        !           643: @example
        !           644: include @var{filename}
        !           645: @end example
        !           646: 
        !           647: Extra spaces are allowed and ignored at the beginning of the line, but a
        !           648: tab is not allowed.  (If the line begins with a tab, it will be considered
        !           649: a command line.)  Whitespace is required between @code{include} and
        !           650: @var{filename}; extra whitespace is ignored there and at the end of the
        !           651: directive.  A comment starting with @samp{#} is allowed at the end of the
        !           652: line.
        !           653: 
        !           654: Reading of the containing makefile is temporarily suspended while the file
        !           655: @var{filename} is read as a makefile.  When that is finished, @code{make}
        !           656: goes on with reading the makefile in which the directive appears.
        !           657: 
        !           658: The default goal target is never taken from an included makefile
        !           659: (@pxref{Goals}).
        !           660: 
        !           661: One occasion for using @code{include} directives is when several programs,
        !           662: handled by individual makefiles in various directories, need to use a
        !           663: common set of variable definitions (@pxref{Setting}) or pattern rules
        !           664: (@pxref{Pattern Rules}).
        !           665: 
        !           666: Another such occasion is when you want to automatically generate
        !           667: dependencies from source files; the dependencies can be put in a file that
        !           668: is included by the main makefile.  This practice is generally cleaner than
        !           669: that of somehow appending the dependencies to the end of the main makefile
        !           670: as has been traditionally done with other versions of @code{make}.
        !           671: 
        !           672: If the specified name does not start with a slash, and the file is not
        !           673: found in the current directory, several other directories are searched.
        !           674: First, any directories you have specified with the @samp{-I} option are
        !           675: searched (@pxref{Options}).  Then the following directories (if they
        !           676: exist) are searched, in this order: @file{/usr/gnu/include},
        !           677: @file{/usr/local/include}, @file{/usr/include}.
        !           678: If an included makefile cannot be found in any of these directories, a
        !           679: warning message is generated, but it is not a fatal error.@refill
        !           680: 
        !           681: @node Rules, Commands, Makefiles, Top
        !           682: @chapter Writing Rules
        !           683: 
        !           684: @cindex rule
        !           685: @cindex target
        !           686: @cindex dependency
        !           687: A @dfn{rule} appears in the makefile and says when and how to remake
        !           688: certain files, called the rule's @dfn{targets} (usually only one per rule).
        !           689: It lists the other files that are the @dfn{dependencies} of the target, and
        !           690: @dfn{commands} to use to create or update the target.
        !           691: 
        !           692: The order of rules is not significant, except for determining the
        !           693: @dfn{default goal}: the target for @code{make} to consider, if you do not
        !           694: otherwise specify one.  The default goal comes from the first rule (not
        !           695: counting included makefiles) whose target does not start with a period.
        !           696: Therefore, the first rule is normally one for compiling the entire program
        !           697: or all the programs described by the makefile.  @xref{Goals}.
        !           698: 
        !           699: @menu
        !           700: * Rule Example::        An explained example of a rule.
        !           701: * Rule Syntax::                General syntax of rules, with explanation.
        !           702: 
        !           703: * Wildcards::          Using wildcard characters like `*' in file names.
        !           704: * Directory Search::    Searching other directories for source files.
        !           705: 
        !           706: * Phony Targets::       Using a target that isn't a real file's name.
        !           707: * Special Targets::     Targets with special built-in meanings.
        !           708: * Empty Targets::       Real files that are empty--only the date matters.
        !           709: * Multiple Targets::    When it is useful to have several targets in a rule.
        !           710: * Static Pattern::     Static pattern rules apply to multiple targets
        !           711:                         and can vary the dependencies according to the
        !           712:                         target name.
        !           713: * Multiple Rules::      Using several rules with the same target.
        !           714: * Double-Colon::        Special kind of rule allowing
        !           715:                           several independent rules for one target.
        !           716: * Commands::            Special features and details of how commands
        !           717:                          in a rule are executed.
        !           718: @end menu
        !           719: 
        !           720: @ifinfo
        !           721: @node Rule Example, Rule Syntax, Rules, Rules
        !           722: @isubsection Rule Example
        !           723: 
        !           724: Here is an example of a rule:
        !           725: 
        !           726: @example
        !           727: foo.o : foo.c defs.h       # module for twiddling the frobs
        !           728:         cc -c -g foo.c
        !           729: @end example
        !           730: 
        !           731: Its target is @file{foo.o} and its dependencies are @file{foo.c} and
        !           732: @file{defs.h}.  It has one command, which is @samp{cc -c -g foo.c}.
        !           733: The command line starts with a tab to identify it as a command.
        !           734: 
        !           735: This rule says two things:
        !           736: 
        !           737: @itemize @bullet
        !           738: @item
        !           739: How to decide whether @file{foo.o} is out of date: it is out of date
        !           740: if it does not exist, or if either @file{foo.c} or @file{defs.h} is
        !           741: more recent than it.
        !           742: 
        !           743: @item
        !           744: How to update the file @file{foo.o}: by running @code{cc} as stated.
        !           745: The command does not explicitly mention @file{defs.h}, but we presume
        !           746: that @file{foo.c} includes it, and that that is why @file{defs.h} was
        !           747: added to the dependencies.
        !           748: @end itemize
        !           749: @end ifinfo
        !           750: 
        !           751: @node Rule Syntax, Wildcards, Rule Example, Rules
        !           752: @section Rule Syntax
        !           753: 
        !           754: In general, a rule looks like this:
        !           755: 
        !           756: @example
        !           757: @var{targets} : @var{dependencies}
        !           758:         @var{command}
        !           759:         @var{command}
        !           760:         ...
        !           761: @end example
        !           762: 
        !           763: @noindent
        !           764: or like this:
        !           765: 
        !           766: @example
        !           767: @var{targets} : @var{dependencies} ; @var{command}
        !           768:         @var{command}
        !           769:         @var{command}
        !           770:         ...
        !           771: @end example
        !           772: 
        !           773: The @var{targets} are file names, separated by spaces.  Wild card
        !           774: characters may be used (@pxref{Wildcards}) and a name of the form
        !           775: @file{@var{a}(@var{m})} represents member @var{m} in archive file @var{a}
        !           776: (@pxref{Archive Members}).  Usually there is only one target per rule, but
        !           777: occasionally there is a reason to have more (@pxref{Multiple Targets}).
        !           778: 
        !           779: The @var{command} lines start with a tab character.  The first command may
        !           780: appear on the line after the dependencies, with a tab character, or may
        !           781: appear on the same line, with a semicolon.  Either way, the effect is the
        !           782: same.  @xref{Commands}.
        !           783: 
        !           784: Because dollar signs are used to start variable references, if you really
        !           785: want a dollar sign in the rule you must write two of them (@samp{$$}).
        !           786: @xref{Variables}.  A long line may be split by inserting a backslash
        !           787: followed by a newline, but this is not required, as there is no limit on
        !           788: the length of a line.
        !           789: 
        !           790: A rule tells @code{make} two things: when the targets are out of date,
        !           791: and how to update them when necessary.
        !           792: 
        !           793: The criterion for being out of date is specified in terms of the
        !           794: @var{dependencies}, which consist of file names separated by spaces.
        !           795: (Wildcards and archive members are allowed here too.)  A target is out of
        !           796: date if it does not exist or if it is older than any of the dependencies
        !           797: (by comparison of last-modification times).  The idea is that the contents
        !           798: of the target file are computed based on information in the dependencies,
        !           799: so if any of the dependencies changes, the contents of the existing target
        !           800: file are no longer necessarily valid.
        !           801: 
        !           802: How to update is specified by @var{commands}.  These are lines to be
        !           803: executed by the shell (normally @samp{sh}), but with some extra features
        !           804: (@pxref{Commands}).
        !           805: 
        !           806: @node Wildcards, Directory Search, Rule Syntax, Rules
        !           807: @section Using Wildcards Characters in File Names
        !           808: @cindex wildcard
        !           809: @cindex file name
        !           810: 
        !           811: A single file name can specify many files using @dfn{wildcard characters}.
        !           812: The wildcard characters in @code{make} are @samp{*}, @samp{?} and
        !           813: @samp{[@dots{}]}, the same as in the Bourne shell.  For example, @file{*.c}
        !           814: specifies a list of all the files (in the working directory) whose names
        !           815: end in @samp{.c}.@refill
        !           816: 
        !           817: Wildcard expansion happens automatically in targets, in dependencies, and
        !           818: in commands.  In other contexts, wildcard expansion happens only if you
        !           819: request it explicitly with the @code{wildcard} function.
        !           820: 
        !           821: The special significance of a wildcard character can be turned off by
        !           822: preceding it with a backslash.  Thus, @file{foo\*bar} would refer to a
        !           823: specific file whose name consists of @samp{foo}, an asterisk, and
        !           824: @samp{bar}.@refill
        !           825: 
        !           826: @menu
        !           827: * Examples: Wildcard Examples.    Some simple examples.
        !           828: * Pitfall: Wildcard Pitfall.      @code{*.o} won't do what you want!
        !           829: * Function: Wildcard Function.
        !           830:        How to do wildcard expansion when defining a variable
        !           831:        using the function @code{wildcard}.
        !           832: @end menu
        !           833: 
        !           834: @node Wildcard Examples, Wildcard Function, Wildcards, Wildcards
        !           835: @subsection Wildcard Examples
        !           836: 
        !           837: Wildcards can be used in the commands of a rule.  For example, here is a
        !           838: rule to delete all the object files:
        !           839: 
        !           840: @example
        !           841: clean:
        !           842:         rm -f *.o
        !           843: @end example
        !           844: 
        !           845: Wildcards are also useful in the dependencies of a rule.  With the
        !           846: following rule in the makefile, @samp{make print} will print all the
        !           847: @samp{.c} files that have changed since the last time you printed them:
        !           848: 
        !           849: @example
        !           850: print: *.c
        !           851:         lpr -p $?
        !           852:         touch print
        !           853: @end example
        !           854: 
        !           855: @noindent
        !           856: This rule uses @file{print} as an empty target file; @pxref{Empty Targets}.
        !           857: 
        !           858: Wildcard expansion does not happen when you define a variable.  Thus, if
        !           859: you write this:
        !           860: 
        !           861: @example
        !           862: objects=*.o
        !           863: @end example
        !           864: 
        !           865: @noindent
        !           866: then the value of the variable @code{objects} is the actual string
        !           867: @samp{*.o}.  However, if you use the value of @code{objects} in a target,
        !           868: dependency or command, wildcard expansion will take place at that time.
        !           869: 
        !           870: @node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards
        !           871: @subsection Pitfalls of Using Wildcards
        !           872: 
        !           873: Now here is an example of a naive way of using wildcard expansion, that
        !           874: does not do what you would intend.  Suppose you would like to say that the
        !           875: executable file @file{foo} is made from all the object files in the
        !           876: directory, and you write this:
        !           877: 
        !           878: @example
        !           879: objects=*.o
        !           880: 
        !           881: foo : $(objects)
        !           882:         cc -o foo $(CFLAGS) $(objects)
        !           883: @end example
        !           884: 
        !           885: @noindent
        !           886: The value of @code{objects} is the actual string @samp{*.o}.  Wildcard
        !           887: expansion happens in the rule for @file{foo}, so that each @emph{existing}
        !           888: @samp{.o} file becomes a dependency of @file{foo} and will be recompiled if
        !           889: necessary.
        !           890: 
        !           891: But what if you delete all the @samp{.o} files?  Then @samp{*.o} will
        !           892: expand into @emph{nothing}.  The target @file{foo} will have no
        !           893: dependencies and would be remade by linking no object files.  This is not
        !           894: what you want!
        !           895: 
        !           896: Actually you can use wildcard expansion for this purpose, but you need more
        !           897: sophisticated techniques, including the @code{wildcard} function and string
        !           898: substitution.
        !           899: @ifinfo
        !           900: @xref{Wildcard Function}.
        !           901: @end ifinfo
        !           902: @iftex
        !           903: These are described in the following section.
        !           904: @end iftex
        !           905: 
        !           906: @node Wildcard Function,, Wildcard Pitfall, Wildcards
        !           907: @subsection The Function @code{wildcard}
        !           908: @findex wildcard
        !           909: 
        !           910: Wildcard expansion happens automatically in rules.  But wildcard expansion
        !           911: does not normally take place when a variable is set, or inside the
        !           912: arguments of a function.  If you want to do wildcard expansion in such
        !           913: places, you need to use the @code{wildcard} function, like this:
        !           914: 
        !           915: @example
        !           916: $(wildcard @var{pattern})
        !           917: @end example
        !           918: 
        !           919: This string, used anywhere in a makefile, is replaced by a space-separated
        !           920: list of names of existing files that match the pattern @var{pattern}.
        !           921: 
        !           922: One use of the @code{wildcard} function is to get a list of all the C source
        !           923: files in a directory, like this:
        !           924: 
        !           925: @example
        !           926: $(wildcard *.c)
        !           927: @end example
        !           928: 
        !           929: We can change the list of C source files into a list of object files by
        !           930: substituting @samp{.o} for @samp{.c} in the result, like this:
        !           931: 
        !           932: @example
        !           933: $(subst .c,.o,$(wildcard *.c))
        !           934: @end example
        !           935: 
        !           936: Here we have used another function, @code{subst} (@pxref{Text Functions}).
        !           937: 
        !           938: Thus, a makefile to compile all C source files in the directory and then
        !           939: link them together could be written as follows:
        !           940: 
        !           941: @example
        !           942: objects:=$(subst .c,.o,$(wildcard *.c))
        !           943: 
        !           944: foo : $(objects)
        !           945:         cc -o foo $(LDFLAGS) $(objects)
        !           946: @end example
        !           947: 
        !           948: @noindent
        !           949: (This takes advantage of the implicit rule for compiling C programs, so
        !           950: there is no need to write explicit rules for compiling the files.)
        !           951: 
        !           952: @node Directory Search, Phony Targets, Wildcards, Rules
        !           953: @section Searching Directories for Dependencies
        !           954: @vindex VPATH
        !           955: @findex vpath
        !           956: @cindex vpath
        !           957: @cindex search path for dependencies
        !           958: @cindex directory search
        !           959: 
        !           960: For large systems, it is often desirable to put sources in a separate
        !           961: directory from the binaries.  The @dfn{directory search} features of
        !           962: @code{make} facilitate this by searching several directories automatically
        !           963: to find a dependency.  When you redistribute the files among directories,
        !           964: you do not need to change the individual rules, just the search paths.
        !           965: 
        !           966: @menu
        !           967: * General Search::    The @code{VPATH} variable specifies a search path
        !           968:                        that applies to every dependency.
        !           969: * Selective Search::  The @code{vpath} directive specifies a search path
        !           970:                        for a specified class of names.
        !           971: * Commands/Search::   How to write shell commands that work together
        !           972:                        with search paths.
        !           973: * Implicit/Search::   How search paths affect implicit rules.
        !           974: * Libraries/Search::  Directory search for link libraries.
        !           975: @end menu
        !           976: 
        !           977: @node General Search, Selective Search, Directory Search, Directory Search
        !           978: @subsection @code{VPATH}: Search Path for All Dependencies
        !           979: 
        !           980: The value of the variable @code{VPATH} is a list of directories which
        !           981: @code{make} should search (in the order specified) for dependency files.
        !           982: The directory names are separated by colons.  For example:
        !           983: 
        !           984: @example
        !           985: VPATH = src:../headers
        !           986: @end example
        !           987: 
        !           988: @noindent
        !           989: specifies a path containing two directories, @file{src} and @file{../headers}.
        !           990: 
        !           991: Whenever a file listed as a dependency does not exist in the current
        !           992: directory, the directories listed in @code{VPATH} are searched for a file
        !           993: with that name.  If a file is found in one of them, that file becomes the
        !           994: dependency.  Rules may then specify the names of source files as if they
        !           995: all existed in the current directory.
        !           996: 
        !           997: Using the value of @code{VPATH} set in the previous example, a rule like this:
        !           998: 
        !           999: @example
        !          1000: foo.o : foo.c
        !          1001: @end example
        !          1002: 
        !          1003: @noindent
        !          1004: is interpreted as if it were written like this:
        !          1005: 
        !          1006: @example
        !          1007: foo.o : src/foo.c
        !          1008: @end example
        !          1009: 
        !          1010: @noindent
        !          1011: assuming the file @file{foo.c} does not exist in the current directory but
        !          1012: is found in the directory @file{src}.
        !          1013: 
        !          1014: @node Selective Search, Commands/Search, General Search, Directory Search
        !          1015: @subsection The @code{vpath} Directive
        !          1016: 
        !          1017: Similar to the @code{VPATH} variable but more selective is the @code{vpath}
        !          1018: directive, which allows you to specify a search path for a particular class
        !          1019: of filenames, those that match a particular pattern.  Thus you can supply
        !          1020: certain search directories for one class of filenames and other directories
        !          1021: (or none) for other filenames.
        !          1022: 
        !          1023: There are three forms of the @code{vpath} directive:
        !          1024: 
        !          1025: @table @code
        !          1026: @item vpath @var{pattern} @var{directories}
        !          1027: Specify the search path @var{directories} for filenames that match
        !          1028: @code{pattern}.  If another path was previously specified for the same
        !          1029: pattern, the new path replaces it.  Note that it does @emph{not} add
        !          1030: to the old path for this pattern.@refill
        !          1031: 
        !          1032: The search path, @var{directories}, is a colon-separated list of
        !          1033: directories to be searched, just like the search path used in the
        !          1034: @code{VPATH} variable.
        !          1035: 
        !          1036: @item vpath @var{pattern}
        !          1037: Clear out the search path associated with @var{pattern}.
        !          1038: 
        !          1039: @item vpath
        !          1040: Clear all search paths previously specified with @code{vpath} directives.
        !          1041: @end table
        !          1042: 
        !          1043: A @code{vpath} pattern is a string containing a @samp{%} character.  The
        !          1044: string must match the filename of a dependency that is being searched for,
        !          1045: the @samp{%} character matching any sequence of zero or more characters (as
        !          1046: in pattern rules; @pxref{Pattern Rules}).  (It is valid to omit the
        !          1047: @samp{%}, but then the pattern must match the dependency exactly, which may
        !          1048: not be very useful.)
        !          1049: 
        !          1050: When a dependency fails to exist in the current directory, if the
        !          1051: @var{pattern} in a @code{vpath} directive matches the name of the
        !          1052: dependency file, then the @var{directories} in that directive are searched
        !          1053: just like (and before) the directories in the @code{VPATH} variable.@refill
        !          1054: 
        !          1055: If several @code{vpath} patterns match the dependency file's name, then
        !          1056: @code{make} processes each matching @code{vpath} directive one by one,
        !          1057: searching all the directories mentioned in each directive.  The @code{vpath}
        !          1058: directives are processed in the order in which they appear in the makefiles.
        !          1059: 
        !          1060: @node Commands/Search, Implicit/Search, Selective Search, Directory Search
        !          1061: @subsection Writing Shell-Commands with Directory Search
        !          1062: 
        !          1063: When a dependency is found in another directory through directory search,
        !          1064: this cannot change the commands of the rule; they will execute as written.
        !          1065: Therefore, you must write the commands with care so that they will look for
        !          1066: the dependency in the directory where @code{make} finds it.
        !          1067: 
        !          1068: This is done with the @dfn{automatic variables} such as @samp{$^}
        !          1069: (@pxref{Automatic}).  For instance, the value of @samp{$^} is a list of all
        !          1070: the dependencies of the rule, including the names of the directories in
        !          1071: which they were found, and the value of @samp{$@@} is the target.  Thus:
        !          1072: 
        !          1073: @example
        !          1074: foo.o : foo.c
        !          1075:         cc -c $(CFLAGS) $^ -o $@@
        !          1076: @end example
        !          1077: 
        !          1078: @noindent
        !          1079: The variable @code{CFLAGS} exists so you can specify flags for C
        !          1080: compilation by implicit rule; we use it here for consistency so it will
        !          1081: affect all C compilations uniformly (@pxref{Implicit Variables}).
        !          1082: 
        !          1083: Often the dependencies include header files as well, which you don't want
        !          1084: to mention in the commands.  The function @code{firstword} can be used to
        !          1085: extract just the first dependency from the entire list, as shown here
        !          1086: (@pxref{Filename Functions}):
        !          1087: 
        !          1088: @example
        !          1089: VPATH = src:../headers
        !          1090: foo.o : foo.c defs.h hack.h
        !          1091:         cc -c $(CFLAGS) $(firstword $^) -o $@@
        !          1092: @end example
        !          1093: 
        !          1094: @noindent
        !          1095: Here the value of @samp{$^} would be something like @samp{src/foo.c
        !          1096: ../headers/defs.h hack.h}, from which @samp{$(firstword $^)} extracts just
        !          1097: @samp{src/foo.c}.@refill
        !          1098: 
        !          1099: @node Implicit/Search, Libraries/Search, Commands/Search, Directory Search
        !          1100: @subsection Directory Search and Implicit Rules
        !          1101: 
        !          1102: The search through the directories specified in @code{VPATH} or with
        !          1103: @code{vpath} happens also during consideration of implicit rules
        !          1104: (@pxref{Implicit}).
        !          1105: 
        !          1106: For example, when a file @file{foo.o} has no explicit rule, @code{make}
        !          1107: considers implicit rules, such as to compile @file{foo.c} if that file
        !          1108: exists.  If such a file is lacking in the current directory, the
        !          1109: appropriate directories are searched for it.  If @file{foo.c} exists (or is
        !          1110: mentioned in the makefile) in any of the directories, the implicit rule for
        !          1111: C compilation is applicable.
        !          1112: 
        !          1113: The commands of all the built-in implicit rules normally use automatic
        !          1114: variables as a matter of necessity; consequently they will use the file
        !          1115: names found by directory search with no extra effort.
        !          1116: 
        !          1117: @node Libraries/Search,, Implicit/Search, Directory Search
        !          1118: @subsection Directory Search for Link Libraries
        !          1119: 
        !          1120: Directory search applies in a special way to libraries used with the
        !          1121: linker.  This special feature comes into play when you write a dependency
        !          1122: whose name is of the form @samp{-l@var{name}}.  (You can tell something
        !          1123: funny is going on here because the dependency is normally the name of a
        !          1124: file, and the @emph{file name} of the library looks like
        !          1125: @file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill
        !          1126: 
        !          1127: When a dependency's name has the form @samp{-l@var{name}}, @code{make}
        !          1128: handles it specially by searching for the file @samp{lib@var{name}.a} in
        !          1129: the directories @samp{/lib} and @samp{/usr/lib}, and then using matching
        !          1130: @code{vpath} search paths and the @code{VPATH} search path.@refill
        !          1131: 
        !          1132: For example,
        !          1133: 
        !          1134: @example
        !          1135: foo : foo.c -lcurses
        !          1136:         cc $^ -o $@@
        !          1137: @end example
        !          1138: 
        !          1139: @noindent
        !          1140: would cause the command @samp{cc foo.c -lcurses -o foo} to be executed when
        !          1141: @file{foo} is older than @file{foo.c} or than @file{libcurses.a} (which has
        !          1142: probably been found by directory search in the file
        !          1143: @file{/usr/lib/libcurses.a}).@refill
        !          1144: 
        !          1145: As shown by the example above, the file name found by directory search is
        !          1146: used only for comparing the file time with the target file's time.  It
        !          1147: does not replace the file's name in later usage (such as in automatic
        !          1148: variables like @code{$^}); the name remains unchanged, still starting
        !          1149: with @samp{-l}.  This leads to the correct results because the linker
        !          1150: will repeat the appropriate search when it processes its arguments.@refill
        !          1151: 
        !          1152: @node Phony Targets, Empty Targets, Directory Search, Rules
        !          1153: @section Phony Targets
        !          1154: @cindex phony targets
        !          1155: 
        !          1156: A phony target is one that is not really the name of a file.
        !          1157: It is only a name for some commands to be executed when explicitly
        !          1158: requested.
        !          1159: 
        !          1160: If you write a rule whose commands will not create the target file, the
        !          1161: commands will be executed every time the target comes up for remaking.
        !          1162: Here is an example:
        !          1163: 
        !          1164: @example
        !          1165: clean:
        !          1166:         rm *.o temp
        !          1167: @end example
        !          1168: 
        !          1169: @noindent
        !          1170: Because the @code{rm} command does not create a file named @file{clean},
        !          1171: probably no such file will ever exist.  Therefore, the @code{rm} command
        !          1172: will be executed every time you say @samp{make clean}.
        !          1173: 
        !          1174: @findex .PHONY
        !          1175: The phony target will cease to work if anything ever does create a file
        !          1176: named @file{clean} in this directory.  Since there are no dependencies, the
        !          1177: @file{clean} would be considered up to date and its commands would not be
        !          1178: executed.  To avoid this problem, you can explicitly declare the target to
        !          1179: be phony, using the special target @code{.PHONY} (@pxref{Special Targets})
        !          1180: as follows:
        !          1181: 
        !          1182: @example
        !          1183: .PHONY : clean
        !          1184: @end example
        !          1185: 
        !          1186: @noindent
        !          1187: Once this is done, @code{make} will run the commands regardless of whether
        !          1188: there is a file named @file{clean}.
        !          1189: 
        !          1190: A phony target should not be a dependency of a real target file; strange
        !          1191: things can result from that.  As long as you don't do that, the phony
        !          1192: target commands will be executed only when the phony target is a goal
        !          1193: (@pxref{Goals}).
        !          1194: 
        !          1195: Phony targets can have dependencies.  When one directory contains multiple
        !          1196: programs, it is most convenient to describe all of the programs in one
        !          1197: makefile @file{./Makefile}.  Since the target remade by default will be the
        !          1198: first one in the makefile, it is common to make this a phony target named
        !          1199: @samp{all} and give it, as dependencies, all the individual programs.  For
        !          1200: example:
        !          1201: 
        !          1202: @example
        !          1203: all : prog1 prog2 prog3
        !          1204: .PHONY : all
        !          1205: 
        !          1206: prog1 : prog1.o utils.o
        !          1207:         cc -o prog1 prog1.o utils.o
        !          1208: 
        !          1209: prog2 : prog2.o
        !          1210:         cc -o prog2 prog2.o
        !          1211: 
        !          1212: prog3 : prog3.o sort.o utils.o
        !          1213:         cc -o prog3 prog3.o sort.o utils.o
        !          1214: @end example
        !          1215: 
        !          1216: @noindent
        !          1217: Now you can say just @samp{make} to remake all three programs, or specify
        !          1218: as arguments the ones to remake (as in @samp{make prog1 prog3}).
        !          1219: 
        !          1220: When one phony target is a dependency of another, it serves as a subroutine
        !          1221: of the other.  For example, here @samp{make cleanall} will delete the
        !          1222: object files, the difference files, and the file @file{program}:
        !          1223: 
        !          1224: @example
        !          1225: cleanall : cleanobj cleandiff
        !          1226:         rm program
        !          1227: 
        !          1228: cleanobj :
        !          1229:         rm *.o
        !          1230: 
        !          1231: cleandiff :
        !          1232:         rm *.diff
        !          1233: @end example
        !          1234: 
        !          1235: @node Empty Targets, Special Targets, Phony Targets, Rules
        !          1236: @section Empty Target Files to Record Events
        !          1237: @cindex empty targets
        !          1238: 
        !          1239: The @dfn{empty target} is a variant of the phony target; it is used to hold
        !          1240: commands for an action that you request explicitly from time to time.
        !          1241: Unlike a phony target, this target file can really exist; but the file's
        !          1242: contents do not matter, and usually are empty.
        !          1243: 
        !          1244: The purpose of the empty target file is to record, with its
        !          1245: last-modification-time, when the rule's commands were last executed.  It
        !          1246: does so because one of the commands is a @code{touch} command to update the
        !          1247: target file.
        !          1248: 
        !          1249: The empty target file must have some dependencies.  When you ask to remake
        !          1250: the empty target, the commands are executed if any dependency is more
        !          1251: recent than the target; in other words, if a dependency has changed since
        !          1252: the last time you remade the target.  Here is an example:
        !          1253: 
        !          1254: @example
        !          1255: print: foo.c bar.c
        !          1256:         lpr -p $?
        !          1257:         touch print
        !          1258: @end example
        !          1259: 
        !          1260: @noindent
        !          1261: With this rule, @samp{make print} will execute the @code{lpr} command if
        !          1262: either source file has changed since the last @samp{make print}.  The
        !          1263: automatic variable @samp{$?} is used to print only those files that have
        !          1264: changed (@pxref{Automatic}).
        !          1265: 
        !          1266: @node Special Targets, Multiple Targets, Empty Targets, Rules
        !          1267: @section Special Built-in Target Names
        !          1268: @cindex special targets
        !          1269: 
        !          1270: Certain names have special meanings if they appear as targets.
        !          1271: 
        !          1272: @table @code
        !          1273: @item .PHONY
        !          1274: The dependencies of the special target @code{.PHONY} are considered to
        !          1275: be phony targets.  When it is time to consider such a target,
        !          1276: @code{make} will run its commands unconditionally, regardless of
        !          1277: whether a file with that name exists or what its last-modification
        !          1278: time is.  @xref{Phony Targets}.
        !          1279: 
        !          1280: @item .SUFFIXES
        !          1281: The dependencies of the special target @code{.SUFFIXES} are the list
        !          1282: of suffixes to be used in checking for suffix rules (@pxref{Suffix
        !          1283: Rules}).
        !          1284: 
        !          1285: @item .DEFAULT
        !          1286: The commands specified for @code{.DEFAULT} are used for any target for
        !          1287: which no other commands are known (either explicitly or through an
        !          1288: implicit rule).  If @code{.DEFAULT} commands are specified, every
        !          1289: nonexistent file mentioned as a dependency will have these commands
        !          1290: executed on its behalf.  @xref{Search Algorithm}.
        !          1291: 
        !          1292: @item .PRECIOUS
        !          1293: @cindex precious targets
        !          1294: The targets which @code{.PRECIOUS} depends on are given this special
        !          1295: treatment: if @code{make} is killed or interrupted during the
        !          1296: execution of their commands, the target is not deleted.
        !          1297: @xref{Interrupts}.
        !          1298: 
        !          1299: @item .IGNORE
        !          1300: Simply by being mentioned as a target, @code{.IGNORE} says to ignore
        !          1301: errors in execution of commands.  The dependencies and commands for
        !          1302: @code{.IGNORE} are not meaningful.
        !          1303: 
        !          1304: @samp{.IGNORE} exists for historical compatibility.  Since
        !          1305: @code{.IGNORE} affects every command in the makefile, it is not very
        !          1306: useful; we recommend you use the more selective ways to ignore errors
        !          1307: in specific commands (@pxref{Errors}).
        !          1308: 
        !          1309: @item .SILENT
        !          1310: Simply by being mentioned as a target, @code{.SILENT} says not to
        !          1311: print commands before executing them.  The dependencies and commands
        !          1312: for @code{.SILENT} are not meaningful.
        !          1313: 
        !          1314: @samp{.SILENT} exists for historical compatibility.  We recommend you
        !          1315: use the more selective ways to silence specific commands
        !          1316: (@pxref{Echoing}).
        !          1317: @end table
        !          1318: 
        !          1319: An entire class of special targets have names made of the concatenation of
        !          1320: two implicit rule suffixes (two members of the list of dependencies of
        !          1321: @code{.SUFFIXES}).  Such special targets are suffix rules, an obsolete way
        !          1322: of defining implicit rules (but a way still widely used).  In principle,
        !          1323: any target name could be special in this way if you break it in two and add
        !          1324: both pieces to the suffix list.  In practice, suffixes normally begin with
        !          1325: @samp{.}, so these special target names also begin with @samp{.}.
        !          1326: @xref{Suffix Rules}.
        !          1327: 
        !          1328: @node Multiple Targets, Multiple Rules, Special Targets, Rules
        !          1329: @section Multiple Targets in a Rule
        !          1330: 
        !          1331: A rule with multiple targets is equivalent to writing many rules, each with
        !          1332: one target, and all identical aside from that.  The same commands apply to
        !          1333: all the targets, but their effects may vary because you can substitute the
        !          1334: actual target name into the command using @samp{$@@}.  The rule contributes
        !          1335: the same dependencies to all the targets also.
        !          1336: 
        !          1337: This is useful in two cases.
        !          1338: 
        !          1339: @itemize @bullet
        !          1340: @item
        !          1341: You want just dependencies, no commands.  For example:
        !          1342: 
        !          1343: @example
        !          1344: kbd.o commands.o files.o: command.h
        !          1345: @end example
        !          1346: 
        !          1347: @noindent
        !          1348: gives an additional dependency to each of the three object files
        !          1349: mentioned.
        !          1350: 
        !          1351: @item
        !          1352: Similar commands work for all the targets.  The commands do not need
        !          1353: to be absolutely identical, since the automatic variable @samp{$@@}
        !          1354: can be used to substitute the particular target to be remade into the
        !          1355: commands (@pxref{Automatic}).  For example:
        !          1356: 
        !          1357: @group
        !          1358: @example
        !          1359: bigoutput littleoutput : text.g
        !          1360:         generate text.g -$(subst output,,$@@) > $@@
        !          1361: @end example
        !          1362: @end group
        !          1363: 
        !          1364: @noindent
        !          1365: is equivalent to
        !          1366: 
        !          1367: @example
        !          1368: bigoutput : text.g
        !          1369:         generate text.g -big > bigoutput
        !          1370: littleoutput : text.g
        !          1371:         generate text.g -little > littleoutput
        !          1372: @end example
        !          1373: 
        !          1374: @noindent
        !          1375: Here we assume the hypothetical program @code{generate} makes two
        !          1376: types of output, one if given @samp{-big} and one if given
        !          1377: @samp{-little}.@refill
        !          1378: @end itemize
        !          1379: 
        !          1380: @ifinfo
        !          1381: Suppose you would like to vary the dependencies according to the target,
        !          1382: much as the variable @samp{$@@} allows you to vary the commands.
        !          1383: You cannot do this with multiple targets in an ordinary rule, but you can
        !          1384: do it with a @dfn{static pattern rule}.  @xref{Static Pattern}.
        !          1385: @end ifinfo
        !          1386: 
        !          1387: @node Static Pattern, Multiple Rules, Multiple Targets, Rules
        !          1388: @section Static Pattern Rules
        !          1389: @cindex static pattern rules
        !          1390: @cindex varying dependencies
        !          1391: 
        !          1392: @dfn{Static pattern rules} are rules which specify multiple targets and
        !          1393: construct the dependency names for each target based on the target name.
        !          1394: They are more general than ordinary rules with multiple targets because the
        !          1395: targets don't have to have identical dependencies.  Their dependencies must
        !          1396: be @emph{analogous}, but not necessarily @emph{identical}.
        !          1397: 
        !          1398: @menu
        !          1399: * Usage: Static Usage. How to use static pattern rules.
        !          1400: * Static vs Implicit::  When are they better than implicit rules?
        !          1401: @end menu
        !          1402: 
        !          1403: @node Static Usage, Static vs Implicit, Static Pattern, Static Pattern
        !          1404: @subsection Syntax of Static Pattern Rules
        !          1405: 
        !          1406: Here is the syntax of a static pattern rule:
        !          1407: 
        !          1408: @example
        !          1409: @var{targets}: @var{target-pattern}: @var{dep-patterns} @dots{}
        !          1410:         @var{commands}
        !          1411:         @dots{}
        !          1412: @end example
        !          1413: 
        !          1414: @noindent
        !          1415: The @var{targets} gives the list of targets that the rule applies to.  The
        !          1416: targets can contain wildcard characters, just like the targets of ordinary
        !          1417: rules (@pxref{Wildcards}).
        !          1418: 
        !          1419: The @var{target-pattern} and @var{dep-patterns} say how to compute the
        !          1420: dependencies of each target.  Each target is matched against the
        !          1421: @var{target-pattern} to extract a part of the target name, called the
        !          1422: @dfn{stem}.  This stem is substituted into each of the @var{dep-patterns}
        !          1423: to make the dependency names (one from each @var{dep-pattern}).
        !          1424: 
        !          1425: Each pattern normally contains the character @samp{%} just once.  When the
        !          1426: @var{target-pattern} matches a target, the @samp{%} can match any part of
        !          1427: the target name; this part is called the @dfn{stem}.  The rest of the
        !          1428: pattern must match exactly.  For example, the target @file{foo.o} matches
        !          1429: the pattern @samp{%.o}, with @samp{foo} as the stem.  The targets
        !          1430: @file{foo.c} and @file{foo.out} don't match that pattern.@refill
        !          1431: 
        !          1432: The dependency names for each target are made by substituting the stem for
        !          1433: the @samp{%} in each dependency pattern.  For example, if one dependency
        !          1434: pattern is @file{%.c}, then substitution of the stem @samp{foo} gives the
        !          1435: dependency name @file{foo.c}.  It is fine to write a dependency pattern that
        !          1436: doesn't contain @samp{%}; then this dependency is the same for all targets.
        !          1437: 
        !          1438: Here is an example, which compiles each of @file{foo.o} and @file{bar.o}
        !          1439: from the corresponding @file{.c} file:
        !          1440: 
        !          1441: @example
        !          1442: objects := foo.o bar.o
        !          1443: 
        !          1444: $(objects): %.o: %.c
        !          1445:         $(CC) -c $(CFLAGS) $< -o $@@
        !          1446: @end example
        !          1447: 
        !          1448: Each target specified must match the target pattern; a warning is issued
        !          1449: for each that does not.  If you have a list of files, only some of which
        !          1450: will match the pattern, you can use the @code{filter} function to remove
        !          1451: nonmatching filenames (@pxref{Text Functions}):
        !          1452: 
        !          1453: @example
        !          1454: files := foo.elc bar.o
        !          1455: 
        !          1456: $(filter %.o,$(files)): %.o: %.c
        !          1457:         $(CC) -c $(CFLAGS) $< -o $@@
        !          1458: $(filter %.elc,$(files)): %.elc: %.el
        !          1459:         emacs -f batch-byte-compile $<
        !          1460: @end example
        !          1461: 
        !          1462: @noindent
        !          1463: Here the result of @samp{$(filter %.o,$(files))} is just @file{bar.o}, and
        !          1464: the first static pattern rule causes it to be made from @file{bar.c}.  The
        !          1465: result of @samp{$(filter %.elc,$(files))} is @file{foo.elc}, which is
        !          1466: made from @file{foo.el}.@refill
        !          1467: 
        !          1468: @node Static vs Implicit,, Static Usage, Static Pattern
        !          1469: @subsection Static Pattern Rules versus Implicit Rules
        !          1470: 
        !          1471: A static pattern rule has much in common with an implicit rule defined as a
        !          1472: pattern rule (@pxref{Pattern Rules}).  Both have a pattern for the target
        !          1473: and patterns for constructing the names of dependencies.  The difference is
        !          1474: in how @code{make} decides @emph{when} the rule applies.
        !          1475: 
        !          1476: An implicit rule @emph{can} apply to any target that matches its pattern,
        !          1477: but it @emph{does} apply only when the target has no commands otherwise
        !          1478: specified, and only when the dependencies can be found.  If more than one
        !          1479: implicit rule appears applicable, only one applies; the choice depends on
        !          1480: the order of rules.
        !          1481: 
        !          1482: By contrast, a static pattern rule applies to the precise list of targets
        !          1483: that you specify in the rule.  It cannot apply to any other target and it
        !          1484: invariably does apply to each of the targets specified.  If two conflicting
        !          1485: rules apply, and both have commands, that's an error.
        !          1486: 
        !          1487: The static pattern rule can be better than an implicit rule for these
        !          1488: reasons:
        !          1489: 
        !          1490: @itemize @bullet
        !          1491: @item
        !          1492: You may wish to override the usual implicit rule for a few
        !          1493: files whose names cannot be categorized syntactically but
        !          1494: can be given in an explicit list.
        !          1495: 
        !          1496: @item
        !          1497: If you cannot be sure of the precise contents of the directories
        !          1498: you are using, you may not be sure which other irrelevant files
        !          1499: might lead @code{make} to use the wrong implicit rule.  The choice
        !          1500: might depend on the order in which the implicit rule search is done.
        !          1501: With static pattern rules, there is no uncertainty: each rule applies
        !          1502: to precisely the targets specified.
        !          1503: @end itemize
        !          1504: 
        !          1505: @node Multiple Rules, Double-Colon, Static Pattern, Rules
        !          1506: @section Multiple Rules for One Target
        !          1507: 
        !          1508: One file can be the target of several rules if at most one rule has commands.
        !          1509: The other rules can only have dependencies.  All the dependencies mentioned
        !          1510: in all the rules are merged into one list of dependencies for the target.
        !          1511: If the target is older than any dependency from any rule, the commands are
        !          1512: executed.
        !          1513: 
        !          1514: An extra rule with just dependencies can be used to give a few extra
        !          1515: dependencies to many files at once.  For example, one usually has a
        !          1516: variable named @code{objects} containing a list of all the compiler output
        !          1517: files in the system being made.  An easy way to say that all of them must
        !          1518: be recompiled if @file{config.h} changes is to write
        !          1519: 
        !          1520: @example
        !          1521: objects = foo.o bar.o
        !          1522: foo.o : defs.h
        !          1523: bar.o : defs.h test.h
        !          1524: $(objects) : config.h
        !          1525: @end example
        !          1526: 
        !          1527: This could be inserted or taken out without changing the rules that really
        !          1528: say how to make the object files, making it a convenient form to use if
        !          1529: you wish to add the additional dependency intermittently.
        !          1530: 
        !          1531: Another wrinkle is that the additional dependencies could be specified with
        !          1532: a variable that you could set with a command argument to @code{make}
        !          1533: (@pxref{Overriding}).  For example,
        !          1534: 
        !          1535: @example
        !          1536: extradeps=
        !          1537: $(objects) : $(extradeps)
        !          1538: @end example
        !          1539: 
        !          1540: @noindent
        !          1541: means that the command @samp{make extradeps=foo.h} will consider
        !          1542: @file{foo.h} as a dependency of each object file, but plain @samp{make}
        !          1543: will not.
        !          1544: 
        !          1545: If none of the explicit rules for a target has commands, then @code{make}
        !          1546: searches for an applicable implicit rule to find some commands.
        !          1547: @xref{Implicit}.
        !          1548: 
        !          1549: @node Double-Colon,, Multiple Rules, Rules
        !          1550: @section Double-Colon Rules
        !          1551: @cindex double-colon rule
        !          1552: 
        !          1553: @dfn{Double-colon} rules are rules written with @samp{::} instead of
        !          1554: @samp{:} after the target names.  They are handled differently from
        !          1555: ordinary rules when the same target appears in more than one rule.
        !          1556: 
        !          1557: When a target appears in multiple rules, all the rules must be the same
        !          1558: type: all ordinary, or all double-colon.  If they are double-colon, each of
        !          1559: them is independent of the others.  Each double-colon rule's commands are
        !          1560: executed if the target is older than any dependencies of that rule.  This
        !          1561: can result in executing none, any or all of the double-colon rules.
        !          1562: 
        !          1563: The double-colon rules for a target are executed in the order they appear
        !          1564: in the makefile.  However, the cases where double-colon rules really make
        !          1565: sense are those where the order of executing the commands would not matter.
        !          1566: 
        !          1567: Each double-colon rule should specify commands; if it does not, an
        !          1568: implicit rule will be used if one applies.  @xref{Implicit}.
        !          1569: 
        !          1570: @node Commands, Variables, Rules, Top
        !          1571: @chapter Writing the Commands in Rules
        !          1572: @cindex commands
        !          1573: 
        !          1574: The commands of a rule consist of shell command lines to be executed one by
        !          1575: one.  Each command line must start with a tab, except that the first
        !          1576: command line may be attached to the target-and-dependencies line with a
        !          1577: semicolon in between.  Blank lines and lines of just comments may appear
        !          1578: among the command lines; they are ignored.
        !          1579: 
        !          1580: Users use many different shell programs, but commands in makefiles are
        !          1581: always interpreted by @file{/bin/sh} unless the makefile specifies otherwise.
        !          1582: 
        !          1583: Whether comments can be written on command lines, and what syntax they use,
        !          1584: is under the control of the shell that is in use.  If it is @file{/bin/sh},
        !          1585: a @samp{#} at the start of a word starts a comment.
        !          1586: 
        !          1587: @menu
        !          1588: * Echoing::       Normally commands are echoed before execution,
        !          1589:                     but you can control this in several ways.
        !          1590: * Execution::     How commands are executed.
        !          1591: * Errors::       What happens after an error in command execution.
        !          1592:                   How to ignore errors in certain commands.
        !          1593: * Interrupts::   If a command is interrupted or killed,
        !          1594:                   the target may be deleted.
        !          1595: * Recursion::    Invoking @code{make} from commands in makefiles.
        !          1596: * Sequences::     Defining canned sequences of commands.
        !          1597: @end menu
        !          1598: 
        !          1599: @node Echoing, Execution, Commands, Commands
        !          1600: @section Command Echoing
        !          1601: 
        !          1602: @cindex echoing (of commands)
        !          1603: @cindex silent operation
        !          1604: @cindex @@ (in commands)
        !          1605: @cindex -n
        !          1606: Normally @code{make} prints each command line before it is executed.
        !          1607: We call this @dfn{echoing} because it gives the appearance that you
        !          1608: are typing the commands yourself.
        !          1609: 
        !          1610: When a line starts with @samp{@@}, it is normally not echoed.  The
        !          1611: @samp{@@} is discarded before the command is passed to the shell.
        !          1612: Typically you would use this for a command whose only effect is to
        !          1613: print something, such as an @code{echo} command.
        !          1614: 
        !          1615: When @code{make} is given the flag @samp{-n}, echoing is all that happens,
        !          1616: no execution.  @xref{Options}.  In this case and only this case, even the
        !          1617: commands starting with @samp{@@} are printed.  This flag is useful for
        !          1618: finding out which commands @code{make} thinks are necessary without
        !          1619: actually doing them.
        !          1620: 
        !          1621: @cindex -s
        !          1622: @findex .SILENT
        !          1623: The @samp{-s} flag to @code{make} prevents all echoing, as if all commands
        !          1624: started with @samp{@@}.  A rule in the makefile for the special target
        !          1625: @code{.SILENT} has the same effect (@pxref{Special Targets}).
        !          1626: @code{.SILENT} is essentially obsolete since @samp{@@} is more general.@refill
        !          1627: 
        !          1628: @node Execution, Errors, Echoing, Commands
        !          1629: @section Command Execution
        !          1630: @cindex execution
        !          1631: @cindex shell
        !          1632: 
        !          1633: When it is time to execute commands to update a target, they are executed
        !          1634: one at a time by making a new subshell for each line.  (In practice,
        !          1635: @code{make} may take shortcuts that do not affect the results.)
        !          1636: 
        !          1637: This implies that shell commands such as @code{cd} that set variables local
        !          1638: to each process will not affect the following command lines.  If you want
        !          1639: to use @code{cd} to affect the next command, put the two on a single line
        !          1640: with a semicolon between them.  Then @code{make} will consider them a
        !          1641: single command and pass them, together, to a shell which will execute them
        !          1642: in sequence.  For example:
        !          1643: 
        !          1644: @example
        !          1645: foo : bar/lose
        !          1646:         cd bar; gobble lose > ../foo
        !          1647: @end example
        !          1648: 
        !          1649: If you would like to split a single shell command into multiple lines of
        !          1650: text, you must use a backslash at the end of all but the last subline.
        !          1651: Such a sequence of lines is combined into a single line, by deleting the
        !          1652: backslash-newline sequences, before passing it to the shell.  Thus, the
        !          1653: following is equivalent to the preceding example:
        !          1654: 
        !          1655: @group
        !          1656: @example
        !          1657: foo : bar/lose
        !          1658:         cd bar;  \
        !          1659:         gobble lose > ../foo
        !          1660: @end example
        !          1661: @end group
        !          1662: 
        !          1663: @vindex SHELL
        !          1664: The program used as the shell is taken from the variable @code{SHELL}.
        !          1665: By default, the program @file{/bin/sh} is used.
        !          1666: 
        !          1667: Unlike most variables, the variable @code{SHELL} will not be set from the
        !          1668: environment, except in a recursive @code{make}.  This is because the
        !          1669: environment variable @code{SHELL} is used to specify your personal choice
        !          1670: of shell program for interactive use.  It would be very bad for personal
        !          1671: choices like this to affect the functioning of makefiles.
        !          1672: @xref{Environment}.
        !          1673: 
        !          1674: @node Errors, Interrupts, Execution, Commands
        !          1675: @section Errors in Commands
        !          1676: 
        !          1677: @cindex error (in commands)
        !          1678: After each shell command returns, @code{make} looks at its exit status.
        !          1679: If the command completed successfully, the next command line is executed in
        !          1680: a new shell, or after the last command line is executed, the rule is finished.
        !          1681: 
        !          1682: If there is an error (the exit status is nonzero), @code{make} gives up on
        !          1683: the current rule, and perhaps on all rules.
        !          1684: 
        !          1685: Sometimes it does not matter whether a command fails.  For example, you
        !          1686: may use the @code{mkdir} command to insure that a directory exists.  If
        !          1687: the directory already exists, @code{mkdir} will report an error, but you
        !          1688: probably want @code{make} to continue regardless.
        !          1689: 
        !          1690: @cindex - (in commands)
        !          1691: To ignore errors in a command line, write a @samp{-} at the beginning of
        !          1692: the line's text (after the initial tab).  The @samp{-} is discarded before
        !          1693: the command is passed to the shell for execution.
        !          1694: 
        !          1695: @cindex -i
        !          1696: @findex .IGNORE
        !          1697: When @code{make} is run with the @samp{-i} flag, errors are ignored in
        !          1698: all commands of all rules.  A rule in the makefile for the special target
        !          1699: @code{.IGNORE} has the same effect.  These ways of ignoring errors are
        !          1700: obsolete because @samp{-} is more general.
        !          1701: 
        !          1702: When errors are to be ignored, because of either a @samp{-} or the
        !          1703: @samp{-i} flag, @code{make} treats an error return just like success,
        !          1704: except that it prints out a message telling you the status code the
        !          1705: command exited with and saying that the error has been ignored.
        !          1706: 
        !          1707: @cindex -k
        !          1708: When an error happens that @code{make} has not been told to ignore,
        !          1709: it implies that the current target cannot be correctly remade, and neither
        !          1710: can any other that depends on it either directly or indirectly.  No further
        !          1711: commands will be executed for these targets, since their preconditions
        !          1712: have not been achieved.
        !          1713: 
        !          1714: Normally @code{make} gives up immediately in this circumstance, returning a
        !          1715: nonzero status.  However, if the @samp{-k} flag is specified, @code{make}
        !          1716: continues to consider the other dependencies of the pending targets,
        !          1717: remaking them if necessary, before it gives up and returns nonzero status.
        !          1718: For example, after an error in compiling one object file, @samp{make -k}
        !          1719: will continue compiling other object files even though it already knows
        !          1720: that linking them will be impossible.  @xref{Options}.
        !          1721: 
        !          1722: The usual behavior assumes that your purpose is to get the specified
        !          1723: targets up to date; once @code{make} learns that this is impossible, it
        !          1724: might as well report the failure immediately.  The @samp{-k} option says
        !          1725: that the real purpose is to test as much as possible of the changes made in
        !          1726: the program, perhaps to find several independent problems so that you can
        !          1727: correct them all before the next attempt to compile.  This is why Emacs's
        !          1728: @code{compile} command passes the @samp{-k} flag by default.
        !          1729: 
        !          1730: @node Interrupts, Recursion, Errors, Commands
        !          1731: @section Interrupting or Killing @code{make}
        !          1732: @cindex interrupt
        !          1733: @cindex signal
        !          1734: @cindex deletion of target files
        !          1735: 
        !          1736: If @code{make} gets a fatal signal while a command is executing, it may
        !          1737: delete the target file that the command was supposed to update.  This is
        !          1738: done if the target file's last-modification time has changed since
        !          1739: @code{make} first checked it.
        !          1740: 
        !          1741: The purpose of deleting the target is to make sure that it is remade from
        !          1742: scratch when @code{make} is next run.  Otherwise, a partially written file
        !          1743: could appear to be valid, since it is more recent than the dependencies.
        !          1744: 
        !          1745: @findex .PRECIOUS
        !          1746: You can prevent the deletion of a target file in this way by making the
        !          1747: special target @code{.PRECIOUS} depend on it.  Before remaking a target,
        !          1748: @code{make} checks to see whether it appears on the dependencies of
        !          1749: @code{.PRECIOUS}, and thereby decides whether the target should be deleted
        !          1750: if a signal happens.  Some reasons why you might do this are that the
        !          1751: target is updated in some atomic fashion or exists only to record a
        !          1752: modification-time (its contents do not matter) or will cause trouble if it
        !          1753: ever fails to exist.
        !          1754: 
        !          1755: @node Recursion, Sequences, Interrupts, Commands
        !          1756: @section Recursive Use of @code{make}
        !          1757: @cindex recursion
        !          1758: 
        !          1759: Recursive use of @code{make} means using @code{make} as a command in a
        !          1760: makefile.  This technique is useful when you want separate makefiles for
        !          1761: various subsystems that compose a larger system.  For example, suppose you
        !          1762: have a subdirectory @file{subdir} which has its own makefile, and you would
        !          1763: like the containing directory's makefile to run @code{make} on the
        !          1764: subdirectory.  You can do it by writing this:
        !          1765: 
        !          1766: @example
        !          1767: subsystem:
        !          1768:         cd subdir; $(MAKE)
        !          1769: @end example
        !          1770: 
        !          1771: @noindent
        !          1772: or, equivalently, this (@pxref{Options}):
        !          1773: 
        !          1774: @example
        !          1775: subsystem:
        !          1776:         $(MAKE) -c subdir
        !          1777: @end example
        !          1778: 
        !          1779: You can write recursive @code{make} commands just by copying this example,
        !          1780: but there are many things to know about how they work and why, and about
        !          1781: how the sub-@code{make} relates to the top-level @code{make}.
        !          1782: 
        !          1783: @menu
        !          1784: * MAKE Variable::        Special effects of using @samp{$(MAKE)}.
        !          1785: * Variables/Recursion::  How variables are communicated to a sub-@code{make}.
        !          1786: * Options/Recursion::    How options are communicated to a sub-@code{make}.
        !          1787: * -w Option::            The @samp{-w} option facilitates debugging
        !          1788:                            makefiles with recursive @code{make} commands.
        !          1789: @end menu
        !          1790: 
        !          1791: @node MAKE Variable, Variables/Recursion, Recursion, Recursion
        !          1792: @subsection How the @code{MAKE} Variable Works
        !          1793: @vindex MAKE
        !          1794: 
        !          1795: Recursive @code{make} commands should always use the variable @code{MAKE},
        !          1796: not the explicit command name @samp{make}, as shown here:
        !          1797: 
        !          1798: @example
        !          1799: subsystem:
        !          1800:         cd subdir; $(MAKE)
        !          1801: @end example
        !          1802: 
        !          1803: The value of this variable is the file name with which @code{make} was
        !          1804: invoked.  If this file name was @file{/bin/make}, then the command executed
        !          1805: is @samp{cd subdir; /bin/make}.  If you use a special version of
        !          1806: @code{make} to run the top-level makefile, the same special version will be
        !          1807: executed for recursive invocations.
        !          1808: 
        !          1809: Also, any arguments that define variable values are added to @code{MAKE},
        !          1810: so the sub-@code{make} gets them too.  Thus, if you do @samp{make
        !          1811: CFLAGS=-O}, so that all C compilations will be optimized, the
        !          1812: sub-@code{make} is run with @samp{cd subdir; /bin/make CFLAGS=-O}.@refill
        !          1813: 
        !          1814: As a special feature, using the variable @code{MAKE} in the commands of a
        !          1815: rule alters the effects of the @samp{-t}, @samp{-n} or @samp{-q} option.
        !          1816: (@xref{Instead of Execution}.)@refill
        !          1817: 
        !          1818: Consider the command @samp{make -t} in the above example.  Following the
        !          1819: usual definition of @samp{-t}, this would create a file named
        !          1820: @file{subsystem} and do nothing else.  What you really want it to do is run
        !          1821: @samp{cd subdir; make -t}; but that would require executing the command,
        !          1822: and @samp{-t} says not to execute commands.@refill
        !          1823: 
        !          1824: The special feature makes this do what you want: whenever a rule's commands
        !          1825: use the variable @code{MAKE}, the flags @samp{-t}, @samp{-n} or @samp{-q}
        !          1826: do not apply to that rule.  The commands of that rule are executed normally
        !          1827: despite the presence of a flag that causes most commands not to be run.
        !          1828: The usual @code{MAKEFLAGS} mechanism passes the flags to the
        !          1829: sub-@code{make} (@pxref{Options/Recursion}), so your request to touch the
        !          1830: files, or print the commands, is propagated to the subsystem.@refill
        !          1831: 
        !          1832: @node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion
        !          1833: @subsection Communicating Variables to a Sub-@code{make}
        !          1834: @cindex environment and recursion
        !          1835: 
        !          1836: Most variable values of the top-level @code{make} are passed to the
        !          1837: sub-@code{make} through the environment.  These variables are defined in
        !          1838: the sub-@code{make} as defaults, but do not override what is specified in
        !          1839: the sub-@code{make}'s makefile.  (Variables are passed down if their names
        !          1840: consist of letters, numbers and underscores.)
        !          1841: 
        !          1842: The way this works is that @code{make} adds each variable and its value to
        !          1843: the environment for running each command.  (Variables whose names start
        !          1844: with non-alphanumeric characters are left out.)  The sub-@code{make}, in
        !          1845: turn, uses the environment to initialize its table of variable values.
        !          1846: @xref{Environment}.
        !          1847: 
        !          1848: @vindex MAKELEVEL
        !          1849: As a special feature, the variable @code{MAKELEVEL} is changed when it is
        !          1850: passed down from level to level.  This variable's value is a string which
        !          1851: is the depth of the level as a decimal number.  The value is @samp{0} for
        !          1852: the top-level @code{make}; @samp{1} for a sub-@code{make}, @samp{2} for a
        !          1853: sub-sub-@code{make}, and so on.  The incrementation happens when
        !          1854: @code{make} sets up the environment for a command.@refill
        !          1855: 
        !          1856: The main use of @code{MAKELEVEL} is to test it in a conditional directive
        !          1857: (@pxref{Conditionals}); this way you can write a makefile that behaves one
        !          1858: way if run recursively and another way if run directly by you.
        !          1859: 
        !          1860: @vindex MAKEFILES
        !          1861: You can use the variable @code{MAKEFILES} to cause all sub-@code{make}
        !          1862: commands to use additional makefiles.  The value of @code{MAKEFILES} is a
        !          1863: whitespace-separated list of filenames.  This variable, if defined in the
        !          1864: outer-level makefile, is passed down through the environment as usual; then
        !          1865: it serves as a list of extra makefiles for the sub-@code{make} to read
        !          1866: before the usual or specified ones.  @xref{MAKEFILES Variable}.
        !          1867: 
        !          1868: @node Options/Recursion, -w Option, Variables/Recursion, Recursion
        !          1869: @subsection Communicating Options to a Sub-@code{make}
        !          1870: @cindex options and recursion
        !          1871: 
        !          1872: @vindex MAKEFLAGS
        !          1873: Flags such as @samp{-s} and @samp{-k} are passed automatically to the
        !          1874: sub-@code{make} through the variable @code{MAKEFLAGS}.  This variable is
        !          1875: set up automatically by @code{make} to contain the flag letters that
        !          1876: @code{make} received.  Thus, if you do @samp{make -ks} then
        !          1877: @code{MAKEFLAGS} gets the value @samp{ks}.@refill
        !          1878: 
        !          1879: As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS}
        !          1880: in its environment.  In response, it takes the flags from that value and
        !          1881: processes them as if they had been given as arguments.  @xref{Options}.
        !          1882: 
        !          1883: The options @samp{-c}, @samp{-d}, @samp{-f}, @samp{-I}, @samp{-o}, and
        !          1884: @samp{-p} are not put into @code{MAKEFLAGS}; these options are not passed
        !          1885: down.@refill
        !          1886: 
        !          1887: If you don't want to pass the other flags down, you must change the
        !          1888: value of @code{MAKEFLAGS}, like this:
        !          1889: 
        !          1890: @example
        !          1891: subsystem:
        !          1892:         cd subdir; $(MAKE) MAKEFLAGS=
        !          1893: @end example
        !          1894: 
        !          1895: @vindex MFLAGS
        !          1896: A similar variable @code{MFLAGS} exists also, for historical compatibility.
        !          1897: It has the same value as @code{MAKEFLAGS} except that a hyphen is added at
        !          1898: the beginning if it is not empty.  @code{MFLAGS} was traditionally used
        !          1899: explicitly in the recursive @code{make} command, like this:
        !          1900: 
        !          1901: @example
        !          1902: subsystem:
        !          1903:         cd subdir; $(MAKE) $(MFLAGS)
        !          1904: @end example
        !          1905: 
        !          1906: @noindent
        !          1907: but now @code{MAKEFLAGS} makes this usage redundant.
        !          1908: 
        !          1909: @node -w Option,, Options/Recursion, Recursion
        !          1910: @subsection The @samp{-w} Option
        !          1911: 
        !          1912: If you are running @code{make} over a large directory tree, the @samp{-w}
        !          1913: option can make the output a lot easier to understand by showing each
        !          1914: directory as it is entered and exited.  For example, if @samp{make -w} is
        !          1915: run in the directory @file{/u/gnu/make}, @code{make} will print a line of
        !          1916: the form:@refill
        !          1917: 
        !          1918: @example
        !          1919: make: Entering directory `/u/gnu/make'.
        !          1920: @end example
        !          1921: 
        !          1922: @noindent
        !          1923: before doing anything else, and a line of the form:
        !          1924: 
        !          1925: @example
        !          1926: make: Leaving directory `/u/gnu/make'.
        !          1927: @end example
        !          1928: 
        !          1929: @noindent
        !          1930: when processing is completed.
        !          1931: 
        !          1932: @node Sequences,, Recursion, Commands
        !          1933: @section Defining Canned Command Sequences
        !          1934: @cindex sequences of commands
        !          1935: 
        !          1936: When the same sequence of commands is useful in making various targets, you
        !          1937: can define it as a canned sequence with the @code{define} directive, and
        !          1938: refer to the canned sequence from the rules for those targets.  The canned
        !          1939: sequence is actually a variable, so the name must not conflict with other
        !          1940: variable names.
        !          1941: 
        !          1942: Here is an example of defining a canned sequence of commands:
        !          1943: 
        !          1944: @example
        !          1945: define run-yacc
        !          1946: yacc $(firstword $^)
        !          1947: mv y.tab.c $@@
        !          1948: endef
        !          1949: @end example
        !          1950: 
        !          1951: @noindent
        !          1952: Here @code{run-yacc} is the name of the variable being defined;
        !          1953: @code{endef} marks the end of the definition; the lines in between are the
        !          1954: commands.  The @code{define} directive does not expand variable references
        !          1955: and function calls in the canned sequence; the @samp{$} characters,
        !          1956: parentheses, variable names, and so on, all become part of the value of the
        !          1957: variable you are defining.  @xref{Defining}, for a complete explanation of
        !          1958: @code{define}.
        !          1959: 
        !          1960: The first command in this example runs Yacc on the first dependency (of
        !          1961: whichever rule uses the canned sequence).  The output file from Yacc is
        !          1962: always named @file{y.tab.c}.  The second command moves the output to the
        !          1963: rule's target file name.
        !          1964: 
        !          1965: To use the canned sequence, substitute the variable into the commands of a
        !          1966: rule.  You can substitute it like any other variable (@pxref{Reference}).
        !          1967: Because variables defined by @code{define} are recursively expanded
        !          1968: variables, all the variable references you wrote inside the @code{define}
        !          1969: are expanded now.  For example:
        !          1970: 
        !          1971: @example
        !          1972: foo.c : foo.y
        !          1973:         $(run-yacc)
        !          1974: @end example
        !          1975: 
        !          1976: @noindent
        !          1977: @samp{foo.y} will substituted for the variable @samp{$^} when it occurs in
        !          1978: @code{run-yacc}'s value, and @samp{foo.c} for @samp{$@@}.@refill
        !          1979: 
        !          1980: This is a realistic example, but this particular one is not needed in
        !          1981: practice because @code{make} has an implicit rule to figure out these
        !          1982: commands based on the file names involved.  @xref{Implicit}.
        !          1983: 
        !          1984: @node Variables, Conditionals, Commands, Top
        !          1985: @chapter How to Use Variables
        !          1986: @cindex variable
        !          1987: @cindex value
        !          1988: @cindex recursive variable expansion
        !          1989: @cindex simple variable expansion
        !          1990: 
        !          1991: A @dfn{variable} is a name defined within @code{make} to represent a string
        !          1992: of text, called the variable's @dfn{value}.  These values can be
        !          1993: substituted by explicit request into targets, dependencies, commands and
        !          1994: other parts of the makefile.
        !          1995: 
        !          1996: Variables can represent lists of file names, options to pass to compilers,
        !          1997: programs to run, directories to look in for source files, directories to
        !          1998: write output in, or anything else you can imagine.
        !          1999: 
        !          2000: A variable name may be any sequence characters not containing @samp{:},
        !          2001: @samp{#}, @samp{=}, leading or trailing whitespace.  However,
        !          2002: variable names containing characters other than letters, numbers and
        !          2003: underscores should be avoided, as they may be given special meanings in the
        !          2004: future, and they are not passed through the environment to a
        !          2005: sub-@code{make} (@pxref{Variables/Recursion}).
        !          2006: 
        !          2007: It is traditional to use upper case letters in variable names, but we
        !          2008: recommend using lower case letters for variable names that serve internal
        !          2009: purposes in the makefile, and reserving upper case for parameters that
        !          2010: control implicit rules or for parameters that the user should override with
        !          2011: command options (@pxref{Overriding}).
        !          2012: 
        !          2013: @menu
        !          2014: * Reference::  How to use the value of a variable.
        !          2015: * Values::      All the ways variables get their values.
        !          2016: * Flavors::    Variables come in two flavors.
        !          2017: * Setting::    How to set a variable in the makefile.
        !          2018: * Override Directive:: Setting a variable in the makefile
        !          2019:                 even if the user has set it with a command argument.
        !          2020: * Defining::    An alternate way to set a variable to a verbatim string.
        !          2021: * Environment:: Variable values can come from the environment.
        !          2022: @end menu
        !          2023: 
        !          2024: @node Reference, Values, Variables, Variables
        !          2025: @section Reference to Variables
        !          2026: @cindex reference to variables
        !          2027: @cindex $ (variable reference)
        !          2028: 
        !          2029: To substitute a variable's value, write a dollar sign followed by the name
        !          2030: of the variable in parentheses or braces: either @samp{$(foo)} or
        !          2031: @samp{$@{foo@}} is a valid reference to the variable @code{foo}.  This
        !          2032: special significance of @samp{$} is why you must write @samp{$$} to have
        !          2033: the effect of a single dollar sign in a file name or command.
        !          2034: 
        !          2035: Variable references can be used in any context: targets, dependencies,
        !          2036: commands, most directives, and new variable values.  Here is a common kind
        !          2037: of example, where a variable holds the names of all the object files in a
        !          2038: program:
        !          2039: 
        !          2040: @example
        !          2041: objects = program.o foo.o utils.o
        !          2042: program : $(objects)
        !          2043:         cc -o program $(objects)
        !          2044: 
        !          2045: $(objects) : defs.h
        !          2046: @end example
        !          2047: 
        !          2048: Variable references work by strict textual substitution.  Thus, the rule
        !          2049: 
        !          2050: @example
        !          2051: foo = c
        !          2052: prog.o : prog.c
        !          2053:         $(foo)$(foo) prog.c
        !          2054: @end example
        !          2055: 
        !          2056: @noindent
        !          2057: could be used to compile a C program @file{prog.c}.  (Since spaces around
        !          2058: the variable value are ignored in variable assignments, the value of
        !          2059: @code{foo} is precisely @samp{c}.)
        !          2060: 
        !          2061: A dollar sign followed by a character other than a dollar sign,
        !          2062: open-parenthesis or open-brace treats that single character as the variable
        !          2063: name.  Thus, you could reference the variable @code{x} with @samp{$x}.
        !          2064: However, this practice is strongly discouraged, except with the automatic
        !          2065: variables (@pxref{Automatic}).
        !          2066: 
        !          2067: 
        !          2068: @subsection Modified References
        !          2069: @cindex modified variable reference
        !          2070: @cindex substitution variable reference
        !          2071: 
        !          2072: In addition to simple references, variables can be referenced in a manner
        !          2073: which modifies the value of the reference but do not modify the value of
        !          2074: the variable referenced.  Such a reference is a @dfn{substitution reference}.
        !          2075: 
        !          2076: A @dfn{substitution reference} is really a simplified form of the
        !          2077: @code{patsubst} expansion function (@pxref{Functions}).  It has the form
        !          2078: @samp{$(var:a=b)} (or @samp{$@{var:a=b@}}) and is equivalent to
        !          2079: @samp{$(patsubst %a,%b,$(var))}.  This means that it replaces every
        !          2080: @samp{a} at the end of a whitespace-separated word with a @samp{b}.
        !          2081: For example:@refill
        !          2082: 
        !          2083: @example
        !          2084: foo := a.o b.o c.o
        !          2085: bar := $(foo:.o=.c)
        !          2086: @end example
        !          2087: 
        !          2088: @noindent
        !          2089: sets @samp{bar} to @samp{a.c b.c c.c}.  @xref{Setting}.
        !          2090: 
        !          2091: @subsection Recursive References
        !          2092: @cindex recursive variable reference
        !          2093: @cindex variable reference, recursive
        !          2094: 
        !          2095: Recursive variable references are a complicated concept needed only for
        !          2096: very complex makefile programming.  You need not worry about them in
        !          2097: general, except to know that making a variable with a dollar sign in its
        !          2098: name might have strange results.  However, if you are the worrisome type or
        !          2099: are actually interested in what they do, read on.
        !          2100: 
        !          2101: Variables may be referenced inside a variable reference.  This is called
        !          2102: a @dfn{recursive variable reference}.  For example,
        !          2103: 
        !          2104: @example
        !          2105: x = y
        !          2106: y = z
        !          2107: a := $($(x))
        !          2108: @end example
        !          2109: 
        !          2110: @noindent
        !          2111: defines @samp{a} as @samp{z}: the @samp{$(x)} inside @samp{$($(x))} expands
        !          2112: to @samp{y}, so @samp{$($(x))} expands to @samp{$(y)} which in turn expands
        !          2113: to @samp{z}.@refill
        !          2114: 
        !          2115: Recursive variable references can get yet more recursive.  For example,
        !          2116: 
        !          2117: @example
        !          2118: x = $(y)
        !          2119: y = z
        !          2120: z = Hello
        !          2121: a := $($(x))
        !          2122: @end example
        !          2123: 
        !          2124: @noindent
        !          2125: defines @samp{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))}
        !          2126: which becomes @samp{$(z)} which becomes @samp{Hello}.  This sort of
        !          2127: recursion can go on for as many levels as you like (and can comprehend),
        !          2128: though it's not clear that very many levels of recursion are useful.@refill
        !          2129: 
        !          2130: Recursive variable references can also contain modified references and
        !          2131: function invokations (@pxref{Functions}), just like any other reference.
        !          2132: For example, using the @code{subst} function (@pxref{Text Functions}):
        !          2133: 
        !          2134: @example
        !          2135: x = variable1
        !          2136: variable2 := Hello
        !          2137: y = $(subst 1,2,$(x))
        !          2138: z = y
        !          2139: a := $($($(z)))
        !          2140: @end example
        !          2141: 
        !          2142: @noindent
        !          2143: eventually defines @samp{a} as @samp{Hello}.  It is doubtful that anyone
        !          2144: would ever want to write a recursive reference as convoluted as this one,
        !          2145: but it works: @samp{$($($(z)))} expands to @samp{$($(y))} which becomes
        !          2146: @samp{$($(subst 1,2,$(x)))} which changes @samp{variable1} to
        !          2147: @samp{variable2} in @samp{$(x)} and finally expands to @samp{$(variable2)},
        !          2148: a simple variable reference that becomes @samp{Hello}.@refill
        !          2149: 
        !          2150: Recursive variable references need not be as simple as @samp{$($(a))}.
        !          2151: They can contain several variable references:
        !          2152: 
        !          2153: @example
        !          2154: a_dirs := dira dirb
        !          2155: 1_dirs := dir1 dir2
        !          2156: 
        !          2157: a_files := filea fileb
        !          2158: 1_files := file1 file2
        !          2159: 
        !          2160: ifeq "$(use_a)" "yes"
        !          2161: a1 := a
        !          2162: else
        !          2163: a1 := 1
        !          2164: endif
        !          2165: 
        !          2166: ifeq "$(use_dirs)" "yes"
        !          2167: df := dirs
        !          2168: else
        !          2169: df := files
        !          2170: endif
        !          2171: 
        !          2172: dirs := $($(a1)_$(df))
        !          2173: @end example
        !          2174: 
        !          2175: @noindent
        !          2176: will give @samp{dirs} the value of @samp{a_dirs}, @samp{1_dirs},
        !          2177: @samp{a_files} or @samp{1_files} depending on the settings of @samp{use_a}
        !          2178: and @samp{use_dirs}.@refill
        !          2179: 
        !          2180: Recursive variable references can also be part of a modified reference:
        !          2181: 
        !          2182: @example
        !          2183: a_objects := a.o b.o c.o
        !          2184: 1_objects := 1.o 2.o 3.o
        !          2185: 
        !          2186: sources := $($(a1)_object:.o=.c)
        !          2187: @end example
        !          2188: 
        !          2189: @noindent
        !          2190: defines @samp{sources} as either @samp{a.c b.c c.c} or @samp{1.c 2.c 3.c},
        !          2191: depending on the value of @samp{a1}.
        !          2192: 
        !          2193: The only restriction on this sort of use of recursive variable references
        !          2194: is that they cannot specify part of a function invokation.  This is because
        !          2195: the search for an initial word matching defined function is done before the
        !          2196: check for a variable name containing a dollar sign.  Thus,
        !          2197: 
        !          2198: @example
        !          2199: ifdef do_sort
        !          2200: func := sort
        !          2201: else
        !          2202: func := strip
        !          2203: endif
        !          2204: 
        !          2205: bar := a   d b g  q  c
        !          2206: 
        !          2207: foo := $($(func) $(bar))
        !          2208: @end example
        !          2209: 
        !          2210: @noindent
        !          2211: attempts to give @samp{foo} the value of the variable @samp{sort a   d b g
        !          2212: q  c} or @samp{strip a   d b g  q  c}, rather than giving @samp{a   d b g
        !          2213: q  c} as the argument to either the @code{sort} or the @code{strip}
        !          2214: function.  This is an implementation restriction which may be removed in
        !          2215: the future if the need arises, but this is not likely since there are not
        !          2216: really any two functions you would want to give the same arguments.@refill
        !          2217: 
        !          2218: Note that @dfn{recursive variable references} are quite different from
        !          2219: @dfn{recursively expanded variables} (@pxref{Flavors}), though both are
        !          2220: used together in complex ways when doing makefile programming.@refill
        !          2221: 
        !          2222: @node Values, Flavors, Reference, Variables
        !          2223: @section How Variables Get Their Values
        !          2224: 
        !          2225: Variables can get values in several different ways:
        !          2226: 
        !          2227: @itemize @bullet
        !          2228: @item
        !          2229: You can specify an overriding value when you run @code{make}.
        !          2230: @xref{Overriding}.
        !          2231: 
        !          2232: @item
        !          2233: You can specify a value in the makefile, either with an assignment
        !          2234: (@pxref{Setting}) or with a verbatim definition (@pxref{Defining}).
        !          2235: 
        !          2236: @item
        !          2237: Values are inherited from the environment.  @xref{Environment}.
        !          2238: 
        !          2239: @item
        !          2240: Several @dfn{automatic} variables are given new values for each rule.
        !          2241: @xref{Automatic}.
        !          2242: 
        !          2243: @item
        !          2244: Several variables have constant initial values.  @xref{Implicit Variables}.
        !          2245: @end itemize
        !          2246: 
        !          2247: @node Flavors, Setting, Values, Variables
        !          2248: @section The Two Flavors of Variables
        !          2249: @cindex flavors (of variables)
        !          2250: @cindex recursive variable expansion
        !          2251: 
        !          2252: There are two kinds of variables in GNU @code{make}.  They are
        !          2253: distinguished by two things: how they are defined and how they are expanded.
        !          2254: 
        !          2255: The first flavor of variable is a @dfn{recursively expanded} variable.
        !          2256: Variables of this sort are defined by lines using @samp{=}
        !          2257: @ifinfo
        !          2258: (@pxref{Setting}).
        !          2259: @end ifinfo
        !          2260: @iftex
        !          2261: (see the next section).
        !          2262: @end iftex
        !          2263: The value you specify is installed verbatim; if it contains references to
        !          2264: other variables, these references are expanded whenever this variable is
        !          2265: substituted (in the course of expanding some other string).  When this
        !          2266: happens, it is recursive expansion.
        !          2267: 
        !          2268: For example,
        !          2269: 
        !          2270: @example
        !          2271: foo = $(bar)
        !          2272: bar = $(ugh)
        !          2273: ugh = Huh?
        !          2274: 
        !          2275: all:;echo $(foo)
        !          2276: @end example
        !          2277: 
        !          2278: @noindent
        !          2279: will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which
        !          2280: expands to @samp{$(ugh)} which finally expands to @samp{Huh?}.@refill
        !          2281: 
        !          2282: This flavor of variable is the only sort supported by other versions of
        !          2283: @code{make}.  It has its advantages and its disadvantages.  An advantage
        !          2284: (most would say) is that:
        !          2285: 
        !          2286: @example
        !          2287: CFLAGS = $(include_dirs) -O
        !          2288: include_dirs = -Ifoo -Ibar
        !          2289: @end example
        !          2290: 
        !          2291: @noindent
        !          2292: will do what was intended: when @samp{CFLAGS} is expanded in a command,
        !          2293: it will expand to @samp{-Ifoo -Ibar}.  A major disadvantage is that you
        !          2294: can't append something on the end of a variable, as in
        !          2295: 
        !          2296: @example
        !          2297: CFLAGS = $(CFLAGS) -O
        !          2298: @end example
        !          2299: 
        !          2300: @noindent
        !          2301: because it will cause an infinite loop in the variable expansion.
        !          2302: (Actually @code{make} detects the infinite loop and reports an error.)
        !          2303: 
        !          2304: Another disadvantage is that any functions (@pxref{Functions}) referenced
        !          2305: in the definition will be executed every time the variable is expanded.
        !          2306: This makes @code{make} run slower; worse, it causes the @code{wildcard}
        !          2307: function to give unpredictable results.
        !          2308: 
        !          2309: To avoid all the problems and inconveniences of recursively expanded
        !          2310: variables, there is another flavor: @dfn{simply expanded} variables.
        !          2311: Simply expanded variables are defined by lines using @samp{:=}
        !          2312: @ifinfo
        !          2313: (@pxref{Setting}).
        !          2314: @end ifinfo
        !          2315: @iftex
        !          2316: (see the next section).
        !          2317: @end iftex
        !          2318: The value of a simply expanded variable is scanned once and for all,
        !          2319: expanding any references to other variables and functions, when the
        !          2320: variable is defined.  The actual value of the simply expanded variable is
        !          2321: the result of expanding the value you write.  It does not contain any
        !          2322: references to other variables; it contains their values @emph{as of the
        !          2323: time this variable was defined}.  Therefore,
        !          2324: 
        !          2325: @example
        !          2326: x := foo
        !          2327: y := $(x) bar
        !          2328: x := later
        !          2329: @end example
        !          2330: 
        !          2331: @noindent
        !          2332: is equivalent to
        !          2333: 
        !          2334: @example
        !          2335: y := foo bar
        !          2336: x := later
        !          2337: @end example
        !          2338: 
        !          2339: When a simply expanded variable is referenced, its value is substituted
        !          2340: verbatim.
        !          2341: 
        !          2342: Simply expanded variables generally make complicated makefile programming
        !          2343: more predictable because they work like variables in most programming
        !          2344: languages.  They allow you to redefine a variable using its own value (or
        !          2345: its value processed in some way by one of the expansion functions) and to
        !          2346: use the expansion functions much more efficiently (@pxref{Functions}).
        !          2347: 
        !          2348: You can also use them to introduce controlled leading or trailing spaces
        !          2349: into variable values.  Such spaces are discarded from your input before
        !          2350: substitution of variable references and function calls; this means you can
        !          2351: include leading or trailing spaces in a variable value by protecting them
        !          2352: with variable references, like this:
        !          2353: 
        !          2354: @example
        !          2355: nullstring :=
        !          2356: space := $(nullstring) $(nullstring)
        !          2357: @end example
        !          2358: 
        !          2359: @noindent
        !          2360: Here the value of the variable @code{space} is precisely one space.
        !          2361: 
        !          2362: @node Setting, Override Directive, Flavors, Variables
        !          2363: @section Setting Variables
        !          2364: @cindex setting variables
        !          2365: @cindex =
        !          2366: @cindex :=
        !          2367: 
        !          2368: To set a variable from the makefile, write a line starting with the
        !          2369: variable name followed by @samp{=} or @samp{:=}.  Whatever follows the
        !          2370: @samp{=} or @samp{:=} on the line becomes the value.  For example,
        !          2371: 
        !          2372: @example
        !          2373: objects = main.o foo.o bar.o utils.o
        !          2374: @end example
        !          2375: 
        !          2376: @noindent
        !          2377: defines a variable named @code{objects}.  Spaces around the variable name
        !          2378: are ignored, and so are spaces after the @samp{=} or at the end of the
        !          2379: line.
        !          2380: 
        !          2381: Variables defined with @samp{=} are @dfn{recursively expanded} variables.
        !          2382: Variables defined with @samp{:=} are @dfn{simply expanded} variables; these
        !          2383: definitions can contain variable references which will be expanded before
        !          2384: the definition is made.  @xref{Flavors}. 
        !          2385: 
        !          2386: There is no limit on the length of the value of a variable except the
        !          2387: amount of swapping space on the computer.  When a variable definition is
        !          2388: long, it is a good idea to break it into several lines by inserting
        !          2389: backslash-newline at convenient places in the definition.  This will not
        !          2390: affect the functioning of @code{make}, but it will make the makefile easier
        !          2391: to read.
        !          2392: 
        !          2393: Most variable names are considered to have the empty string as a value if
        !          2394: you have never set them.  Several variables have built-in initial values
        !          2395: that are not empty, but can be set by you in the usual ways
        !          2396: (@pxref{Implicit Variables}).  Several special variables are set
        !          2397: automatically to a new value for each rule; these are called the
        !          2398: @dfn{automatic} variables (@pxref{Automatic}).
        !          2399: 
        !          2400: @node Override Directive, Defining, Setting, Variables
        !          2401: @section The @code{override} Directive
        !          2402: @findex override
        !          2403: 
        !          2404: If a variable has been set with a command argument (@pxref{Overriding}),
        !          2405: then ordinary assignments in the makefile are ignored.  If you want to set
        !          2406: the variable in the makefile even though it was set with a command
        !          2407: argument, you can use an @code{override} directive, which is a line that
        !          2408: looks like this:
        !          2409: 
        !          2410: @example
        !          2411: override @var{variable} = @var{value}
        !          2412: @end example
        !          2413: 
        !          2414: or
        !          2415: 
        !          2416: @example
        !          2417: override @var{variable} := @var{value}
        !          2418: @end example
        !          2419: 
        !          2420: The @code{override} directive was not invented for escalation in the war
        !          2421: between makefiles and command arguments.  It was invented so you can alter
        !          2422: and add to values that the user specifies with command arguments.
        !          2423: 
        !          2424: For example, suppose you always want the @samp{-g} switch when you run the
        !          2425: C compiler, but you would like to allow the user to specify the other
        !          2426: switches with a command argument just as usual.  You could use this
        !          2427: @code{override} directive:
        !          2428: 
        !          2429: @example
        !          2430: override CFLAGS := $(CFLAGS) -g
        !          2431: @end example
        !          2432: 
        !          2433: @node Defining, Environment, Override Directive, Variables
        !          2434: @section Defining Variables Verbatim
        !          2435: @findex define
        !          2436: @findex endef
        !          2437: 
        !          2438: Another way to set the value of a variable is to use the @code{define}
        !          2439: directive.  This directive has a different syntax which allows newline
        !          2440: characters to be included in the value, which is convenient for defining
        !          2441: canned sequences of commands (@pxref{Sequences}).
        !          2442: 
        !          2443: The @code{define} directive is followed on the same line the name of the
        !          2444: variable and nothing more.  The value to give the variable appears on the
        !          2445: following lines.  The end of the value is marked by a line containing just
        !          2446: the word @code{endef}.  Aside from this difference in syntax, @code{define}
        !          2447: works just like @samp{=}; it creates a recursively-expanded variable
        !          2448: (@pxref{Flavors}).
        !          2449: 
        !          2450: @example
        !          2451: define two-lines
        !          2452: echo foo
        !          2453: echo $(bar)
        !          2454: endef
        !          2455: @end example
        !          2456: 
        !          2457: The value in an ordinary assignment cannot contain a newline; but the
        !          2458: newlines that separate the lines of the value in a @code{define} become
        !          2459: part of the variable's value (except for the final newline which precedes
        !          2460: the @code{endef} and is not considered part of the value).@refill
        !          2461: 
        !          2462: The previous example is functionally equivalent to this:
        !          2463: 
        !          2464: @example
        !          2465: two-lines = echo foo; echo $(bar)
        !          2466: @end example
        !          2467: 
        !          2468: @noindent
        !          2469: since the shell will interpret the semicolon and the newline identically.
        !          2470: 
        !          2471: @node Environment,, Defining, Variables
        !          2472: @section Variables from the Environment
        !          2473: 
        !          2474: @cindex environment
        !          2475: Variables in @code{make} can come from the environment with which
        !          2476: @code{make} is run.  Every environment variable that @code{make} sees when
        !          2477: it starts up is transformed into a @code{make} variable with the same name
        !          2478: and value.  But an explicit assignment in the makefile, or with a command
        !          2479: argument, overrides the environment.  (If the @samp{-e} flag is specified,
        !          2480: then values from the environment override assignments in the makefile.
        !          2481: @xref{Options}.  But this is not recommended practice.)
        !          2482: 
        !          2483: By setting the variable @code{CFLAGS} in your environment, you can cause
        !          2484: all C compilations in most makefiles to use the compiler switches you
        !          2485: prefer.  This is safe for variables with standard or conventional meanings
        !          2486: because you know that no makefile will use them for other things.  (But
        !          2487: this is not totally reliable; some makefiles set @code{CFLAGS} explicitly
        !          2488: and therefore are not affected by the value in the environment.)
        !          2489: 
        !          2490: When @code{make} is invoked recursively, variables defined in the outer
        !          2491: invocation are automatically passed to inner invocations through the
        !          2492: environment (@pxref{Recursion}).  This is the main purpose of turning
        !          2493: environment variables into @code{make} variables, and it requires no
        !          2494: attention from you.
        !          2495: 
        !          2496: Other use of variables from the environment is not recommended.  It is not
        !          2497: wise for makefiles to depend for their functioning on environment variables
        !          2498: set up outside their control, since this would cause different users to get
        !          2499: different results from the same makefile.  This is against the whole
        !          2500: purpose of most makefiles.
        !          2501: 
        !          2502: Such problems would be especially likely with the variable @code{SHELL},
        !          2503: which is normally present in the environment to specify the user's choice
        !          2504: of interactive shell.  It would be very undesirable for this choice to
        !          2505: affect @code{make}.  So @code{make} ignores the environment value of
        !          2506: @code{SHELL} if the value of @code{MAKELEVEL} is zero (which is normally
        !          2507: true except in recursive invocations of @code{make}).@refill
        !          2508: 
        !          2509: @node Conditionals, Functions, Variables, Top
        !          2510: @chapter Conditional Parts of Makefiles
        !          2511: 
        !          2512: @cindex conditionals
        !          2513: A @dfn{conditional} causes part of a makefile to be obeyed or ignored
        !          2514: depending on the values of variables.  Conditionals can compare the value
        !          2515: of one variable with another, or the value of a variable with a constant
        !          2516: string.  Conditionals control what @code{make} actually ``sees'' in the
        !          2517: makefile, so they @emph{cannot} be used to control shell commands at the
        !          2518: time of execution.@refill
        !          2519: 
        !          2520: @menu
        !          2521: * Example: Conditional Example.   An annotated example.
        !          2522: * Syntax: Conditional Syntax.     Precise rules for syntax of conditionals.
        !          2523: * Flags: Testing Flags.           Conditionals testing flags such as @samp{-t}.
        !          2524: @end menu
        !          2525: 
        !          2526: @node Conditional Example, Conditional Syntax, Conditionals, Conditionals
        !          2527: @section Example of a Conditional
        !          2528: 
        !          2529: This conditional tells @code{make} to use one set of libraries if the
        !          2530: @code{CC} variable is @samp{gcc}, and a different set of libraries
        !          2531: otherwise.  It works by controlling which of two command lines will be used
        !          2532: as the command for a rule.  The result is that @samp{CC=gcc} as an argument
        !          2533: to @code{make} not only changes which compiler is used but also which
        !          2534: libraries are linked.
        !          2535: 
        !          2536: @example
        !          2537: libs_for_gcc = -lgnu
        !          2538: normal_libs =
        !          2539: 
        !          2540: foo: $(objects)
        !          2541: ifeq ($(CC),gcc)
        !          2542:         $(CC) -o foo $(objects) $(libs_for_gcc)
        !          2543: else
        !          2544:         $(CC) -o foo $(objects) $(normal_libs)
        !          2545: endif
        !          2546: @end example
        !          2547: 
        !          2548: @noindent
        !          2549: This conditional uses three directives: one @code{ifeq}, one @code{else}
        !          2550: and one @code{endif}.
        !          2551: 
        !          2552: The @code{ifeq} directive contains two arguments, separated by a comma and
        !          2553: surrounded by parentheses.  Variable substitution is performed on both
        !          2554: arguments and then they are compared.  The lines of the makefile following
        !          2555: the @code{ifeq} are obeyed if the two arguments match; otherwise they are
        !          2556: ignored.
        !          2557: 
        !          2558: The @code{else} directive causes the following lines to be obeyed if the
        !          2559: previous conditional failed.  In the example above, this means that the
        !          2560: second alternative linking command is used whenever the first alternative
        !          2561: is not used.  It is optional to have an @code{else} in a conditional.
        !          2562: 
        !          2563: The @code{endif} directive ends the conditional.  Every conditional must
        !          2564: end with an @code{endif}.  Unconditional makefile text follows.
        !          2565: 
        !          2566: When the variable @code{CC} has the value @samp{gcc}, the above example has
        !          2567: this effect:
        !          2568: 
        !          2569: @example
        !          2570: foo: $(objects)
        !          2571:         $(CC) -o foo $(objects) $(libs_for_gcc)
        !          2572: @end example
        !          2573: 
        !          2574: @noindent
        !          2575: When the variable @code{CC} has any other value, this effect is this:
        !          2576: 
        !          2577: @example
        !          2578: foo: $(objects)
        !          2579:         $(CC) -o foo $(objects) $(normal_libs)
        !          2580: @end example
        !          2581: 
        !          2582: Equivalent results can be obtained in another way by conditionalizing a
        !          2583: variable assignment and then using the variable unconditionally:
        !          2584: 
        !          2585: @example
        !          2586: libs_for_gcc = -lgnu
        !          2587: normal_libs =
        !          2588: 
        !          2589: ifeq ($(CC),gcc)
        !          2590:   libs=$(libs_for_gcc)
        !          2591: else
        !          2592:   libs=$(normal_libs)
        !          2593: endif
        !          2594: 
        !          2595: foo: $(objects)
        !          2596:         $(CC) -o foo $(objects) $(libs)
        !          2597: @end example
        !          2598: 
        !          2599: @node Conditional Syntax, Testing Flags, Conditional Example, Conditionals
        !          2600: @section Syntax of Conditionals
        !          2601: @findex ifdef
        !          2602: @findex ifeq
        !          2603: @findex else
        !          2604: @findex endif
        !          2605: 
        !          2606: The syntax of a simple conditional with no @code{else} is as follows:
        !          2607: 
        !          2608: @example
        !          2609: @var{conditional-directive}
        !          2610: @var{text-if-true}
        !          2611: endif
        !          2612: @end example
        !          2613: 
        !          2614: @noindent
        !          2615: The @var{text-if-true} may be any lines of text, to be considered as part
        !          2616: of the makefile if the condition is true.  If the condition is false, no
        !          2617: text is used instead.
        !          2618: 
        !          2619: The syntax of a complex conditional is as follows:
        !          2620: 
        !          2621: @example
        !          2622: @var{conditional-directive}
        !          2623: @var{text-if-true}
        !          2624: else
        !          2625: @var{text-if-false}
        !          2626: endif
        !          2627: @end example
        !          2628: 
        !          2629: @noindent
        !          2630: If the condition is true, @var{text-if-true} is used; otherwise,
        !          2631: @var{text-if-false} is used instead.  The @var{text-if-false} can be any
        !          2632: number of lines of text.
        !          2633: 
        !          2634: Conditionals work at the textual level.  The lines of the
        !          2635: @var{text-if-true} are read as part of the makefile if the condition is
        !          2636: true; if the condition is false, those lines are ignored completely.  It
        !          2637: follows that syntactic units of the makefile, such as rules, may safely be
        !          2638: split across the beginning or the end of the conditional.@refill
        !          2639: 
        !          2640: You may use an @code{include} directive within a conditional, but you may
        !          2641: not start a conditional in one file and end it in another.
        !          2642: 
        !          2643: The syntax of the @var{conditional-directive} is the same whether the
        !          2644: conditional is simple or complex.  There are four different directives that
        !          2645: test different conditions.  Here is a table of them:
        !          2646: 
        !          2647: @table @code
        !          2648: @item ifeq (@var{arg1}, @var{arg2})
        !          2649: Expand all variable references in @var{arg1} and @var{arg2} and
        !          2650: compare them.  If they are identical, the @var{text-if-true} is
        !          2651: effective; otherwise, the @var{text-if-false}, if any, is effective.
        !          2652: 
        !          2653: @item ifneq (@var{arg1}, @var{arg2})
        !          2654: Expand all variable references in @var{arg1} and @var{arg2} and
        !          2655: compare them.  If they are different, the @var{text-if-true} is
        !          2656: effective; otherwise, the @var{text-if-false}, if any, is effective.
        !          2657: 
        !          2658: @item ifdef @var{variable-name}
        !          2659: If the variable @var{variable-name} has a non-empty value, the
        !          2660: @var{text-if-true} is effective; otherwise, the @var{text-if-false},
        !          2661: if any, is effective.  Variables that have never been defined have an
        !          2662: empty value.
        !          2663: 
        !          2664: @item ifndef @var{variable-name}
        !          2665: If the variable @var{variable-name} has an empty value, the
        !          2666: @var{text-if-true} is effective; otherwise, the @var{text-if-false},
        !          2667: if any, is effective.
        !          2668: @end table
        !          2669: 
        !          2670: Extra spaces are allowed and ignored at the beginning of the conditional
        !          2671: directive line, but a tab is not allowed.  (If the line begins with a tab,
        !          2672: it will be considered a command for a rule.)  Aside from this, extra spaces
        !          2673: or tabs may be inserted with no effect anywhere except within the directive
        !          2674: name or within an argument.  A comment starting with @samp{#} may appear at
        !          2675: the end of the line.
        !          2676: 
        !          2677: The other two directives that play a part in a conditional are @code{else}
        !          2678: and @code{endif}.  Each of these directives is written as one word, with no
        !          2679: arguments.  Extra spaces are allowed and ignored at the beginning of the
        !          2680: line, and spaces or tabs at the end.  A comment starting with @samp{#} may
        !          2681: appear at the end of the line.
        !          2682: 
        !          2683: @node Testing Flags,, Conditional Syntax, Conditionals
        !          2684: @section Conditionals that Test Flags
        !          2685: 
        !          2686: You can write a conditional that tests @code{make} command flags such as
        !          2687: @samp{-t} by using the variable @code{MAKEFLAGS} together with the
        !          2688: @code{findstring} function.  This is useful when @code{touch} is not
        !          2689: enough to make a file appear up to date.
        !          2690: 
        !          2691: The @code{findstring} function determines whether one string appears as a
        !          2692: substring of another.  If you want to test for the @samp{-t} flag,
        !          2693: use @samp{t} as the first string and the value of @code{MAKEFLAGS} as
        !          2694: the other.
        !          2695: 
        !          2696: For example, here is how to arrange to use @samp{ranlib -t} to finish
        !          2697: marking an archive file up to date:
        !          2698: 
        !          2699: @example
        !          2700: archive.a: @dots{}
        !          2701: ifneq (,$(findstring t,$(MAKEFLAGS)))
        !          2702:         @@echo $(MAKE) > /dev/null
        !          2703:         touch archive.a
        !          2704:         ranlib -t archive.a
        !          2705: else
        !          2706:         ranlib archive.a
        !          2707: endif
        !          2708: @end example
        !          2709: 
        !          2710: @noindent
        !          2711: The @code{echo} command does nothing when executed; but its presence, with
        !          2712: a reference to the variable @code{MAKE}, marks the rule as ``recursive'' so
        !          2713: that its commands will be executed despite use of the @samp{-t} flag.
        !          2714: @xref{Recursion}.
        !          2715: 
        !          2716: @node Functions, Running, Conditionals, Top
        !          2717: @chapter Functions for Transforming Text
        !          2718: @cindex function
        !          2719: 
        !          2720: @dfn{Functions} allow you to do text processing in the makefile to compute
        !          2721: the files to operate on or the commands to use.  You use a function in a
        !          2722: @dfn{function call}, where you give the name of the function and some text
        !          2723: (the @dfn{arguments}) for the function to operate on.  The result of the
        !          2724: function's processing is substituted into the makefile at the point of the
        !          2725: call, just as a variable might be substituted.
        !          2726: 
        !          2727: @menu
        !          2728: * Syntax: Function Syntax.  Syntax of function calls in general.
        !          2729: * Text Functions::          Text manipulation functions.
        !          2730: * Foreach Function::        The @code{foreach} function.
        !          2731: * Filename Functions::      Functions for manipulating file names.
        !          2732: @end menu
        !          2733: 
        !          2734: @node Function Syntax, Text Functions, Functions, Functions
        !          2735: @section Function Call Syntax
        !          2736: @cindex $ (function call)
        !          2737: @cindex arguments
        !          2738: 
        !          2739: A function call resembles a variable reference.  It looks like this:
        !          2740: 
        !          2741: @example
        !          2742: $(@var{function} @var{arguments})
        !          2743: @end example
        !          2744: 
        !          2745: @noindent
        !          2746: or like this:
        !          2747: 
        !          2748: @example
        !          2749: $@{@var{function} @var{arguments}@}
        !          2750: @end example
        !          2751: 
        !          2752: Here @var{function} is a function name; one of a short list of names that
        !          2753: are part of @code{make}.  There is no provision for defining new functions.
        !          2754: 
        !          2755: The @var{arguments} are the arguments of the function.  They are separated
        !          2756: from the function name by one or more spaces and/or tabs, and if there is
        !          2757: more than one argument they are separated by commas.  Such whitespace and
        !          2758: commas are not part of any argument's value.  Parentheses or braces,
        !          2759: whichever you use to surround the function call, can appear in an argument
        !          2760: only in matching pairs; the ones that were not used to surround the
        !          2761: function call can appear freely.  If the arguments contain other function
        !          2762: calls or variable references, it is wisest to surround them with the same
        !          2763: delimiters used for the containing function call.
        !          2764: 
        !          2765: The text written for each argument is processed by substitution of
        !          2766: variables and function calls in order to produce the argument value, which
        !          2767: is the text on which the function acts.
        !          2768: 
        !          2769: Commas and unmatched parentheses or braces cannot appear in the text of an
        !          2770: argument as written; leading spaces cannot appear in the text of the first
        !          2771: argument as written.  These characters can be put into the argument value
        !          2772: by variable substitution.  First define variables @code{comma} and
        !          2773: @code{space} whose values are isolated comma and space characters, then
        !          2774: substitute those variables where such characters are wanted, like this:
        !          2775: 
        !          2776: @example
        !          2777: comma:= ,
        !          2778: space:= $(empty) $(empty)
        !          2779: foo:= a b c
        !          2780: bar:= $(subst $(space),$(comma),$(foo))
        !          2781: # @r{bar is now `a,b,c'.}
        !          2782: @end example
        !          2783: 
        !          2784: @noindent
        !          2785: Here the @code{subst} function replaces each space with a comma, through
        !          2786: the value of @code{foo}, and substitutes the result.
        !          2787: 
        !          2788: @node Text Functions, Foreach Function, Function Syntax, Functions
        !          2789: @section Functions for String Substitution and Analysis
        !          2790: 
        !          2791: Here are some functions that operate strings:
        !          2792: 
        !          2793: @table @code
        !          2794: @item $(subst @var{from},@var{to},@var{text})
        !          2795: @findex subst
        !          2796: Performs a textual replacement on the text @var{text}: each occurrence
        !          2797: of @var{from} is replaced by @var{to}.  The result is substituted for
        !          2798: the function call.  For example,
        !          2799: 
        !          2800: @example
        !          2801: $(subst ee,EE,feet on the street)
        !          2802: @end example
        !          2803: 
        !          2804: substitutes the string @samp{fEEt on the strEEt}.
        !          2805: 
        !          2806: @item $(patsubst @var{pattern},@var{replacement},@var{text})
        !          2807: @findex patsubst
        !          2808: Finds whitespace-separated words in @var{text} that match
        !          2809: @var{pattern} and replaces them with @var{replacement}.  Here
        !          2810: @var{pattern} may contain a @samp{%} which acts as a wildcard,
        !          2811: matching any number of any characters within a word.  If
        !          2812: @var{replacement} also contains a @samp{%}, the @samp{%} is replaced
        !          2813: by the text that matched the @samp{%} in @var{pattern}.@refill
        !          2814: 
        !          2815: Whitespace between words is folded into single space characters;
        !          2816: leading and trailing whitespace is discarded.
        !          2817: 
        !          2818: @item $(strip @var{string})
        !          2819: @findex strip
        !          2820: Removes leading and trailing whitespace from @var{string} and replaces
        !          2821: each internal sequence of one or more whitespace characters with a
        !          2822: single space.
        !          2823: 
        !          2824: @item $(findstring @var{find},@var{in})
        !          2825: @findex findstring
        !          2826: Searches @var{in} for an occurrence of @var{find}.  If it occurs, the
        !          2827: value is @var{find}; otherwise, the value is empty.  You can use this
        !          2828: function in a conditional to test for the presence of a specific
        !          2829: substring in a given string.  @xref{Testing Flags}, for a practical
        !          2830: application of @code{findstring}.
        !          2831: 
        !          2832: @item $(filter @var{pattern},@var{text})
        !          2833: @findex filter
        !          2834: Removes all whitespace-separated words in @var{text} that do @emph{not}
        !          2835: match @var{pattern}, returning only matching words.  The pattern is one
        !          2836: using @samp{%} as used in the @code{patsubst} function.  This can be used
        !          2837: to separate out different types of strings (such as filenames) in a variable.
        !          2838: For example:@refill
        !          2839: 
        !          2840: @example
        !          2841: sources := foo.c bar.c ugh.h
        !          2842: foo: $(sources)
        !          2843:         cc $(filter %.c,$(sources)) -o foo
        !          2844: @end example
        !          2845: 
        !          2846: @noindent
        !          2847: says that @file{foo} depends of @file{foo.c}, @file{bar.c} and
        !          2848: @file{ugh.h} but only @file{foo.c} and @file{bar.c} should be specified
        !          2849: in the command to the compiler.@refill
        !          2850: 
        !          2851: @item $(filter-out @var{pattern},@var{text})
        !          2852: @findex filter-out
        !          2853: Removes all whitespace-separated words in @var{text} that @emph{do}
        !          2854: match @var{pattern}, returning only matching words.  This is the exact
        !          2855: opposite of the @code{filter} function.@refill
        !          2856: 
        !          2857: @item $(sort @var{list})
        !          2858: @findex sort
        !          2859: Sorts the words of @var{list} in lexical order, removing duplicate
        !          2860: words.  The output is a list of words separated by single spaces.
        !          2861: 
        !          2862: @item $(word @var{n},@var{text})
        !          2863: @findex word
        !          2864: Returns the @var{n}th word of @var{text}.  If @var{n} is bigger than
        !          2865: the number of words in @var{text}, nothing is returned.  If you give
        !          2866: 0 as @var{n}, you will get a fatal error to remind you to quit
        !          2867: thinking like a C programmer.
        !          2868: 
        !          2869: @item $(words @var{text})
        !          2870: @findex words
        !          2871: Returns the number of words in @var{text}.  Thus, @code{$(word
        !          2872: $(words @var{text}),@var{text})} is the last word of @var{text}.@refill
        !          2873: @end table
        !          2874: 
        !          2875: Here is a realistic example of the use of @code{subst}.  Suppose that a
        !          2876: makefile uses the @code{VPATH} variable to specify a list of directories
        !          2877: that @code{make} should search for dependency files.  This example shows
        !          2878: how to tell the C compiler to search for header files in the same list of
        !          2879: directories.
        !          2880: 
        !          2881: The value of @code{VPATH} is a list of directories separated by colons,
        !          2882: such as @samp{src:../headers}.  First, the @code{subst} function is used to
        !          2883: change the colons to spaces:
        !          2884: 
        !          2885: @example
        !          2886: $(subst :, ,$(VPATH))
        !          2887: @end example
        !          2888: 
        !          2889: @noindent
        !          2890: This produces @samp{src ../headers}.  Then another function,
        !          2891: @code{addprefix}, can turn each directory name into an @samp{-I} flag.
        !          2892: These can be added to the value of the variable @code{CFLAGS}, which is
        !          2893: passed automatically to the C compiler, like this:
        !          2894: 
        !          2895: @example
        !          2896: override CFLAGS:= $(CFLAGS) $(addprefix -I,$(subst :, ,$(VPATH)))
        !          2897: @end example
        !          2898: 
        !          2899: @noindent
        !          2900: The effect is to append the text @samp{-Isrc -I../headers} to the
        !          2901: previously given value of @code{CFLAGS}.  The @code{override} directive is
        !          2902: used so that the new value is assigned even if the previous value of
        !          2903: @code{CFLAGS} was specified with a command argument (@pxref{Override
        !          2904: Directive}).
        !          2905: 
        !          2906: The function @code{strip} can be very useful when used in conjunction
        !          2907: with conditionals.  When comparing something with the null string
        !          2908: @samp{""} using @code{ifeq} or @code{ifneq}, you usually want a string
        !          2909: of just whitespace to match the null string.  Thus,
        !          2910: 
        !          2911: @example
        !          2912: .PHONY: all
        !          2913: ifneq  "$(needs_made)" ""
        !          2914: all: $(needs_made)
        !          2915: else
        !          2916: all:;@@echo 'Nothing to make!'
        !          2917: endif
        !          2918: @end example
        !          2919: 
        !          2920: @noindent
        !          2921: might fail to have the desired results.  Replacing the variable reference
        !          2922: @samp{"$(needs_made)"} with the function call @samp{"$(strip
        !          2923: $(needs_made))"} in the @code{ifneq} directive would make it more robust.
        !          2924: 
        !          2925: @node Foreach Function, Filename Functions, Text Functions, Functions
        !          2926: @section The @code{foreach} Function
        !          2927: @findex foreach
        !          2928: 
        !          2929: The @code{foreach} function is very different from other functions.  It
        !          2930: causes one piece of text to be used repeatedly, each time with a different
        !          2931: substitution performed on it.  It resembles the @code{for} command in the
        !          2932: shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}.
        !          2933: 
        !          2934: The syntax of the @code{foreach} function is:
        !          2935: 
        !          2936: @example
        !          2937: $(foreach @var{var},@var{list},@var{text})
        !          2938: @end example
        !          2939: 
        !          2940: @noindent
        !          2941: The first two arguments, @var{var} and @var{list}, are expanded before
        !          2942: anything else is done; note that the last argument, @var{text}, is
        !          2943: @emph{not} expanded at the same time.  Then for each word of the expanded
        !          2944: value of @var{list}, the variable named by the expanded value of @var{var}
        !          2945: is set to that word, and @var{text} is expanded.  Presumably @var{text}
        !          2946: contains references to that variable, so the expansions will be different
        !          2947: each time.
        !          2948: 
        !          2949: The result is that @var{text} is expanded as many times as there are
        !          2950: whitespace-separated words in @var{list}.  The multiple expansions of
        !          2951: @var{text} are concatenated, with spaces between them, to make the result
        !          2952: of @code{foreach}.
        !          2953: 
        !          2954: This simple example sets the variable @samp{files} to the list of all files
        !          2955: in the directories in the list @samp{dirs}:
        !          2956: 
        !          2957: @example
        !          2958: find_files = $(wildcard $(dir)/*)
        !          2959: dirs := a b c d
        !          2960: files := $(foreach dir,$(dirs),$(find_files))
        !          2961: @end example
        !          2962: 
        !          2963: For readability, it is a good idea to put the @var{text} part of a
        !          2964: @code{foreach} function invokation into a variable.  Here we use the
        !          2965: variable @code{find_file} this way.  We make this a recursively-expanding
        !          2966: variable by using @samp{=} to define it.  This is necessary so that when
        !          2967: its value is substituted by @code{foreach} the value is rescanned for
        !          2968: variable references and function calls.  This is what causes the
        !          2969: @code{wildcard} function actually to be called.
        !          2970: 
        !          2971: This example has the same result (except for setting @samp{find_files},
        !          2972: @samp{dirs} and @samp{dir}) as the following example:
        !          2973: 
        !          2974: @example
        !          2975: files := $(wildcard a/* b/* c/* d/*)
        !          2976: @end example
        !          2977: 
        !          2978: The value of the variable @var{var} after the @code{foreach} function call
        !          2979: is the same as the value beforehand.  Other values taken from @var{list}
        !          2980: are in effect only temporarily, during the execution of @code{foreach}.
        !          2981: The variable @var{var} is a simply-expanded variable during the execution
        !          2982: of @code{foreach} but is returned to the same flavor it was before the
        !          2983: @code{foreach} when it is done.  @xref{Flavors}.
        !          2984: 
        !          2985: If @var{var} was previously undefined, then it is defined as a recursively
        !          2986: expanded variable (@samp{=}, not @samp{:=}) during the @code{foreach} and
        !          2987: remains so (with a null value) afterward.
        !          2988: 
        !          2989: Because it is expanded before @code{foreach} runs, the @var{var} argument
        !          2990: to @code{foreach} need not be a literal variable name.  It can instead be a
        !          2991: variable expression resulting in the name.  Thus,
        !          2992: 
        !          2993: @example
        !          2994: dir := a
        !          2995: var = $(whatsthevar)
        !          2996: foo := dar
        !          2997: whatsthevar := $(subst a,i,$(foo))
        !          2998: files := $(foreach $(var),$(dirs),$(find_files))
        !          2999: @end example
        !          3000: 
        !          3001: @noindent
        !          3002: is ultimately equivalent to the first example.  You must take care when
        !          3003: using complex variable expressions that result in variable names because
        !          3004: many strange things are legal variable names, and these might not be what
        !          3005: you intended.  For example,
        !          3006: 
        !          3007: @example
        !          3008: files := $(foreach Es escrito en espanol!,b c ch,$(find_files))
        !          3009: @end example
        !          3010: 
        !          3011: @noindent
        !          3012: might be useful if @samp{find_files} references the variable @samp{Es
        !          3013: escrito en espanol!} (es un nombre bastante largo, no?), but it is more
        !          3014: likely to be a mistake.
        !          3015: 
        !          3016: @node Filename Functions,, Foreach Function, Functions
        !          3017: @section Functions for File Names
        !          3018: 
        !          3019: Several of the built-in expansion functions relate specifically to
        !          3020: taking apart file names or lists of file names.
        !          3021: 
        !          3022: Each of these functions performs a specific transformation on a file name.
        !          3023: The argument of the function is regarded as a series of file names,
        !          3024: separated by whitespace.  (Leading and trailing whitespace is ignored.)
        !          3025: Each file name in the series is transformed in the same way and the results
        !          3026: are concatenated with single spaces between them.
        !          3027: 
        !          3028: @table @code
        !          3029: @item $(dir @var{names})
        !          3030: @findex dir
        !          3031: Extracts the directory-part of each file name in @var{names}.  The
        !          3032: directory-part of the file name is everything up through (and
        !          3033: including) the last slash in it.  If the file name contains no slash,
        !          3034: the directory part is the string @samp{./}.  For example,
        !          3035: 
        !          3036: @example
        !          3037: $(dir src/foo.c hacks)
        !          3038: @end example
        !          3039: 
        !          3040: @noindent
        !          3041: produces the result @samp{src/ ./}.
        !          3042: 
        !          3043: @item $(notdir @var{names})
        !          3044: @findex notdir
        !          3045: Extracts all but the directory-part of each file name in @var{names}.
        !          3046: If the file name contains no slash, it is left unchanged.  Otherwise,
        !          3047: everything through the last slash is removed from it.  A file name
        !          3048: that ends with a slash becomes an empty string.  This is unfortunate,
        !          3049: because it means that the result does not always have the same number
        !          3050: of whitespace-separated file names as the argument had; but we do not
        !          3051: see any other valid alternative.
        !          3052: 
        !          3053: For example,
        !          3054: 
        !          3055: @example
        !          3056: $(notdir src/foo.c hacks)
        !          3057: @end example
        !          3058: 
        !          3059: @noindent
        !          3060: produces the result @samp{foo.c hacks}.
        !          3061: 
        !          3062: @item $(suffix @var{names})
        !          3063: @findex suffix
        !          3064: Extracts the suffix of each file name in @var{names}.  If the file name
        !          3065: contains a period, the suffix is everything starting with the last
        !          3066: period.  Otherwise, the suffix is the empty string.  This frequently
        !          3067: means that the result will be empty when @var{names} is not, and if
        !          3068: @var{names} contains multiple file names, the result may contain fewer
        !          3069: file names.
        !          3070: 
        !          3071: For example,
        !          3072: 
        !          3073: @example
        !          3074: $(suffix src/foo.c hacks)
        !          3075: @end example
        !          3076: 
        !          3077: @noindent
        !          3078: produces the result @samp{.c}.
        !          3079: 
        !          3080: @item $(basename @var{names})
        !          3081: @findex basename
        !          3082: Extracts all but the suffix of each file name in @var{names}.  If the
        !          3083: file name contains a period, the basename is everything starting up to
        !          3084: (and not including) the last period.  Otherwise, the basename is the
        !          3085: entire file name.  For example,
        !          3086: 
        !          3087: @example
        !          3088: $(basename src/foo.c hacks)
        !          3089: @end example
        !          3090: 
        !          3091: @noindent
        !          3092: produces the result @samp{src/foo hacks}.
        !          3093: 
        !          3094: @item $(addsuffix @var{suffix},@var{names})
        !          3095: @findex addsuffix
        !          3096: The argument @var{names} is regarded as a series of names, separated
        !          3097: by whitespace; @var{suffix} is used as a unit.  The value of
        !          3098: @var{suffix} is appended to the end of each individual name and the
        !          3099: resulting larger names are concatenated with single spaces between
        !          3100: them.  For example,
        !          3101: 
        !          3102: @example
        !          3103: $(addsuffix .c,foo bar)
        !          3104: @end example
        !          3105: 
        !          3106: @noindent
        !          3107: produces the result @samp{foo.c bar.c}.
        !          3108: 
        !          3109: @item $(addprefix @var{prefix},@var{names})
        !          3110: @findex addprefix
        !          3111: The argument @var{names} is regarded as a series of names, separated
        !          3112: by whitespace; @var{prefix} is used as a unit.  The value of
        !          3113: @var{prefix} is appended to the front of each individual name and the
        !          3114: resulting larger names are concatenated with single spaces between
        !          3115: them.  For example,
        !          3116: 
        !          3117: @example
        !          3118: $(addprefix src/,foo bar)
        !          3119: @end example
        !          3120: 
        !          3121: @noindent
        !          3122: produces the result @samp{src/foo src/bar}.
        !          3123: 
        !          3124: @item $(join @var{list1},@var{list2})
        !          3125: @findex join
        !          3126: Concatenates the two arguments word by word: the two first words (one
        !          3127: from each argument) concatenated form the first word of the result, the
        !          3128: two second words form the second word of the result, and so on.  So the
        !          3129: @var{n}th word of the result comes from the @var{n}th word of each
        !          3130: argument.  If one argument has more words that the other, the extra
        !          3131: words are copied unchanged into the result.
        !          3132: 
        !          3133: For example, @samp{$(join a b,.c .o)} produces @samp{a.c b.o}.
        !          3134: 
        !          3135: Whitespace between the words in the lists is not preserved; it is
        !          3136: replaced with a single space.
        !          3137: 
        !          3138: This function can reverse the effect of the @code{dir} and @code{notdir}
        !          3139: functions, after other processing has been done on the separated lists
        !          3140: of directories and files.@refill
        !          3141: 
        !          3142: @item $(firstword @var{names})
        !          3143: @findex firstword
        !          3144: The argument @var{names} is regarded as a series of names, separated
        !          3145: by whitespace.  The value is the first name in the series.  The rest
        !          3146: of the names are ignored.  For example,
        !          3147: 
        !          3148: @example
        !          3149: $(firstword foo bar)
        !          3150: @end example
        !          3151: 
        !          3152: @noindent
        !          3153: produces the result @samp{foo}.  Although @code{$(firstword
        !          3154: @var{text})} is the same as @code{$(word 1,@var{text})}, the
        !          3155: @code{firstword} function is retained for its ease of use.@refill
        !          3156: 
        !          3157: @item $(wildcard @var{pattern})
        !          3158: @findex wildcard
        !          3159: The argument @var{pattern} is a file name pattern, typically containing
        !          3160: wildcard characters.  The result of @code{wildcard} is a space-separated
        !          3161: list of the names of existing files that match the pattern.
        !          3162: 
        !          3163: Wildcards are expanded automatically in rules (@pxref{Wildcards}).
        !          3164: But they are not normally expanded when a variable is set, or inside the
        !          3165: arguments of other functions.  Those occasions are when the @code{wildcard}
        !          3166: function is useful.
        !          3167: @end table
        !          3168: 
        !          3169: @node Running, Implicit, Functions, Top
        !          3170: @chapter How to Run @code{make}
        !          3171: 
        !          3172: A makefile that says how to recompile a program can be used in more than
        !          3173: one way.  The simplest use is to recompile every file that is out of date.
        !          3174: This is what @code{make} will do if run with no arguments.
        !          3175: 
        !          3176: But you might want to update only some of the files; you might want to use
        !          3177: a different compiler or different compiler options; you might want just to
        !          3178: find out which files are out of date without changing them.
        !          3179: 
        !          3180: By specifying arguments when you run @code{make}, you can do any of these
        !          3181: things or many others.
        !          3182: 
        !          3183: @menu
        !          3184: * Makefile Arguments::    Arguments to specify which makefile to use.
        !          3185: 
        !          3186: * Goals::                 Goal arguments specify which parts of the makefile
        !          3187:                            should be used.
        !          3188: 
        !          3189: * Avoid Compilation::     How to avoid recompiling certain files.
        !          3190: 
        !          3191: * Instead of Execution::  Mode flags specify what kind of thing to do
        !          3192:                            with the commands in the makefile
        !          3193:                            other than simply execute them.
        !          3194: 
        !          3195: * Overriding::            Overriding a variable can specify an alternate
        !          3196:                            compiler, or alternate flags for the compiler,
        !          3197:                            or whatever else you program into the makefile.
        !          3198: 
        !          3199: * Testing::               How to proceed past some errors, to test compilation.
        !          3200: 
        !          3201: * Options::               Summary of all options @code{make} accepts.
        !          3202: @end menu
        !          3203: 
        !          3204: @node Makefile Arguments, Goals, Running, Running
        !          3205: @section Arguments to Specify the Makefile
        !          3206: 
        !          3207: The way to specify the name of the makefile is with the @samp{-f} option.
        !          3208: For example, @samp{-f altmake} says to use the file @file{altmake} as
        !          3209: the makefile.
        !          3210: 
        !          3211: If you use the @samp{-f} flag several times (each time with a
        !          3212: following argument), all the specified files are used jointly as
        !          3213: makefiles.
        !          3214: 
        !          3215: If you do not use the @samp{-f} flag, the default is to use
        !          3216: @file{./makefile}, or, if that does not exist, @file{./Makefile}.
        !          3217: @xref{Makefiles}.@refill
        !          3218: 
        !          3219: @node Goals, Avoid Compilation, Makefile Arguments, Running
        !          3220: @section Goals
        !          3221: @cindex goal
        !          3222: 
        !          3223: The @dfn{goals} are the targets that @code{make} should strive ultimately
        !          3224: to update.  Other targets are updated as well if they appear as
        !          3225: dependencies of goals, or dependencies of dependencies of goals, etc.
        !          3226: 
        !          3227: By default, the goal is the first target in the makefile (not counting
        !          3228: targets that start with a period or that appear in included makefiles).
        !          3229: Therefore, makefiles are usually written so that the first target is for
        !          3230: compiling the entire program or programs they describe.
        !          3231: 
        !          3232: You can specify a different goal or goal with arguments to @code{make}.
        !          3233: Use the name of the goal as an argument.  If you specify several goals,
        !          3234: @code{make} processes each of them in turn, in the order you name them.
        !          3235: 
        !          3236: Any target in the makefile may be specified as a goal (unless it starts
        !          3237: with @samp{-} or contains an @samp{=}).  Even targets not in the makefile
        !          3238: may be specified, if @code{make} can find implicit rules that say how to
        !          3239: make them.
        !          3240: 
        !          3241: One use of specifying a goal is if you want to compile only a part of
        !          3242: the program, or only one of several programs.  Specify as a goal each
        !          3243: file that you wish to remake.  For example, consider a directory containing
        !          3244: a several programs, with a makefile that starts like this:
        !          3245: 
        !          3246: @example
        !          3247: .PHONY: all
        !          3248: all: size nm ld ar as
        !          3249: @end example
        !          3250: 
        !          3251: If you are working on the program @code{size}, you might want to say
        !          3252: @samp{make size} so that only the files of that program are recompiled.
        !          3253: 
        !          3254: Another use of specifying a goal is to make files that aren't normally
        !          3255: made.  For example, there may be a file of debugging output, or a version
        !          3256: of the program that is compiled specially for testing, which has a rule
        !          3257: in the makefile but isn't a dependency of the default goal.
        !          3258: 
        !          3259: Another use of specifying a goal is to run the commands associated with a
        !          3260: phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty Targets}).
        !          3261: Many makefiles contain a phony target named @file{clean} which deletes
        !          3262: everything except source files.  Naturally, this is done only if you
        !          3263: request it explicitly with @samp{make clean}.  Here is a list of typical
        !          3264: phony and empty target names:
        !          3265: 
        !          3266: @table @file
        !          3267: @item all
        !          3268: Make all the top-level targets the makefile knows about.
        !          3269: 
        !          3270: @item clean
        !          3271: Delete all files that the makefile could remake.
        !          3272: 
        !          3273: @item clobber
        !          3274: Delete absolutely everything the makefile could remake (whereas
        !          3275: @samp{make clean} often leaves intact some files that might take a
        !          3276: long time to remake).
        !          3277: 
        !          3278: @item install
        !          3279: Copy the executable file into a directory that users typically search
        !          3280: for commands; copy any auxiliary files that the executable uses into
        !          3281: the directories where it will look for them.
        !          3282: 
        !          3283: @item print
        !          3284: Print listings of the source files that have changed.
        !          3285: 
        !          3286: @item tar
        !          3287: Create a tar file of the source files.
        !          3288: 
        !          3289: @item shar
        !          3290: Create a shell archive (shar file) of the source files.
        !          3291: @end table
        !          3292: 
        !          3293: @node Avoid Compilation, Instead of Execution, Goals, Running
        !          3294: @section Avoiding Recompilation of Some Files
        !          3295: @cindex -o
        !          3296: 
        !          3297: Sometimes you may have changed a source file but you don't want to
        !          3298: recompile all the files that depend on it.  For example, suppose you add a
        !          3299: macro or a declaration to a header file that many other files depend on.
        !          3300: Being conservative, @code{make} assumes that any change in the header file
        !          3301: requires recompilation of all dependent files, but you know that they don't
        !          3302: need to be recompiled and you would rather not waste the time waiting.
        !          3303: 
        !          3304: If you anticipate the problem before making the change, you can use the
        !          3305: @samp{-t} flag.  This flag tells @code{make} not to run the commands in the
        !          3306: rules, but rather to mark the target up to date by changing its
        !          3307: last-modification date.  You would follow this procedure:
        !          3308: 
        !          3309: @enumerate
        !          3310: @item
        !          3311: Use the command @samp{make} to recompile the source files that really
        !          3312: need recompilation.
        !          3313: 
        !          3314: @item
        !          3315: Make the changes in the header files.
        !          3316: 
        !          3317: @item
        !          3318: Use the command @samp{make -t} to mark all the object files as
        !          3319: up to date.  The next time you run @code{make}, the changes in the
        !          3320: header files will not cause any recompilation.
        !          3321: @end enumerate
        !          3322: 
        !          3323: If you have already changed the header file at a time when some files do
        !          3324: need recompilation, it is too late to do this.  Instead, you can use the
        !          3325: @samp{-o @var{file}} flag, which marks a specified file as ``old''
        !          3326: (@pxref{Options}).  This means that the file itself won't be remade,
        !          3327: and nothing else will be remade on its account.  Follow this procedure:
        !          3328: 
        !          3329: @enumerate
        !          3330: @item
        !          3331: Recompile the source files that need compilation for reasons independent
        !          3332: of the particular header file, with @samp{make -o @var{headerfile}}.
        !          3333: If several header files are involved, use a separate @samp{-o} option
        !          3334: for each header file.
        !          3335: 
        !          3336: @item
        !          3337: Touch all the object files with @samp{make -t}.
        !          3338: @end enumerate
        !          3339: 
        !          3340: @node Instead of Execution, Overriding, Avoid Compilation, Running
        !          3341: @section Instead of Executing the Commands
        !          3342: @cindex -t
        !          3343: @cindex touch
        !          3344: @cindex -q
        !          3345: @cindex -n
        !          3346: 
        !          3347: The makefile tells @code{make} how to tell whether a target is up to date,
        !          3348: and how to update each target.  But updating the targets is not always
        !          3349: what you want.  Certain options specify other activities for @code{make}.
        !          3350: 
        !          3351: @table @samp
        !          3352: @item -t
        !          3353: ``Touch''.  The activity is to mark the targets as up to date without
        !          3354: actually changing them.  In other words, @code{make} pretends to compile
        !          3355: the targets but does not really change their contents.
        !          3356: 
        !          3357: @item -n
        !          3358: ``No-op''.  The activity is to print what commands would be used to make
        !          3359: the targets up to date, but not actually execute them.
        !          3360: 
        !          3361: @item -q
        !          3362: ``Question''.  The activity is to find out silently whether the targets
        !          3363: are up to date already; but execute no commands in either case.  In other
        !          3364: words, neither compilation nor output will occur.
        !          3365: @end table
        !          3366: 
        !          3367: With the @samp{-n} flag, @code{make} prints without execution the commands
        !          3368: that it would normally execute.
        !          3369: 
        !          3370: With the @samp{-t} flag, @code{make} ignores the commands in the rules
        !          3371: and uses (in effect) the command @code{touch} for each target that needs to
        !          3372: be remade.  The @code{touch} command is also printed, unless @samp{-s} or
        !          3373: @code{.SILENT} is used.  For speed, @code{make} does not actually invoke
        !          3374: the program @code{touch}.  It does the work directly.
        !          3375: 
        !          3376: With the @samp{-q} flag, @code{make} prints nothing and executes no
        !          3377: commands, but the exit status code it returns is zero if and only if the
        !          3378: targets to be considered are already up to date.
        !          3379: 
        !          3380: It is an error to use more than one of these three flags in the same
        !          3381: invocation of @code{make}.
        !          3382: 
        !          3383: If you are not at all interested in what @code{make} @emph{would} do,
        !          3384: but rather in some other information about @code{make}, there are two
        !          3385: options: the command line @samp{make -p -f /dev/null} will print the
        !          3386: information in @code{make}'s database of variables, rules, directories
        !          3387: and files and @samp{make -v -f /dev/null} will print information about
        !          3388: what version of GNU @code{make} you are using.  @xref{Options}.@refill
        !          3389: 
        !          3390: @node Overriding, Testing, Instead of Execution, Running
        !          3391: @section Overriding Variables
        !          3392: 
        !          3393: You can override the value of a variable using an argument to @code{make}
        !          3394: that contains a @samp{=}.  The argument @samp{@var{v}=@var{x}} (or
        !          3395: @samp{@var{v}:=@var{x}}; @pxref{Flavors}) sets the value of the variable
        !          3396: @var{v} to @var{x}.
        !          3397: 
        !          3398: Values specified this way override all values specified in the makefile
        !          3399: itself; once you have set a variable with a command argument, any ordinary
        !          3400: attempt in the makefile to change that variable is simply ignored.
        !          3401: 
        !          3402: One way to use this facility is to pass extra flags to compilers.
        !          3403: For example, in a properly written makefile, the variable @code{CFLAGS}
        !          3404: is included in each command that runs the C compiler, so a file
        !          3405: @file{foo.c} would be compiled like this:
        !          3406: 
        !          3407: @example
        !          3408: cc -c $(CFLAGS) foo.c
        !          3409: @end example
        !          3410: 
        !          3411: Thus, whatever value you set for @code{CFLAGS} affects each compilation
        !          3412: that occurs.  The makefile probably specifies the usual value for
        !          3413: @code{CFLAGS}, like this:
        !          3414: 
        !          3415: @example
        !          3416: CFLAGS=-g
        !          3417: @end example
        !          3418: 
        !          3419: Each time you run @code{make}, you can override this value and specify a
        !          3420: different value.  For example, if you say @samp{make CFLAGS='-g -O'}, each
        !          3421: C compilation will be done with @samp{cc -c -g -O}.  (This illustrates how
        !          3422: you can enclose spaces and other special characters in the value of a
        !          3423: variable when you override it.)
        !          3424: 
        !          3425: The variable @code{CFLAGS} is only one of many standard variables that
        !          3426: exist just so that you can change them this way.
        !          3427: @xref{Implicit Variables}, for a complete list.
        !          3428: 
        !          3429: You can also program the makefile to look at additional variables of your
        !          3430: own, giving the user ability to control other aspects of how the makefile
        !          3431: works by changing the variables.
        !          3432: 
        !          3433: There is one way that the makefile can change a variable that you have
        !          3434: overridden.  This is to use the @code{override} directive, which is a line
        !          3435: that looks like this: @samp{override @var{variable} = @var{value}}.
        !          3436: @xref{Override Directive}.
        !          3437: 
        !          3438: @node Testing, Options, Overriding, Running
        !          3439: @section Testing the Compilation of a Program
        !          3440: 
        !          3441: Normally, when an error happens in executing a shell command, @code{make}
        !          3442: gives up immediately, returning a nonzero status.  No further commands are
        !          3443: executed for any target.  The error implies that the goal cannot be
        !          3444: correctly remade, and @code{make} reports this as soon as it knows.
        !          3445: 
        !          3446: When you are compiling a program that you have just changed, this is not
        !          3447: what you want.  Instead, you would rather that @code{make} try compiling
        !          3448: every file that can be tried, to show you all the compilation errors.
        !          3449: 
        !          3450: @cindex -k
        !          3451: On these occasions, you should use the @samp{-k} flag.  This tells
        !          3452: @code{make} to continue to consider the other dependencies of the pending
        !          3453: targets, remaking them if necessary, before it gives up and returns nonzero
        !          3454: status.  For example, after an error in compiling one object file,
        !          3455: @samp{make -k} will continue compiling other object files even though it
        !          3456: already knows that linking them will be impossible.  In addition to
        !          3457: contuing after failing shell commands, @samp{make -k} will continue as much
        !          3458: as possible after discovering that it doesn't know how to make a target or
        !          3459: dependency file.  This will always cause an error message, but without
        !          3460: @samp{-k}, it is a fatal error.  @xref{Options}.
        !          3461: 
        !          3462: The usual behavior of @code{make} assumes that your purpose is to get the
        !          3463: goals up to date; once @code{make} learns that this is impossible, it might
        !          3464: as well report the failure immediately.  The @samp{-k} flag says that the
        !          3465: real purpose is to test as much as possible of the changes made in the
        !          3466: program, perhaps to find several independent problems so that you can
        !          3467: correct them all before the next attempt to compile.  This is why Emacs's
        !          3468: @code{compile} command passes the @samp{-k} flag by default.
        !          3469: 
        !          3470: @node Options,, Testing, Running
        !          3471: @section Summary of Options
        !          3472: @cindex options
        !          3473: @cindex flags
        !          3474: 
        !          3475: Here is a table of all the options @code{make} understands:
        !          3476: 
        !          3477: @table @samp
        !          3478: @item -b
        !          3479: @itemx -m
        !          3480: These options are ignored for compatibility with other versions of @code{make}.
        !          3481: 
        !          3482: @item -c @var{dir}
        !          3483: Change to directory @var{dir} before executing the rules.  If multiple
        !          3484: @samp{-c} options are specified, each is interpreted relative to the
        !          3485: previous one: @samp{-c / -c etc} is equivalent to @samp{-c /etc}.
        !          3486: This is typically used with recursive invocations of @code{make}
        !          3487: (@pxref{Recursion}).
        !          3488: 
        !          3489: @item -d
        !          3490: Print debugging information in addition to normal processing.  The
        !          3491: debugging information says which files are being considered for
        !          3492: remaking, which file-times are being compared and with what results,
        !          3493: which files actually need to be remade, which implicit rules are
        !          3494: considered and which are applied---everything interesting about how
        !          3495: @code{make} decides what to do.
        !          3496: 
        !          3497: @item -f @var{file}
        !          3498: Use file @var{file} as a makefile.  @xref{Makefiles}.
        !          3499: 
        !          3500: @item -i
        !          3501: Ignore all errors in commands executed to remake files.
        !          3502: @xref{Errors}.
        !          3503: 
        !          3504: @item -I @var{dir}
        !          3505: Specifies a directory @var{dir} to search for included makefiles.
        !          3506: @xref{Include}.  If several @samp{-I} options are used to specify
        !          3507: several directories, the directories are searched in the order
        !          3508: specified.
        !          3509: 
        !          3510: @item -k
        !          3511: Continue as much as possible after an error.  While the target that
        !          3512: failed, and those that depend on it, cannot be remade, the other
        !          3513: dependencies of these targets can be processed all the same.
        !          3514: @xref{Testing}.
        !          3515: 
        !          3516: @item -n
        !          3517: Print the commands that would be executed, but do not execute them.
        !          3518: @xref{Instead of Execution}.
        !          3519: 
        !          3520: @item -o @var{file}
        !          3521: Do not remake the file @var{file} even if it is older than its
        !          3522: dependencies, and do not remake anything on account of changes in
        !          3523: @var{file}.  Essentially the file is treated as very old and its rules
        !          3524: are ignored.  @xref{Avoid Compilation}.
        !          3525: 
        !          3526: @item -p
        !          3527: Print the data base (rules and variable values) that results from
        !          3528: reading the makefiles; then execute as usual or as otherwise
        !          3529: specified.  This also prints the version information given by
        !          3530: the @samp{-v} switch (see below).  To print the data base without
        !          3531: trying to remake any files, use @samp{make -p -f /dev/null}.
        !          3532: 
        !          3533: @item -q
        !          3534: ``Question mode''.  Do not run any commands, or print anything; just
        !          3535: return an exit status that is zero if the specified targets are
        !          3536: already up to date, nonzero otherwise.  @xref{Instead of Execution}.
        !          3537: 
        !          3538: @item -r
        !          3539: Eliminate use of the built-in implicit rules (@pxref{Implicit}).
        !          3540: Also clear out the default list of suffixes for suffix rules
        !          3541: (@pxref{Suffix Rules}).
        !          3542: 
        !          3543: @item -s
        !          3544: Silent operation; do not print the commands as they are executed.
        !          3545: @xref{Echoing}.
        !          3546: 
        !          3547: @item -S
        !          3548: Cancel the effect of the @samp{-k} option.  This is never necessary
        !          3549: except in a recursive @code{make} where @samp{-k} might be inherited
        !          3550: from the top-level @code{make} via @code{MAKEFLAGS} (@pxref{Recursion})
        !          3551: or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill
        !          3552: 
        !          3553: @item -t
        !          3554: Touch files (mark them up to date without really changing them)
        !          3555: instead of running their commands.  This is used to pretend (to fool
        !          3556: future invocations of @code{make}) that the commands were done.
        !          3557: @xref{Instead of Execution}.
        !          3558: 
        !          3559: @item -v
        !          3560: Print the version of the @code{make} program plus a copyright,
        !          3561: list of authors and notice of (non)warranty (short).
        !          3562: After this information is printed, processing continues normally.
        !          3563: To get the version information without doing anything else,
        !          3564: use @samp{make -v -f /dev/null}.
        !          3565: 
        !          3566: @item -w
        !          3567: Print a message containing the working directory both before and after
        !          3568: executing the makefile; this is useful for tracking down errors from
        !          3569: builds of large directory trees.  @xref{Recursion}.
        !          3570: @end table
        !          3571: 
        !          3572: @node Implicit, Archives, Running, Top
        !          3573: @chapter Using Implicit Rules
        !          3574: @cindex implicit rule
        !          3575: 
        !          3576: Certain standard ways of remaking target files are used very often.  For
        !          3577: example, one customary way to make an object file is from a C source file
        !          3578: using the C compiler, @code{cc}.
        !          3579: 
        !          3580: @dfn{Implicit rules} tell @code{make} how to use customary techniques so
        !          3581: that you don't have to specify them in detail when you want to use them.
        !          3582: For example, there is an implicit rule for C compilation.
        !          3583: 
        !          3584: Implicit rules work based on file names.  For example, C compilation typically
        !          3585: takes a @file{.c} file and makes a @file{.o} file.  So @code{make} applies
        !          3586: the implicit rule when it sees this combination of file-name endings.
        !          3587: 
        !          3588: A chain of implicit rules can apply in sequence; for example, @code{make}
        !          3589: will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file.
        !          3590: @iftex
        !          3591: @xref{Chained Rules}.
        !          3592: @end iftex
        !          3593: 
        !          3594: The built-in implicit rules use several variables in their commands so
        !          3595: that, by changing the values of the variables, you can change the way the
        !          3596: implicit rule works.  For example, the variable @code{CFLAGS} controls the
        !          3597: flags given to the C compiler by the implicit rule for C compilation.
        !          3598: @iftex
        !          3599: @xref{Implicit Variables}.
        !          3600: @end iftex
        !          3601: 
        !          3602: You can define your own implicit rules by writing @dfn{pattern rules}.
        !          3603: @iftex
        !          3604: @xref{Pattern Rules}.
        !          3605: @end iftex
        !          3606: 
        !          3607: @menu
        !          3608: * Using Implicit::       How to use an existing implicit rule
        !          3609:                           to get the commands for updating a file.
        !          3610: 
        !          3611: * Catalogue of Rules::   Catalogue of built-in implicit rules.
        !          3612: 
        !          3613: * Implicit Variables::   By changing certain variables, you can
        !          3614:                           change what the predefined implicit rules do.
        !          3615: 
        !          3616: * Chained Rules::        Using a chain of implicit rules.
        !          3617: 
        !          3618: * Pattern Rules::        Defining new implicit rules.
        !          3619: 
        !          3620: * Search Algorithm::     Precise algorithm for applying implicit rules.
        !          3621: @end menu
        !          3622: 
        !          3623: @node Using Implicit, Catalogue of Rules, Implicit, Implicit
        !          3624: @section Using Implicit Rules
        !          3625: 
        !          3626: To allow @code{make} to find a customary method for updating a target file,
        !          3627: all you have to do is refrain from specifying commands yourself.  Either
        !          3628: write a rule with no command lines, or don't write a rule at all.  Then
        !          3629: @code{make} will figure out which implicit rule to use based on which
        !          3630: kind of source file exists.
        !          3631: 
        !          3632: For example, suppose the makefile looks like this:
        !          3633: 
        !          3634: @example
        !          3635: foo : foo.o bar.o
        !          3636:         cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)
        !          3637: @end example
        !          3638: 
        !          3639: @noindent
        !          3640: Because you mention @file{foo.o} but do not give a rule for it, @code{make}
        !          3641: will automatically look for an implicit rule that tells how to update it.
        !          3642: This happens whether or not the file @file{foo.o} currently exists.
        !          3643: 
        !          3644: If an implicit rule is found, it supplies both commands and a dependency
        !          3645: (the source file).  You would want to write a rule for @file{foo.o} with no
        !          3646: command lines if you need to specify additional dependencies, such as
        !          3647: header files, that the implicit rule cannot supply.
        !          3648: 
        !          3649: Each implicit rule has a target pattern and dependency patterns.  There may
        !          3650: be many implicit rules with the same target pattern.  For example, numerous
        !          3651: rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler;
        !          3652: another, from a @samp{.p} file with the Pascal compiler; and so on.  The rule
        !          3653: that actually applies is the one whose dependency exists or can be made.
        !          3654: 
        !          3655: So, if you have a file @file{foo.c}, @code{make} will run the C compiler;
        !          3656: otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal
        !          3657: compiler; and so on.
        !          3658: 
        !          3659: Of course, when you write the makefile, you know which implicit rule you
        !          3660: want @code{make} to use, and you know it will choose that one because you
        !          3661: know which other files are supposed to exist.  @xref{Catalogue of Rules},
        !          3662: for a catalogue of all the predefined implicit rules.
        !          3663: 
        !          3664: Above, we said an implicit rule applies if the required dependency ``exists
        !          3665: or can be made''.  A file ``can be made'' if it is mentioned explicitly in
        !          3666: the makefile as a target or a dependency, or if an implicit rule can be
        !          3667: recursively found for how to make it.  When the implicit dependency is the
        !          3668: result of another implicit rule, we say that @dfn{chaining} is occurring.
        !          3669: @xref{Chained Rules}.
        !          3670: 
        !          3671: In general, @code{make} searches for an implicit rule for each target, and
        !          3672: for each double-colon rule, that has no commands.  A file that is mentioned
        !          3673: only as a dependency is considered a target whose rule specifies nothing,
        !          3674: so implicit rule search happens for it.  @xref{Search Algorithm}, for the
        !          3675: details of how the search is done.
        !          3676: 
        !          3677: @node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit
        !          3678: @section Catalogue of Implicit Rules
        !          3679: 
        !          3680: Here is a catalogue of predefined implicit rules which are always available
        !          3681: unless the makefile explicitly overrides or cancels them.
        !          3682: (@xref{Canceling Rules}, for information on canceling or overriding an
        !          3683: implicit rule.  The @samp{-r} option cancels all predefined rules.)
        !          3684: 
        !          3685: @table @asis
        !          3686: @item Compiling C programs
        !          3687: @file{@var{n}.o} will be made automatically from @file{@var{n}.c} 
        !          3688: with the command @samp{$(CC) -c $(CFLAGS)}.@refill
        !          3689: 
        !          3690: @item Compiling Pascal programs
        !          3691: @file{@var{n}.o} will be made automatically from @file{@var{n}.p}
        !          3692: with the command @samp{$(PC) -c $(PFLAGS)}.@refill
        !          3693: 
        !          3694: @item Compiling Fortran, EFL and Ratfor programs
        !          3695: @file{@var{n}.o} will be made automatically from @file{@var{n}.e},
        !          3696: @file{@var{n}.r}, @file{@var{n}.F} or @file{@var{n}.f} by running the
        !          3697: Fortran compiler.  The precise command used is as follows:@refill
        !          3698: 
        !          3699: @table @code
        !          3700: @item .e
        !          3701: @samp{$(FC) -c $(EFLAGS)}.
        !          3702: @item .f
        !          3703: @samp{$(FC) -c $(FFLAGS)}.
        !          3704: @item .F
        !          3705: @samp{$(FC) -c $(FFLAGS)}.
        !          3706: @item .r
        !          3707: @samp{$(FC) -c $(RFLAGS)}.
        !          3708: @end table
        !          3709: 
        !          3710: @item Preprocessing Fortran, EFL and Ratfor programs
        !          3711: @file{@var{n}.f} will be made automatically from @file{@var{n}.e},
        !          3712: @file{@var{n}.r} or @file{@var{n}.F}.  This rule runs just the
        !          3713: preprocessor to convert a Ratfor, EFL or preprocessable Fortran
        !          3714: program into a strict Fortran program.  The precise command used is as
        !          3715: follows:@refill
        !          3716: 
        !          3717: @table @code
        !          3718: @item .e
        !          3719: @samp{$(FC) -F $(EFLAGS)}.
        !          3720: @item .F
        !          3721: @samp{$(FC) -F $(FFLAGS)}.
        !          3722: @item .r
        !          3723: @samp{$(FC) -F $(RFLAGS)}.
        !          3724: @end table
        !          3725: 
        !          3726: @item Assembling assembler programs
        !          3727: @file{@var{n}.o} will be made automatically from @file{@var{n}.s} by
        !          3728: running the assembler @code{as}.  The precise command used is
        !          3729: @samp{$(AS) $(ASFLAGS)}.@refill
        !          3730: 
        !          3731: @item Linking a single object file
        !          3732: @file{@var{n}} will be made automatically from @file{@var{n}.o} by
        !          3733: running the linker @code{ld} via the C compiler.  The precise command
        !          3734: used is @samp{$(CC) $(LDFLAGS) @dots{} $(LOADLIBES)}.@refill
        !          3735: 
        !          3736: This rule does the right thing for a simple program with only one source
        !          3737: file.  It will also do the right thing if there are multiple object files
        !          3738: (presumably coming from various other source files), the first of which has
        !          3739: a name matching that of the executable file.  Thus,
        !          3740: 
        !          3741: @example
        !          3742: x: y.o z.o
        !          3743: @end example
        !          3744: 
        !          3745: @noindent
        !          3746: when @file{x.c}, @file{y.c} and @file{z.c} all exist will execute:
        !          3747: 
        !          3748: @example
        !          3749: cc -c x.c -o x.o
        !          3750: cc -c y.c -o y.o
        !          3751: cc -c z.c -o z.o
        !          3752: cc x.o y.o z.o -o x
        !          3753: rm -f x.o
        !          3754: rm -f y.o
        !          3755: rm -f z.o
        !          3756: @end example
        !          3757: 
        !          3758: @noindent
        !          3759: In more complicated cases, you must write an explicit command for linking.
        !          3760: 
        !          3761: @item Yacc for C programs
        !          3762: @file{@var{n}.c} will be made automatically from @file{@var{n}.y} by
        !          3763: running Yacc with the command @samp{$(YACC) $(YFLAGS)}.
        !          3764: 
        !          3765: @item Yacc for Ratfor programs
        !          3766: @file{@var{n}.r} will be made automatically from @file{@var{n}.yr} by
        !          3767: running Yacc with the command @samp{$(YACCR) $(YFLAGS)}.
        !          3768: 
        !          3769: @item Yacc for EFL programs
        !          3770: @file{@var{n}.e} will be made automatically from @file{@var{n}.ye} by
        !          3771: running Yacc with the command @samp{$(YACCE) $(YFLAGS)}.
        !          3772: 
        !          3773: @item Lex for C programs
        !          3774: @file{@var{n}.c} will be made automatically from @file{@var{n}.l} by
        !          3775: by running Lex.  The actual command is @samp{$(LEX) $(LFLAGS)}.
        !          3776: 
        !          3777: @item Lex for Ratfor programs
        !          3778: @file{@var{n}.r} will be made automatically from @file{@var{n}.l} by
        !          3779: by running Lex.  The actual command is @samp{$(LEX) $(LFLAGS)}.
        !          3780: 
        !          3781: The traditional custom of using the same suffix @samp{.l} for all Lex
        !          3782: files regardless of whether they produce C code or Ratfor code makes
        !          3783: it impossible for @code{make} to determine automatically which of the
        !          3784: two languages you are using in any particular case.  If @code{make} is
        !          3785: called upon to remake an object file from a @samp{.l} file, it must
        !          3786: guess which compiler to use.  It will guess the C compiler, because
        !          3787: that is more common.  If you are using Ratfor, make sure @code{make}
        !          3788: knows this by mentioning @file{@var{n}.r} in the makefile.
        !          3789: 
        !          3790: @item RCS
        !          3791: Any file @file{@var{n}} will be extracted if necessary from an RCS
        !          3792: file named either @file{@var{n},v} or @file{RCS/@var{n},v}.  The
        !          3793: precise command used is @samp{$(CO) $(COFLAGS)}.  The variable
        !          3794: @code{CO} has default value @samp{co}.
        !          3795: 
        !          3796: @item SCCS
        !          3797: Any file @file{@var{n}} will be extracted if necessary from an SCCS
        !          3798: file named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}.  The
        !          3799: precise command used is @samp{$(GET) $(GFLAGS)}.
        !          3800: 
        !          3801: We recommend that you avoid the use of SCCS.  RCS is widely held to be
        !          3802: superior, and is also free.  By choosing free software in place of
        !          3803: comparable (or lesser) proprietary software, you support the free software
        !          3804: movement.
        !          3805: @end table
        !          3806: 
        !          3807: @node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit
        !          3808: @section Variables Used by Implicit Rules
        !          3809: @cindex flags for compilers
        !          3810: 
        !          3811: The commands in built-in implicit rules make liberal use of certain
        !          3812: predefined variables.  You can redefine these variables, either in the
        !          3813: makefile or with arguments to @code{make}, to alter how the implicit rules
        !          3814: work without actually redefining them.
        !          3815: 
        !          3816: For example, the command used to compile a C source file actually says
        !          3817: @samp{$(CC) -c $(CFLAGS)}.  The default values of the variables used
        !          3818: are @samp{cc} and nothing, resulting in the command @samp{cc -c}.  By
        !          3819: redefining @samp{$(CC)} to @samp{ncc}, you could cause @samp{ncc} to
        !          3820: be used for all C compilations performed by the implicit rule.  By
        !          3821: redefining @samp{$(CFLAGS)} to be @samp{-g}, you could pass the
        !          3822: @samp{-g} option to each compilation.  @emph{All} implicit rules that
        !          3823: do C compilation use @samp{$(CC)} to get the program name for the
        !          3824: compiler and @emph{all} include @samp{$(CFLAGS)} among the arguments
        !          3825: given to the compiler.@refill
        !          3826: 
        !          3827: The variables used in implicit rules fall into two classes: those that are
        !          3828: names of programs (like @code{CC}) and those that contain arguments for the
        !          3829: programs (like @code{CFLAGS}).  (The ``name of a program'' may also contain
        !          3830: some command arguments, but it must start with an actual executable program
        !          3831: name.)  If a variable value contains more than one argument, separate them
        !          3832: with spaces.
        !          3833: 
        !          3834: Here is a table of variables used as names of programs:
        !          3835: 
        !          3836: @table @code
        !          3837: @item AS
        !          3838: @vindex AS
        !          3839: Program for doing assembly; default @samp{as}.
        !          3840: 
        !          3841: @item CC
        !          3842: @vindex CC
        !          3843: Program for compiling C programs; default @samp{cc}.
        !          3844: 
        !          3845: @item CO
        !          3846: @vindex CO
        !          3847: Program for extracting a file from RCS; default @samp{co}.
        !          3848: 
        !          3849: @item FC
        !          3850: @vindex FC
        !          3851: Program for compiling or preprocessing Fortran, Ratfor,
        !          3852: and EFL programs; default @samp{f77}.
        !          3853: 
        !          3854: @item GET
        !          3855: @vindex GET
        !          3856: Program for extracting a file from SCCS; default @samp{get}.
        !          3857: 
        !          3858: @item LEX
        !          3859: @vindex LEX
        !          3860: Program to use to turn Lex grammars into C programs or Ratfor programs;
        !          3861: default @samp{lex}.
        !          3862: 
        !          3863: @item PC
        !          3864: @vindex PC
        !          3865: Program for compiling Pascal programs; default @samp{pc}.
        !          3866: 
        !          3867: @item YACC
        !          3868: @vindex YACC
        !          3869: Program to use to turn Yacc grammars into C programs; default @samp{yacc}.
        !          3870: 
        !          3871: @item YACCR
        !          3872: @vindex YACCR
        !          3873: Program to use to turn Yacc grammars into Ratfor
        !          3874: programs; default @samp{yacc -r}.
        !          3875: 
        !          3876: @item YACCE
        !          3877: @vindex YACCE
        !          3878: Program to use to turn Yacc grammars into EFL
        !          3879: programs; default @samp{yacc -e}.
        !          3880: 
        !          3881: @item RANLIB
        !          3882: @vindex RANLIB
        !          3883: Program to use to update the symbol-directory of an archive
        !          3884: (the @file{__.SYMDEF} member); default @samp{ranlib}.
        !          3885: @end table
        !          3886: 
        !          3887: Here is a table of variables whose values are additional arguments for the
        !          3888: programs above.  The default values for all of these is the empty string.
        !          3889: 
        !          3890: @table @code
        !          3891: @item ASFLAGS
        !          3892: @vindex ASFLAGS
        !          3893: Extra flags to give to the assembler (when explicitly
        !          3894: invoked on a @samp{.s} file).
        !          3895: 
        !          3896: @item CFLAGS
        !          3897: @vindex CFLAGS
        !          3898: Extra flags to give to the C compiler.
        !          3899: 
        !          3900: @item EFLAGS
        !          3901: @vindex EFLAGS
        !          3902: Extra flags to give to the Fortran compiler for EFL programs.
        !          3903: 
        !          3904: @item FFLAGS
        !          3905: @vindex FFLAGS
        !          3906: Extra flags to give to the Fortran compiler.
        !          3907: 
        !          3908: @item LFLAGS
        !          3909: @vindex LFLAGS
        !          3910: Extra flags to give to Lex.
        !          3911: 
        !          3912: @item LDFLAGS
        !          3913: @vindex LDFLAGS
        !          3914: Extra flags to give to compilers when they are supposed to invoke the
        !          3915: linker, @samp{ld} (actually the value of the variable @code{LD}).
        !          3916: 
        !          3917: @item PFLAGS
        !          3918: @vindex PFLAGS
        !          3919: Extra flags to give to the Pascal compiler.
        !          3920: 
        !          3921: @item RFLAGS
        !          3922: @vindex RFLAGS
        !          3923: Extra flags to give to the Fortran compiler for Ratfor programs.
        !          3924: 
        !          3925: @item YFLAGS
        !          3926: @vindex YFLAGS
        !          3927: Extra flags to give to Yacc.
        !          3928: @end table
        !          3929: 
        !          3930: @node Chained Rules, Pattern Rules, Implicit Variables, Implicit
        !          3931: @section Chains of Implicit Rules
        !          3932: 
        !          3933: @cindex chains of rules
        !          3934: Sometimes a file can be made by a sequence of implicit rules.  For example,
        !          3935: a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running
        !          3936: first Yacc and then @code{cc}.  Such a sequence is called a @dfn{chain}.
        !          3937: 
        !          3938: If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no
        !          3939: special searching is required: @code{make} finds that the object file can
        !          3940: be made by C compilation from @file{@var{n}.c}; later on, when considering
        !          3941: how to make @file{@var{n}.c}, the rule for running Yacc will be
        !          3942: used.  Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are
        !          3943: updated.@refill
        !          3944: 
        !          3945: @cindex intermediate file
        !          3946: However, even if @file{@var{n}.c} does not exist and is not mentioned,
        !          3947: @code{make} knows how to envision it as the missing link between
        !          3948: @file{@var{n}.o} and @file{@var{n}.y}!  In this case, @file{@var{n}.c} is
        !          3949: called an @dfn{intermediate file}.  Once @code{make} has decided to use the
        !          3950: intermediate file, it is entered in the data base as if it had been
        !          3951: mentioned in the makefile, along with the implicit rule that says how to
        !          3952: create it.@refill
        !          3953: 
        !          3954: Intermediate files are remade using their rules just like all other
        !          3955: files.  The difference is that the intermediate file is deleted when
        !          3956: @code{make} is finished.  Therefore, the intermediate file which did
        !          3957: not exist before @code{make} also does not exist after @code{make}.
        !          3958: The deletion is reported to you by printing a @samp{rm -f} command
        !          3959: that shows what @code{make} is doing.  (You can optionally define an
        !          3960: implicit rule so as to preserve certain intermediate files.  You can also
        !          3961: list the target pattern of an implicit rule (such as @samp{%.o}) as a
        !          3962: dependency file of the special target @code{.PRECIOUS} to preserve intermediate
        !          3963: files whose target patterns match that file's name.)@refill
        !          3964: 
        !          3965: A chain can involve more than two implicit rules.  For example, it is
        !          3966: possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS,
        !          3967: Yacc and @code{cc}.  Then both @file{foo.y} and @file{foo.c} are
        !          3968: intermediate files that are deleted at the end.@refill
        !          3969: 
        !          3970: No single implicit rule can appear more than once in a chain.  This means
        !          3971: that @code{make} will not even consider such a ridiculous thing as making
        !          3972: @file{foo} from @file{foo.o.o} by running the linker twice.  This
        !          3973: constraint has the added benefit of preventing any infinite loop in the
        !          3974: search for an implicit rule chain.
        !          3975: 
        !          3976: There are some special implicit rules to optimize certain cases that would
        !          3977: otherwise by handled by rule chains.  For example, making @file{foo} from
        !          3978: @file{foo.c} could be handled by compiling and linking with separate rules,
        !          3979: using @file{foo.o} as an intermediate file.  But what actually happens is
        !          3980: that a special rule for this case does the compilation and linking with a
        !          3981: single @code{cc} command.  The optimized rule is used in preference to the
        !          3982: step-by-step chain because it comes earlier in the ordering of rules.
        !          3983: 
        !          3984: @node Pattern Rules, Last Resort, Chained Rules, Implicit
        !          3985: @section Defining and Redefining Pattern Rules
        !          3986: 
        !          3987: @cindex pattern rule
        !          3988: You define an implicit rule by writing a @dfn{pattern rule}.  A pattern
        !          3989: rule looks like an ordinary rule, except that its target contains the
        !          3990: character @samp{%} (exactly one of them).  The target is considered a
        !          3991: pattern for matching file names; the @samp{%} can match any substring,
        !          3992: while other characters match only themselves.
        !          3993: 
        !          3994: For example, @samp{%.c} as a pattern matches any file name that ends in
        !          3995: @samp{.c}.  @samp{s.%.c} as a pattern matches any file name that starts
        !          3996: with @samp{s.}, ends in @samp{.c} and is at least five characters long.
        !          3997: (There must be at least one character to match the @samp{%}.)  The substring
        !          3998: that the @samp{%} matches is called the @dfn{stem}.@refill
        !          3999: 
        !          4000: A pattern rule must have at least one dependency that uses @samp{%}.
        !          4001: @samp{%} in a dependency of a pattern rule stands for the same stem
        !          4002: that was matched by the @samp{%} in the target.  In order for
        !          4003: the pattern rule to apply, its target pattern must match the file name
        !          4004: under consideration, and its dependency patterns must name files that
        !          4005: exist or can be made.  These files become dependencies of the target.
        !          4006: 
        !          4007: There may also be dependencies that do not use @samp{%}; such a dependency
        !          4008: attaches to every file made by this pattern rule.  These unvarying
        !          4009: dependencies are rarely useful.
        !          4010: 
        !          4011: The order in which pattern rules appear in the makefile is important
        !          4012: because the rules are considered in that order.  Of equally applicable
        !          4013: rules, the first one found is used.  The rules you write take precedence
        !          4014: over those that are built in.  Note, however, that a rule whose
        !          4015: dependencies actually exist or are mentioned always takes priority over a
        !          4016: rule with dependencies that must be made by chaining other implicit rules.
        !          4017: 
        !          4018: @menu
        !          4019: * Examples: Pattern Examples.  Real examples of pattern rule definitions.
        !          4020: 
        !          4021: * Vars: Automatic.             The automatic variables enable the commands
        !          4022:                                 in pattern rules to act on the right files.
        !          4023: 
        !          4024: * Matching: Pattern Match.     Details of how patterns match.
        !          4025: 
        !          4026: * Match-Anything Rules::       Precautions in defining a rules that can
        !          4027:                                 match any target file whatever.
        !          4028: 
        !          4029: * Canceling Rules::           Overriding or canceling built-in rules.
        !          4030: 
        !          4031: * Last Resort::                How to define a last-resort rule
        !          4032:                                 that applies to any target that no other
        !          4033:                                 rule applies to.
        !          4034: 
        !          4035: * Suffix Rules::               The old-fashioned way to define implicit rules.
        !          4036: @end menu
        !          4037: 
        !          4038: @node Pattern Examples, Automatic, Pattern Rules, Pattern Rules
        !          4039: @subsection Pattern Rule Examples
        !          4040: 
        !          4041: Here are some examples of pattern rules actually predefined in
        !          4042: @code{make}.  First, the rule that compiles @samp{.c} files into @samp{.o}
        !          4043: files:@refill
        !          4044: 
        !          4045: @example
        !          4046: %.o : %.c
        !          4047:         $(CC) -c $(CFLAGS) $< -o $@@
        !          4048: @end example
        !          4049: 
        !          4050: @noindent
        !          4051: defines a rule that can make any file @file{@var{x}.o} from
        !          4052: @file{@var{x}.c}.  The command uses the automatic variables @samp{$@@} and
        !          4053: @samp{$<} to substitute the names of the target file and the source file
        !          4054: as they are in each case where the rule apply (@pxref{Automatic}).@refill
        !          4055: 
        !          4056: Here is a second built-in rule:
        !          4057: 
        !          4058: @example
        !          4059: % :: RCS/%,v
        !          4060:         $(CO) $(COFLAGS) $<
        !          4061: @end example
        !          4062: 
        !          4063: @noindent
        !          4064: defines a rule that can make any file @file{@var{x}} whatever from a
        !          4065: corresponding file @file{@var{x},v} in the subdirectory @file{RCS}.  Since
        !          4066: the target is @samp{%}, this rule will apply to any file whatever, provided
        !          4067: the appropriate dependency file exists.  The double colon makes the rule
        !          4068: @dfn{terminal}, which means that its dependency may not be an intermediate
        !          4069: file (@pxref{Match-Anything Rules}).@refill
        !          4070: 
        !          4071: @node Automatic, Pattern Match, Pattern Examples, Pattern Rules
        !          4072: @subsection Automatic Variables
        !          4073: @cindex automatic variables
        !          4074: 
        !          4075: Suppose you are writing a pattern rule to compile a @samp{.c} file into a
        !          4076: @samp{.o} file: how do you write the @samp{cc} command so that it operates
        !          4077: on the right source file name?  You can't write the name in the command,
        !          4078: because the name is different each time the implicit rule is applied.
        !          4079: 
        !          4080: What you do is use a special feature of @code{make}, the @dfn{automatic
        !          4081: variables}.  These variables have values computed afresh for each rule that
        !          4082: is executed, based on the target and dependencies of the rule.  In this
        !          4083: example, you would use @samp{$@@} for the object file name and @samp{$<}
        !          4084: for the source file name.
        !          4085: 
        !          4086: Here is a table of automatic variables:
        !          4087: 
        !          4088: @table @code
        !          4089: @item $@@
        !          4090: The file name of the target of the rule.  If the target is an archive
        !          4091: member, then @samp{$@@} is the name of the archive file.
        !          4092: 
        !          4093: @item $%
        !          4094: The target member name, when the target is an archive member.  For
        !          4095: example, if the target is @file{foo.a(bar.o)} then @samp{$%} is
        !          4096: @file{bar.o} and @samp{$@@} is @file{foo.a}.  @samp{$%} is empty
        !          4097: when the target is not an archive member.
        !          4098: 
        !          4099: @item $<
        !          4100: The name of the first dependency.
        !          4101: 
        !          4102: @item $?
        !          4103: The names of all the dependencies that are newer than the target, with
        !          4104: spaces between them.
        !          4105: 
        !          4106: @item $^
        !          4107: The names of all the dependencies, with spaces between them.
        !          4108: 
        !          4109: @item $*
        !          4110: The stem with which an implicit rule matches (@pxref{Pattern Match}).
        !          4111: If the target is @file{dir/a.foo.b} and the target pattern is
        !          4112: @file{a.%.b} then the stem is @file{dir/foo}.  The stem is useful for
        !          4113: constructing names of related files.@refill
        !          4114: @end table
        !          4115: 
        !          4116: @samp{$?} is useful even in explicit rules when you wish to operate on only
        !          4117: the dependencies that have changed.  For example, suppose that an archive
        !          4118: named @file{lib} is supposed to contain copies of several object files.
        !          4119: This rule copies just the changed object files into the archive:
        !          4120: 
        !          4121: @example
        !          4122: lib: foo.o bar.o lose.o win.o
        !          4123:         ar c lib $?
        !          4124: @end example
        !          4125: 
        !          4126: Of the variables listed above, four have values that are single file names.
        !          4127: These four have variants that get just the file's directory name or just
        !          4128: the file name within the directory.  The variant variables' names are
        !          4129: formed by appending @samp{D} or @samp{F}, respectively.  These variants are
        !          4130: semi-obsolete in GNU @code{make} since the functions @code{dir} and
        !          4131: @code{notdir} can be used to get an equivalent effect (@pxref{Filename
        !          4132: Functions}).  Here is a table of the variants:@refill
        !          4133: 
        !          4134: @table @samp
        !          4135: @item $(@@D)
        !          4136: The directory part of the file name of the target.  If the value of
        !          4137: @samp{$@@} is @file{dir/foo.o} then @samp{$(@@D)} is @file{dir/}.
        !          4138: This value is @file{./} if @samp{$@@} does not contain a slash.
        !          4139: @samp{$(@@D)} is equivalent to @samp{$(dir $@@)}.@refill
        !          4140: 
        !          4141: @item $(@@F)
        !          4142: The file-within-directory part of the file name of the target.  If the
        !          4143: value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is
        !          4144: @file{foo.o}.  @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}.
        !          4145: 
        !          4146: @item $($/)
        !          4147: The same as @code{$(@@F)}, for compatibility with some other versions
        !          4148: of @code{make}.
        !          4149: 
        !          4150: @item $(%D)
        !          4151: @itemx $(%F)
        !          4152: The directory part and the file-within-directory part of the archive
        !          4153: member name.
        !          4154: 
        !          4155: @item $(*D)
        !          4156: @itemx $(*F)
        !          4157: The directory part and the file-within-directory part of the stem;
        !          4158: @file{dir/} in this example.
        !          4159: 
        !          4160: @item $(<D)
        !          4161: @itemx $(<F)
        !          4162: The directory part and the file-within-directory part of the first
        !          4163: implicit dependency.
        !          4164: @end table
        !          4165: 
        !          4166: @node Pattern Match, Match-Anything Rules, Automatic, Pattern Rules
        !          4167: @subsection How Patterns Match
        !          4168: 
        !          4169: @cindex stem
        !          4170: A target pattern is composed of a @samp{%} between a prefix and a suffix,
        !          4171: either of which may be empty.  The pattern matches a file name only if the
        !          4172: file name starts with the prefix and ends with the suffix, without overlap.
        !          4173: The text between the prefix and the suffix is called the @dfn{stem}.  Thus,
        !          4174: when the pattern @samp{%.o} matches the file name @file{test.o}, the stem
        !          4175: is @samp{test}.  The pattern rule dependencies are turned into actual file
        !          4176: names by substituting the stem for the character @samp{%}.  Thus, if in the
        !          4177: same example one of the dependencies is written as @samp{%.c}, it expands
        !          4178: to @samp{test.c}.@refill
        !          4179: 
        !          4180: When the target pattern does not contain a slash (and usually it does not),
        !          4181: directory names in the file names are removed from the file name before it
        !          4182: is compared with the target prefix and suffix.  The directory names, along
        !          4183: with the slash that ends them, are added back to the stem.  Thus,
        !          4184: @samp{e%t} does match the file name @file{src/eat}, with @samp{src/a} as
        !          4185: the stem.  When dependencies are turned into file names, the directories
        !          4186: from the stem are added at the front, while the rest of the stem is
        !          4187: substituted for the @samp{%}.  The stem @samp{src/a} with a dependency
        !          4188: pattern @samp{c%r} gives the file name @file{src/car}.@refill
        !          4189: 
        !          4190: @node Match-Anything Rules, Canceling Rules, Pattern Match, Pattern Rules
        !          4191: @subsection Match-Anything Pattern Rules
        !          4192: 
        !          4193: @cindex match-anything rule
        !          4194: @cindex terminal rule
        !          4195: When a pattern rule's target is just @samp{%}, it matches any filename
        !          4196: whatever.  We call these rules @dfn{match-anything} rules.  They are very
        !          4197: useful, but it can take a lot of time for @code{make} to think about them,
        !          4198: because it must consider every such rule for each file name listed either
        !          4199: as a target or as a dependency.
        !          4200: 
        !          4201: Suppose the makefile mentions @file{foo.c}.  For this target, @code{make}
        !          4202: would have to consider making it by linking an object file @file{foo.c.o},
        !          4203: or by C compilation-and-linking in one step from @file{foo.c.c}, or by
        !          4204: Pascal compilation-and-linking from @file{foo.c.p}, and many other
        !          4205: possibilities.  We know these possibilities are ridiculous since
        !          4206: @file{foo.c} is a C source file, not an executable.@refill
        !          4207: 
        !          4208: If @code{make} did consider these possibilities, it would ultimately reject
        !          4209: them, because files such as @file{foo.c.o}, @file{foo.c.p}, etc. would not
        !          4210: exist.  But these possibilities are so numerous that @code{make} would run
        !          4211: very slowly if it had to consider them.@refill
        !          4212: 
        !          4213: To gain speed, we have put various constraints on the way @code{make}
        !          4214: considers match-anything rules.  There are two different constraints that
        !          4215: can be applied, and each time you define a match-anything rule you must
        !          4216: choose one or the other for that rule.
        !          4217: 
        !          4218: One choice is to mark the match-anything rule as @dfn{terminal} by defining
        !          4219: it with a double colon.  When a rule is terminal, it does not apply
        !          4220: unless its dependencies actually exist.  Dependencies that could be made
        !          4221: with other implicit rules are not good enough.
        !          4222: 
        !          4223: For example, the built-in implicit rules for extracting sources from RCS
        !          4224: and SCCS files are terminal; as a result, if the file @file{foo.c,v} does
        !          4225: not exist, @code{make} will not even consider trying to make it as an
        !          4226: intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}.
        !          4227: RCS and SCCS files are generally ultimate source files, which should not be
        !          4228: remade from any other files; therefore, @code{make} can save time by not
        !          4229: looking for ways to remake them.@refill
        !          4230: 
        !          4231: If you do not mark the match-anything rule as terminal, then it is
        !          4232: nonterminal.  A nonterminal match-anything rule cannot apply to a file name
        !          4233: that indicates a specific type of data.  A file name indicates a specific
        !          4234: type of data if some non-match-anything implicit rule target matches it.
        !          4235: 
        !          4236: For example, the file name @file{foo.c} matches the target for the pattern
        !          4237: rule @samp{%.c : %.y} (the rule to run Yacc).  Regardless of whether this
        !          4238: rule is actually applicable (which happens only if there is a file
        !          4239: @file{foo.y}), the fact that its target matches is enough to prevent
        !          4240: consideration of any nonterminal match-everything rules for the file
        !          4241: @file{foo.c}.  Thus, @code{make} will not even consider trying to make
        !          4242: @file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c},
        !          4243: @file{foo.c.p}, etc.@refill
        !          4244: 
        !          4245: The motivation for this constraint is that nonterminal match-everything
        !          4246: rules are used for making files containing specific types of data (such as
        !          4247: executable files) and a file name with a recognized suffix indicates a
        !          4248: specific different type of data (such as a C source file).
        !          4249: 
        !          4250: Special built-in dummy pattern rules are provided solely to recognize
        !          4251: certain file names so that nonterminal match-everything rules won't be
        !          4252: considered.  These dummy rules have no dependencies and no commands, and
        !          4253: they are ignored for all other purposes.  For example, the built-in
        !          4254: implicit rule
        !          4255: 
        !          4256: @example
        !          4257: %.p :
        !          4258: @end example
        !          4259: 
        !          4260: @noindent
        !          4261: exists to make sure that Pascal source files such as @file{foo.p} match a
        !          4262: specific target pattern and thereby prevent time from being wasted looking
        !          4263: for @file{foo.p.o} or @file{foo.p.c}.
        !          4264: 
        !          4265: @node Canceling Rules,, Match-Anything Rules, Pattern Rules
        !          4266: @subsection Canceling Implicit Rules
        !          4267: 
        !          4268: You can override a built-in implicit rule by defining a new pattern rule
        !          4269: with the same target and dependencies, but different commands.  When the
        !          4270: new rule is defined, the built-in one is replaced.  The new rule's position
        !          4271: in the sequence of implicit rules is determined by where you write the new
        !          4272: rule.
        !          4273: 
        !          4274: You can cancel a built-in implicit rule by defining a pattern rule with the
        !          4275: same target and dependencies, but no commands.  For example, the following
        !          4276: would cancel the rule that runs the assembler:
        !          4277: 
        !          4278: @example
        !          4279: %.o : %.s
        !          4280: @end example
        !          4281: 
        !          4282: @node Last Resort, Suffix Rules, Pattern Rules, Implicit
        !          4283: @section Defining Last-Resort Default Rules
        !          4284: 
        !          4285: @findex .DEFAULT
        !          4286: You can define a last-resort implicit rule by writing a rule for the target
        !          4287: @code{.DEFAULT}.  Such a rule's commands are used for all targets and
        !          4288: dependencies that have no commands of their own and for which no other
        !          4289: implicit rule applies.  Naturally, there is no @code{.DEFAULT} rule unless
        !          4290: you write one.
        !          4291: 
        !          4292: For example, when testing a makefile, you might not care if the source
        !          4293: files contain real data, only that they exist.  Then you might do this:
        !          4294: 
        !          4295: @example
        !          4296: .DEFAULT:
        !          4297:         touch $@@
        !          4298: @end example
        !          4299: 
        !          4300: @noindent
        !          4301: to cause all the source files needed (as dependencies) to be created
        !          4302: silently.
        !          4303: 
        !          4304: @node Suffix Rules, Search Algorithm, Last Resort, Implicit
        !          4305: @section Old-Fashioned Suffix Rules
        !          4306: @cindex suffix rules
        !          4307: 
        !          4308: @dfn{Suffix rules} are the old-fashioned way of defining implicit rules for
        !          4309: @code{make}.  Suffix rules are obsolete because pattern rules are more
        !          4310: general and clearer.  They are supported in GNU @code{make} for
        !          4311: compatibility with old makefiles.  They come in two kinds:
        !          4312: @dfn{double-suffix} and @dfn{single-suffix}.@refill
        !          4313: 
        !          4314: A double-suffix rule is defined by a pair of suffixes: the target suffix
        !          4315: and the source suffix.  It matches any file whose name ends with the target
        !          4316: suffix.  The corresponding implicit dependency is to the file name made by
        !          4317: replacing the target suffix with the source suffix.  A two-suffix rule
        !          4318: whose target and source suffixes are @samp{.o} and @samp{.c} is equivalent
        !          4319: to the pattern rule @samp{%.o : %.c}.
        !          4320: 
        !          4321: A single-suffix rule is defined by a single suffix, which is the source
        !          4322: suffix.  It matches any file name, and the corresponding implicit
        !          4323: dependency name is made by appending the source suffix.  A single-suffix
        !          4324: rule whose source suffix is @samp{.c} is equivalent to the pattern rule
        !          4325: @samp{% : %.c}.
        !          4326: 
        !          4327: Suffix rule definitions are recognized by comparing each rule's target
        !          4328: against a defined list of known suffixes.  When @code{make} sees a rule
        !          4329: whose target is a known suffix, this rule is considered a single-suffix
        !          4330: rule.  When @code{make} sees a rule whose target is two known suffixes
        !          4331: concatenated, this rule is taken as a double-suffix rule.
        !          4332: 
        !          4333: For example, @samp{.c} and @samp{.o} are both on the default list of known
        !          4334: suffixes.  Therefore, if you define a rule whose target is @samp{.c.o},
        !          4335: @code{make} takes it to be a double-suffix rule with source suffix
        !          4336: @samp{.c} and target suffix @samp{.o}.  For example, here is the old
        !          4337: fashioned way to define the rule for compiling a C source:@refill
        !          4338: 
        !          4339: @example
        !          4340: .c.o:
        !          4341:         $(CC) -c $(CFLAGS) -o $@@ $<
        !          4342: @end example
        !          4343: 
        !          4344: @findex .SUFFIXES
        !          4345: The known suffixes are simply the names of the dependencies of the special
        !          4346: target @code{.SUFFIXES}.  You can add your own suffixes by writing a rule
        !          4347: for @code{.SUFFIXES} that adds more dependencies, as in
        !          4348: 
        !          4349: @example
        !          4350: .SUFFIXES: .hack .win
        !          4351: @end example
        !          4352: 
        !          4353: @noindent
        !          4354: which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes.
        !          4355: 
        !          4356: If you wish to eliminate the default known suffixes instead of just adding
        !          4357: to them, write a rule for @code{.SUFFIXES} with no dependencies.  By
        !          4358: special dispensation, this eliminates all existing dependencies of
        !          4359: @code{.SUFFIXES}.  You can then write another rule to add the suffixes you
        !          4360: want.  For example,
        !          4361: 
        !          4362: @example
        !          4363: .SUFFIXES:    # @r{Delete the default suffixes}
        !          4364: .SUFFIXES: .c .o .h   # @r{Define our suffix list}
        !          4365: @end example
        !          4366: 
        !          4367: The @samp{-r} flag causes the default list of suffixes to be empty.
        !          4368: 
        !          4369: @node Search Algorithm,, Last Resort, Implicit
        !          4370: @section Implicit Rule Search Algorithm
        !          4371: 
        !          4372: Here is the procedure @code{make} uses for searching for an implicit rule
        !          4373: for a target @var{t}.  This procedure is followed for each double-colon
        !          4374: rule with no commands, for each target of ordinary rules none of which have
        !          4375: commands, and for each dependency that is not the target of any rule.  It
        !          4376: is also followed recursively for dependencies that come from implicit
        !          4377: rules, in the search for a chain of rules.
        !          4378: 
        !          4379: Suffix rules are not mentioned in this algorithm because suffix rules are
        !          4380: converted to equivalent pattern rules after the makefiles have been read
        !          4381: in.
        !          4382: 
        !          4383: For an archive member target of the form
        !          4384: @samp{@var{archive}(@var{member})}, the following algorithm is run twice,
        !          4385: first using @samp{(@var{member})} as the target @var{t}, and second using
        !          4386: the entire target if the first run found no rule.@refill
        !          4387: 
        !          4388: @enumerate
        !          4389: @item
        !          4390: Split @var{t} into a directory part, called @var{d}, and the rest,
        !          4391: called @var{n}.  For example, if @var{t} is @samp{src/foo.o}, then
        !          4392: @var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill
        !          4393: 
        !          4394: @item
        !          4395: Make a list of the pattern rules whose target matches @var{t} or
        !          4396: @var{n}.  If the target pattern contains a slash, it is matched
        !          4397: against @var{t}; otherwise, against @var{n}.
        !          4398: 
        !          4399: @item
        !          4400: If any rule in that list is @emph{not} a match-anything rule, then
        !          4401: remove all nonterminal match-anything rules from the list.
        !          4402: 
        !          4403: @item
        !          4404: Remove any rules with no dependencies from the list.
        !          4405: 
        !          4406: @item
        !          4407: For each pattern rule in the list:
        !          4408: 
        !          4409: @enumerate
        !          4410: @item
        !          4411: Find the stem @var{s}: the part of @var{t} or @var{n} that the
        !          4412: @samp{%} in the target pattern matches.@refill
        !          4413: 
        !          4414: @item
        !          4415: Compute the dependency names by substituting @var{s} for @samp{%}; if
        !          4416: the target pattern does not contain a slash, @var{d} is appended to
        !          4417: the front of each dependency name.
        !          4418: 
        !          4419: @item
        !          4420: Test whether all the dependencies exist or ought to exist.  (If a
        !          4421: file name mentioned in the makefile as a target or as an explicit
        !          4422: dependency then we say it ought to exist.)
        !          4423: 
        !          4424: If all dependencies exist or ought to exist, then this rule applies.
        !          4425: @end enumerate
        !          4426: 
        !          4427: @item
        !          4428: If no pattern rule has been found so far, try harder.  For
        !          4429: each pattern rule in the list:
        !          4430: 
        !          4431: @enumerate
        !          4432: @item
        !          4433: If the rule is a terminal match-anything rule, ignore it and go
        !          4434: on to the next rule.
        !          4435: 
        !          4436: @item
        !          4437: Compute the dependency names as before.
        !          4438: 
        !          4439: @item
        !          4440: Test whether all the dependencies exist or ought to exist.
        !          4441: 
        !          4442: @item
        !          4443: For each dependency that does not exist, follow this algorithm
        !          4444: recursively to see if the dependency can be made by an implicit
        !          4445: rule.
        !          4446: 
        !          4447: @item
        !          4448: If all dependencies exist, ought to exist, or can be made by
        !          4449: implicit rules, then this rule applies.
        !          4450: @end enumerate
        !          4451: 
        !          4452: @item
        !          4453: If no rule has been found so far, this target cannot be made by an
        !          4454: implicit rule.  Return failure.
        !          4455: 
        !          4456: @item
        !          4457: If no implicit rule applies, the rule for @code{.DEFAULT}, if any,
        !          4458: applies.  In that case, give @var{t} the same commands that
        !          4459: @code{.DEFAULT} has.  Otherwise, there are no commands for @var{t}.
        !          4460: @end enumerate
        !          4461: 
        !          4462: When the commands of a pattern rule are executed for @var{t}, the automatic
        !          4463: variables @samp{$@@}, @samp{$*} and @samp{$<} are set as follows:
        !          4464: 
        !          4465: @table @samp
        !          4466: @item $@@
        !          4467: @var{t}
        !          4468: @item $*
        !          4469: If the target pattern contains a slash, this is @var{s}; otherwise, it
        !          4470: is @var{d}@var{s}.
        !          4471: @item $<
        !          4472: The name of the first dependency that came via the implicit rule.
        !          4473: @end table
        !          4474: 
        !          4475: For @code{.DEFAULT} commands, as for non-implicit commands, @samp{$*}
        !          4476: and @samp{$<} are empty.  @samp{$@@} is @var{t}, as always.
        !          4477: 
        !          4478: @node Archives, Features, Implicit, Top
        !          4479: @chapter Using @code{make} to Update Archive Files
        !          4480: @cindex archive
        !          4481: 
        !          4482: @dfn{Archive files} are files containing named subfiles called
        !          4483: @dfn{members}; they are maintained with the program @code{ar} and their
        !          4484: main use is as subroutine libraries for linking.
        !          4485: 
        !          4486: @menu
        !          4487: * Members: Archive Members.    How to name an archive member
        !          4488:                                as a target or dependency.
        !          4489: * Update: Archive Update.      An implicit rule can update
        !          4490:                                most archive member targets just right.
        !          4491: * Symbols: Archive Symbols.    Another implicit rule runs @code{ranlib}
        !          4492:                                to update the special member @file{__.SYMDEF}.
        !          4493: @end menu
        !          4494: 
        !          4495: @node Archive Members, Archive Update, Archives, Archives
        !          4496: @section Archive Members as Targets
        !          4497: @cindex archive member targets
        !          4498: 
        !          4499: An individual member of an archive file can be used as a target or
        !          4500: dependency in @code{make}.  The archive file must already exist, but the
        !          4501: member need not exist.  You specify the member named @var{member} in
        !          4502: archive file @var{archive} as follows:
        !          4503: 
        !          4504: @example
        !          4505: @var{archive}(@var{member})
        !          4506: @end example
        !          4507: 
        !          4508: @noindent
        !          4509: This construct is available only in targets and dependencies, not in
        !          4510: commands!  Most programs that you might use in commands do not support this
        !          4511: syntax and cannot act directly on archive members.  Only @code{ar} and
        !          4512: other programs specifically designed to operate on archives can do so.
        !          4513: Therefore, valid commands to update an archive member target probably must
        !          4514: use @code{ar}.  For example, this rule says to create a member
        !          4515: @file{hack.o} in archive @file{foolib} by copying the file @file{hack.o}:
        !          4516: 
        !          4517: @example
        !          4518: foolib(hack.o) : hack.o
        !          4519:         ar r foolib hack.o
        !          4520: @end example
        !          4521: 
        !          4522: In fact, nearly all archive member targets are updated in just this way
        !          4523: and there is an implicit rule to do it for you.
        !          4524: 
        !          4525: @node Archive Update, Archive Symbols, Archive Members, Archives
        !          4526: @section Implicit Rule for Archive Member Targets
        !          4527: 
        !          4528: Recall that a target that looks like @file{@var{a}(@var{m})} stands for the
        !          4529: member named @var{m} in the archive file @var{a}.
        !          4530: 
        !          4531: When @code{make} looks for an implicit rule for such a target, as a special
        !          4532: feature it considers implicit rules that match @file{(@var{m})}, as well as
        !          4533: those that match the actual target @file{@var{a}(@var{m})}.
        !          4534: 
        !          4535: This causes one special rule whose target is @file{(%)} to match.  This
        !          4536: rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m}
        !          4537: into the archive.  For example, it will update the archive member target
        !          4538: @file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the
        !          4539: archive @file{foo.a} as a member named @file{bar.o}.
        !          4540: 
        !          4541: When this rule is chained with others, the result is very powerful.  Thus,
        !          4542: @samp{make "foo.a(bar.o)"} in the presence of a file @file{bar.c} is enough
        !          4543: to cause the following commands to be run, even without a makefile:
        !          4544: 
        !          4545: @example
        !          4546: cc -c bar.c -o bar.o
        !          4547: ar r foo.a bar.o
        !          4548: rm -f bar.o
        !          4549: @end example
        !          4550: 
        !          4551: @noindent
        !          4552: Here the file @file{bar.o} has been envisioned as an intermediate file.
        !          4553: 
        !          4554: @node Archive Symbols,, Archive Update, Archives
        !          4555: @subsection Updating Archive Symbol Directories
        !          4556: @cindex __.SYMDEF
        !          4557: 
        !          4558: An archive file that is used as a library usually contains a special member
        !          4559: named @file{__.SYMDEF} that contains a directory of the external symbol
        !          4560: names defined by all the other members.  After you update any other
        !          4561: members, you need to update @file{__.SYMDEF} so that it will summarize the
        !          4562: other members properly.  This is done by running the @code{ranlib} program:
        !          4563: 
        !          4564: @example
        !          4565: ranlib @var{archivefile}
        !          4566: @end example
        !          4567: 
        !          4568: Normally you would put this command in the rule for the archive file,
        !          4569: and make all the members of the archive file dependents of that rule.
        !          4570: For example,
        !          4571: 
        !          4572: @example
        !          4573: libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{}
        !          4574:         ranlib libfoo.a
        !          4575: @end example
        !          4576: 
        !          4577: @noindent
        !          4578: The effect of this is to update archive members @file{x.o}, @file{y.o},
        !          4579: etc., and then update the symbol directory member @file{__.SYMDEF} by
        !          4580: running @code{ranlib}.  The rules for updating the members are not shown
        !          4581: here; most likely you can omit them and use the implicit rule which copies
        !          4582: files into the archive, as described in the preceding section.
        !          4583: 
        !          4584: @node Features, Missing, Archives, Top
        !          4585: @chapter Features of GNU @code{make}
        !          4586: 
        !          4587: Here is a summary of the features of GNU @code{make}, for comparison
        !          4588: with and credit to other versions of @code{make}.  We consider the features
        !          4589: of @code{make} in BSD 4.2 systems as a baseline.
        !          4590: 
        !          4591: Many features come from the version of @code{make} in System V:
        !          4592: 
        !          4593: @itemize @bullet
        !          4594: @item
        !          4595: The @code{VPATH} variable and its special meaning.  @xref{Directory
        !          4596: Search}.  This feature exists in System V @code{make}, but is undocumented.
        !          4597: It is documented in 4.3 BSD @code{make} (which says it mimics System V's
        !          4598: @code{VPATH} feature).@refill
        !          4599: 
        !          4600: @item
        !          4601: Included makefiles.  @xref{Include}.
        !          4602: 
        !          4603: @item
        !          4604: Variables are read from and communicated via the environment.
        !          4605: @xref{Environment}.
        !          4606: 
        !          4607: @item
        !          4608: Options passed through the variable @code{MAKEFLAGS} to recursive
        !          4609: invocations of @code{make}.  @xref{Options/Recursion}.
        !          4610: 
        !          4611: @item
        !          4612: The automatic variable @code{$%} is set to the member name
        !          4613: in an archive reference.  @xref{Automatic}.
        !          4614: 
        !          4615: @item
        !          4616: The automatic variables @code{$@@}, @code{$*}, @code{$<} and @code{$%}
        !          4617: have corresponding forms like @code{$(@@F)} and @code{$(@@D)}.
        !          4618: @xref{Automatic}.@refill
        !          4619: 
        !          4620: @item
        !          4621: Substitution variable references.  @xref{Reference}.
        !          4622: 
        !          4623: @item
        !          4624: The command-line options @samp{-b} and @samp{-m}, accepted and ignored.
        !          4625: 
        !          4626: @item
        !          4627: Execution of recursive commands to run @code{make} via the variable
        !          4628: @code{MAKE} even if @samp{-n}, @samp{-q} or @samp{-t} is specified.
        !          4629: @xref{Recursion}.
        !          4630: 
        !          4631: @item
        !          4632: Support for suffix @samp{.a} in suffix rules.  In GNU @code{make},
        !          4633: this is actually implemented by changing with one pattern rule for
        !          4634: installing members in an archive.  @xref{Chained Rules}.@refill
        !          4635: 
        !          4636: @item
        !          4637: The arrangement of lines and backslash-newline combinations in
        !          4638: commands is retained when the commands are printed, so they appear as
        !          4639: they do in the makefile, except for the stripping of initial
        !          4640: whitespace.
        !          4641: @end itemize
        !          4642: 
        !          4643: Some features were inspired by a version of @code{make} whose identity we
        !          4644: don't recall:
        !          4645: 
        !          4646: @itemize @bullet
        !          4647: @item
        !          4648: Pattern rules using @samp{%}.  @xref{Pattern Rules}.
        !          4649: 
        !          4650: @item
        !          4651: The automatic variable @code{$^} containing a list of all dependencies
        !          4652: of the current target.  @xref{Automatic}.
        !          4653: @end itemize
        !          4654: 
        !          4655: The remaining features are inventions new in GNU @code{make}:
        !          4656: 
        !          4657: @itemize @bullet
        !          4658: @item
        !          4659: The @samp{-v} option to print version and copyright information.
        !          4660: 
        !          4661: @item
        !          4662: Simply-expanded variables.  @xref{Flavors}.
        !          4663: 
        !          4664: @item
        !          4665: Passing command-line variable assignments automatically through the
        !          4666: variable @code{MAKE} to recursive @code{make} invocations.
        !          4667: @xref{Recursion}.
        !          4668: 
        !          4669: @item
        !          4670: The @samp{-c} command option to change directory.  @xref{Options}.
        !          4671: 
        !          4672: @item
        !          4673: Verbatim variable definitions made with @code{define}.  @xref{Defining}.
        !          4674: 
        !          4675: @item
        !          4676: Phony targets declared with the special target @code{.PHONY}.
        !          4677: @xref{Phony Targets}.
        !          4678: 
        !          4679: @item
        !          4680: Text manipulation by calling functions.  @xref{Functions}.
        !          4681: 
        !          4682: @item
        !          4683: The @samp{-o} option to pretend a file's modification-time is old.
        !          4684: @xref{Avoid Compilation}.
        !          4685: 
        !          4686: @item
        !          4687: Conditional execution.  @xref{Conditionals}.
        !          4688: 
        !          4689: @item
        !          4690: Included makefiles never determine the default goal.
        !          4691: 
        !          4692: @item
        !          4693: The included makefile search path.  @xref{Include}.
        !          4694: 
        !          4695: @item
        !          4696: Specifying extra makefiles to read.  @xref{MAKEFILES Variable}.
        !          4697: 
        !          4698: @item
        !          4699: Stripping leading sequences of @samp{./} from file names, so that
        !          4700: @file{./@var{file}} and @file{@var{file}} are considered to be the
        !          4701: same file.
        !          4702: 
        !          4703: @item
        !          4704: Special search method for library dependencies written in the form
        !          4705: @samp{-l@var{name}}.  @xref{Libraries/Search}.
        !          4706: 
        !          4707: @item
        !          4708: Allowing suffixes for suffix rules (@pxref{Suffix Rules}) to contain
        !          4709: any characters.  In other version of @code{make}, they must begin with
        !          4710: @samp{.} and not contain any @samp{/} characters.
        !          4711: 
        !          4712: @item
        !          4713: The variable @code{MAKELEVEL} which keeps track of the current level
        !          4714: of @code{make} recursion.  @xref{Recursion}.
        !          4715: 
        !          4716: @item
        !          4717: Rule chaining and implicit intermediate files.  @xref{Chained Rules}.
        !          4718: 
        !          4719: @item
        !          4720: Static pattern rules.  @xref{Static Pattern}.
        !          4721: 
        !          4722: @item
        !          4723: Selective @code{vpath} search.  @xref{Directory Search}.
        !          4724: 
        !          4725: @item
        !          4726: Recursive variable references.  @xref{Reference}.
        !          4727: @end itemize
        !          4728: 
        !          4729: @node Missing, Concept Index, Features, Top
        !          4730: @chapter Missing Features in GNU @code{make}
        !          4731: 
        !          4732: The @code{make} programs in various other systems support a few features
        !          4733: that are not implemented in GNU @code{make}.
        !          4734: 
        !          4735: @itemize @bullet
        !          4736: @item
        !          4737: A target of the form @samp{@var{file}((@var{entry}))} stands for a member
        !          4738: of archive file @var{file}.  The member is chosen, not by name, but by
        !          4739: being an object file which defines the linker symbol @var{entry}.@refill
        !          4740: 
        !          4741: This feature was not put into GNU @code{make} because of the
        !          4742: nonmodularity of putting knowledge into @code{make} of the internal
        !          4743: format of archive file symbol directories.  @xref{Archive Symbols}.
        !          4744: 
        !          4745: @item
        !          4746: Suffixes (used in suffix rules) that end with the character @samp{~}
        !          4747: have a special meaning; they refer to the SCCS file that corresponds
        !          4748: to the file one would get without the @samp{~}.  For example, the
        !          4749: suffix rule @samp{.c~.o} would make the file @file{@var{n}.o} file from
        !          4750: the SCCS file @file{s.@var{n}.c}.  For complete coverage, a whole
        !          4751: series of such suffix rules is required.  @xref{Suffix Rules}.@refill
        !          4752: 
        !          4753: In GNU @code{make}, this entire series of cases is handled by two
        !          4754: pattern rules for extraction from SCCS, in combination with the
        !          4755: general feature of rule chaining.  @xref{Chained Rules}.
        !          4756: 
        !          4757: @item
        !          4758: In System V @code{make}, the string @samp{$$@@} has the strange meaning
        !          4759: that, in the dependencies of a rule with multiple targets, it stands
        !          4760: for the particular target that is being processed.
        !          4761: 
        !          4762: This is not defined in GNU @code{make} because @samp{$$} should always
        !          4763: stand for an ordinary @samp{$}.
        !          4764: 
        !          4765: It is possible to get this functionality through the use of static pattern
        !          4766: rules (@pxref{Static Pattern}).  The System V @code{make} rule:
        !          4767: 
        !          4768: @example
        !          4769: $(targets): $$@@.o lib.a
        !          4770: @end example
        !          4771: 
        !          4772: @noindent
        !          4773: can be replaced with the GNU @code{make} static pattern rule:
        !          4774: 
        !          4775: @example
        !          4776: $(targets): %: %.o lib.a
        !          4777: @end example
        !          4778: 
        !          4779: @item
        !          4780: In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search
        !          4781: (@pxref{Directory Search}) have their names changed inside command strings.
        !          4782: We feel it is much cleaner to always use automatic variables and thus
        !          4783: obviate the need for this feature.  We are still debating whether to
        !          4784: implement this for the sake of compatibility or to leave it out to avoid
        !          4785: such terrible ugliness.@refill
        !          4786: @end itemize
        !          4787: 
        !          4788: @node Concept Index, Name Index, Missing, Top
        !          4789: @unnumbered Index of Concepts
        !          4790: 
        !          4791: @printindex cp
        !          4792: 
        !          4793: @node Name Index,, Concept Index, Top
        !          4794: @unnumbered Index of Functions, Directives and Variables
        !          4795: 
        !          4796: @printindex fn
        !          4797: 
        !          4798: @contents
        !          4799: @bye

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.