diff options
Diffstat (limited to 'make.texinfo')
| -rw-r--r-- | make.texinfo | 2352 |
1 files changed, 1715 insertions, 637 deletions
diff --git a/make.texinfo b/make.texinfo index b5bfe2c..88450b4 100644 --- a/make.texinfo +++ b/make.texinfo @@ -1,19 +1,26 @@ -\input texinfo @c -*- Texinfo -*- +\input texinfo @c -*- Texinfo -*- @c %**start of header @setfilename make.info @settitle Make @setchapternewpage odd +@smallbook @c %**end of header -@iftex @finalout -@end iftex -@comment Combine the variable and function indices. +@c Combine the variable and function indices: @synindex vr fn +@c !!set edition, date, version here and in *two* additional places. +@c Search for !!set @ifinfo -This file documents the GNU Make utility. +This file documents the GNU Make utility, which determines +automatically which pieces of a large program need to be recompiled, +and issues the commands to recompile them. + +@c !!set edition, date, version +This is Edition 0.30 Beta, last updated 20 December 1991, +of @cite{The GNU Make Manual}, for @code{make}, Version 3.61 Beta. Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc. @@ -29,42 +36,30 @@ notice identical to this one except for the removal of this paragraph @end ignore Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that -the section entitled ``GNU General Public License'' is included exactly as in -the original, and provided that the entire resulting derived work is +manual under the conditions for verbatim copying, provided also that the +section entitled ``GNU General Public License'' is included exactly as +in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the text of the translations of the section -entitled ``GNU General Public License'' must be approved for accuracy by the -Foundation. +entitled ``GNU General Public License'' must be approved for accuracy +by the Foundation. @end ifinfo +@c !!set edition, date, version @titlepage -@sp 10 -@center @titlefont{GNU Make} -@sp 2 -@center A Program for Directing Recompilation -@sp 2 -@center by Richard M. Stallman and Roland McGrath -@sp 3 -@center Edition 0.28 Beta, -@sp 1 -@center last updated 23 September 1991, -@sp 1 -@center for @code{make}, Version 3.61 Beta. +@title GNU Make +@subtitle A Program for Directing Recompilation +@subtitle Edition 0.30 Beta, for @code{make} Version 3.61 Beta. +@subtitle December 1991 +@author by Richard M. Stallman and Roland McGrath @page @vskip 0pt plus 1filll Copyright @copyright{} 1988, 1989, 1990, 1991 Free Software Foundation, Inc. @sp 2 - -This is Edition 0.28 Beta of the @cite{GNU Make Manual}, @* -last updated 23 September 1991, @* -for @code{make} Version 3.61 Beta. - -@sp 2 Published by the Free Software Foundation @* 675 Massachusetts Avenue, @* Cambridge, MA 02139 USA @* @@ -89,65 +84,639 @@ Foundation. @end titlepage @page -@node Top, Overview, , (dir) -@comment node-name, next, previous, up - @ifinfo -The GNU @code{make} utility determines automatically which pieces of a +@node Top, Copying, (dir), (dir) +@top Make + +@c !!set edition, date, version +The GNU @code{make} utility automatically determines which pieces of a large program need to be recompiled, and issues the commands to -recompile them. This manual describes it and contains the following -chapters: +recompile them.@refill + +This is Edition 0.30 Beta of the @cite{GNU Make Manual}, +last updated 20 December 1991, +for @code{make} Version 3.61 Beta.@refill + +This manual describes @code{make} and contains the following chapters:@refill @end ifinfo @menu -* Overview:: Introducing @code{make}. -* Copying:: Copying conditions for GNU @code{make}. -* Bugs:: If you have problems, or think you've found a bug. -* Simple:: A simple example explained. -* Makefiles:: The data base contains rules and variable definitions. -* Rules:: A rule says how and when to remake one file. -* Commands:: A rule contains shell commands that say how to remake. -* Variables:: A variable holds a text string for substitution into rules. -* Conditionals::Makefiles that do one thing or another depending on - variable values. -* Functions:: Functions can do text-processing within @code{make}. - -* Running:: How to run @code{make}; how you can adjust the way - @code{make} uses the makefile. - -* Implicit:: Implicit rules take over if the makefile doesn't say - how a file is to be remade. -* Archives:: How to use @code{make} to update archive files. - -* Features:: GNU @code{make}'s advanced features and how GNU @code{make} - relates to other versions of @code{make}. -* Missing:: Features of other @code{make}s not supported - by GNU @code{make}. - -* Concept Index::Index of cross-references to where concepts are discussed. -* Name Index:: Index of cross-references for names of @code{make}'s - variables, functions, special targets and directives. +* Copying:: GNU GENERAL PUBLIC LICENSE +* Overview:: Introducing @code{make}. +* Introduction:: An introduction to makefiles. +* Makefiles:: Writing Makefiles +* Rules:: Writing Rules +* Commands:: Writing the Commands in Rules +* Using Variables:: How to Use Variables +* Conditionals:: Conditional Parts of Makefiles +* Functions:: Functions for Transforming Text +* Running:: How to Run @code{make} +* Implicit Rules:: Using Implicit Rules +* Archives:: Using @code{make} to Update Archive Files +* Features:: Features of GNU @code{make} +* Missing:: Missing Features of GNU @code{make} +* Complex Makefile:: Complex Makefile +* Concept Index:: Index of Concepts +* Name Index:: Index of Functions, Variables, & Directives + + --- The Detailed Node Listing --- + +Overview of @code{make} + +* Preparing:: Preparing and Running Make +* Reading:: On Reading this Text +* Bugs:: Problems and Bugs + +An Introduction to Makefiles + +* Parts of Makefiles:: The Parts of a Makefile +* Simple Makefile:: A Simple Makefile +* How Make Works:: How @code{make} Processes This Makefile +* Variables Simplify:: Variables Make Makefiles Simpler +* make Deduces:: Letting @code{make} Deduce the Commands +* Combine By Dependency:: Another Style of Makefile +* Cleanup:: Rules for Cleaning the Directory + +Writing Makefiles + +* Makefile Contents:: What makefiles contain. +* Makefile Names:: How to name your makefile. +* Include:: How one makefile can use another makefile. +* MAKEFILES Variable:: The environment can specify extra makefiles. +* Remaking Makefiles:: How makefiles get remade. +* Overriding Makefiles:: How to override part of one makefile + with another makefile. + +Writing Rules + +* Rule Example:: An example explained. +* Rule Syntax:: General syntax explained. +* Wildcards:: Using wildcard characters such as `*'. +* Directory Search:: Searching other directories for source files. +* Phony Targets:: Using a target that isn't a real file's name. +* Force Targets:: You can use a target without commands + or dependencies to mark other + targets as phony. +* Empty Targets:: When only the date matters and the + files are empty. +* Special Targets:: Targets with special built-in meanings. +* Multiple Targets:: When to make use of several targets in a rule. +* Static Pattern:: Static pattern rules apply to multiple targets + and can vary the dependencies according to + the target name. +* Multiple Rules:: How to use several rules with the same target. +* Double-Colon:: How to use a special kind of rule to allow + several independent rules for one target. + +Using Wildcard Characters in File Names + +* Wildcard Examples:: Several examples +* Wildcard Pitfall:: Problems to avoid. +* Wildcard Function:: How to cause wildcard expansion where + it does not normally take place. + +Searching Directories for Dependencies + +* General Search:: Specifying a search path that applies + to every dependency. +* Selective Search:: Specifying a search path + for a specified class of names. +* Commands/Search:: How to write shell commands that work together + with search paths. +* Implicit/Search:: How search paths affect implicit rules. +* Libraries/Search:: Directory search for link libraries. + +Static Pattern Rules + +* Static Usage:: The syntax of static pattern rules. +* Static vs Implicit:: When are they better than implicit rules? + +Writing the Commands in Rules + +* Echoing:: How to control when commands are echoed. +* Execution:: How commands are executed. +* Parallel:: How commands can be executed in parallel. +* Errors:: What happens after a command execution error. +* Interrupts:: What happens when a command is interrupted. +* Recursion:: Invoking @code{make} from makefiles. +* Sequences:: Defining canned sequences of commands. +* Empty Commands:: Defining useful, do-nothing commands. + +Recursive Use of @code{make} + +* MAKE Variable:: The special effects of using @samp{$(MAKE)}. +* Variables/Recursion:: How to communicate variables to a sub-@code{make}. +* Options/Recursion:: How to communicate options to a sub-@code{make}. +* -w Option:: How to use the @samp{-w} option to debug + makefiles with recursive @code{make} commands. + +How to Use Variables + +* Reference:: How to use the value of a variable. +* Flavors:: Variables come in two flavors. +* Advanced:: Advanced features for referencing a variable. +* Values:: All the ways variables get their values. +* Setting:: How to set a variable in the makefile. +* Override Directive:: How to set a variable in the makefile even if + the user has set it with a command argument. +* Defining:: An alternate way to set a variable + to a verbatim string. +* Environment:: Variable values can come from the environment. + +Advanced Features for Reference to Variables + +* Substitution Refs:: Referencing a variable with + substitutions on the value. +* Computed Names:: Computing the name of the variable to refer to. + +Conditional Parts of Makefiles + +* Conditional Example:: Example of a conditional +* Conditional Syntax:: The syntax of conditionals. +* Testing Flags:: Conditionals that test flags. + +Functions for Transforming Text + +* Syntax of Functions:: How to write a function call. +* Text Functions:: General-purpose text manipulation functions. +* Filename Functions:: Functions for manipulating file names. +* Foreach Function:: Repeat some text with controlled variation. +* Origin Function:: Find where a variable got its value. +* Shell Function:: Substitute the output of a shell command. + +How to Run @code{make} + +* Makefile Arguments:: How to specify which makefile to use. +* Goals:: How to use goal arguments to specify which + parts of the makefile to use. +* Instead of Execution:: How to use mode flags to specify what + kind of thing to do with the commands + in the makefile other than simply + execute them. +* Avoiding Compilation:: How to avoid recompiling certain files. +* Overriding:: How to override a variable to specify + an alternate compiler and other things. +* Testing:: How to proceed past some errors, to + test compilation. +* Options Summary:: Summary of Options + +Using Implicit Rules + +* Using Implicit:: How to use an existing implicit rule + to get the commands for updating a file. +* Catalogue of Rules:: A list of built-in implicit rules. +* Implicit Variables:: How to change what predefined rules do. +* Chained Rules:: How to use a chain of implicit rules. +* Pattern Rules:: How to define new implicit rules. +* Last Resort:: How to defining commands for rules + which can't find any. +* Suffix Rules:: The old-fashioned style of implicit rule. +* Search Algorithm:: The precise algorithm for applying + implicit rules. + +Defining and Redefining Pattern Rules + +* Pattern Intro:: An introduction to pattern rules. +* Pattern Examples:: Examples of pattern rules. +* Automatic:: Automatic variables. +* Pattern Match:: How patterns match. +* Match-Anything Rules:: Precautions you should take prior to + defining rules that can match any + target file whatever. +* Canceling Rules:: How to override or cancel built-in rules. + +Using @code{make} to Update Archive Files + +* Archive Members:: Archive members as targets. +* Archive Update:: The implicit rule for archive member targets. + +Implicit Rule for Archive Member Targets + +* Archive Symbols:: How to update archive symbol directories. @end menu +@node Copying, Overview, Top, Top +@unnumbered GNU GENERAL PUBLIC LICENSE +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +675 Mass Ave, Cambridge, MA 02139, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate +@item +This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The ``Program'', below, +refers to any such program or work, and a ``work based on the Program'' +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification''.) Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +@item +You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +@item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. -@node Overview, Copying, Top, Top +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. +This is free software, and you are welcome to redistribute it +under certain conditions; type `show c' for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than @samp{show w} and +@samp{show c}; they could even be mouse-clicks or menu items---whatever +suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here is a sample; alter the names: + +@example +Yoyodyne, Inc., hereby disclaims all copyright +interest in the program `Gnomovision' +(which makes passes at compilers) written +by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end example + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. + +@node Overview, Introduction, Copying, Top @chapter Overview of @code{make} -The purpose of the @code{make} utility is to determine automatically which -pieces of a large program need to be recompiled, and issue the commands to -recompile them. This manual describes the GNU implementation of -@code{make}, which was implemented by Richard Stallman and Roland McGrath. +The @code{make} utility automatically determines which pieces of a +large program need to be recompiled, and issues commands to +recompile them. This manual describes GNU @code{make}, which was +implemented by Richard Stallman and Roland McGrath. Our examples show C programs, since they are most common, but you can use @code{make} with any programming language whose compiler can be run with a -shell command. In fact, @code{make} is not limited to programs. You can +shell command. Indeed, @code{make} is not limited to programs. You can use it to describe any task where some files must be updated automatically from others whenever the others change. +@menu +* Preparing:: Preparing and Running Make +* Reading:: On Reading this Text +* Bugs:: Problems and Bugs +@end menu + +@node Preparing, Reading, Overview, Overview +@ifinfo +@heading Preparing and Running Make +@end ifinfo + To prepare to use @code{make}, you must write a file called the @dfn{makefile} that describes the relationships among files -in your program, and the states the commands for updating each file. -In a program, typically the executable file is updated from object +in your program and provides commands for updating each file. +In a program, typically, the executable file is updated from object files, which are in turn made by compiling source files.@refill Once a suitable makefile exists, each time you change some source files, @@ -163,21 +732,26 @@ uses the makefile data base and the last-modification times of the files to decide which of the files need to be updated. For each of those files, it issues the commands recorded in the data base. -@iftex -Command arguments to @code{make} can be used to control which files should -be recompiled, or how. @xref{Running}. -@end iftex +You can provide command line arguments to @code{make} to control which +files should be recompiled, or how. @xref{Running, ,How to Run @code{make}}. -@node Copying, Bugs, Overview, Top +@node Reading, Bugs, Preparing, Overview +@section On Reading this Text -@include gpl.texinfo +If you are new to @code{make}, or are looking for a general +introduction, read the first few sections of each chapter, skipping the +later sections. In each chapter, the first few sections contain +introductory or general information and the later sections contain +specialized or technical information. The exception is the second +chapter, @cite{An Introduction to Makefiles}, all of which is introductory. +(@xref{Introduction, ,An Introduction to Makefiles}.) -@node Bugs, Simple, Copying, Top -@chapter Problems and Bugs +@node Bugs, , Reading, Overview +@section Problems and Bugs If you have problems with GNU @code{make} or think you've found a bug, -please report it to Roland McGrath; he doesn't promise to do anything -but he might well want to fix it. +please report it to the developers; we cannot promise to do +anything but we might well want to fix it. Before reporting a bug, make sure you've actually found a real bug. Carefully reread the documentation and see if it really says you can do @@ -198,32 +772,112 @@ command @samp{make -v -f /dev/null}.@refill Non-bug suggestions are always welcome as well. If you have questions about things that are unclear in the documentation -or are just obscure features, ask Roland McGrath; he'll be happy to help -you out (but no promises). You can send him electronic mail at Internet -address @samp{roland@@prep.ai.mit.edu} or UUCP path -@samp{mit-eddie!prep.ai.mit.edu!roland}.@refill - -@node Simple, Makefiles, Bugs, Top -@chapter Simple Example of @code{make} - -Suppose we have a text editor consisting of eight C source files and three -header files. We need a makefile to tell @code{make} how to compile and -link the editor. Assume that all the C files include @file{defs.h}, but -only those defining editing commands include @file{commands.h} and only low -level files that change the editor buffer include @file{buffer.h}. +or are just obscure features, contact Roland McGrath; he will try to help +you out, although he may not have the time to fix the problem.@refill + +You can send electronic mail to Roland McGrath either through the +Internet or via UUCP: + +@example +@group +@r{Internet address:} + roland@@prep.ai.mit.edu + +@r{UUCP path:} + mit-eddie!prep.ai.mit.edu!roland +@end group +@end example + +@node Introduction, Makefiles, Overview, Top +@comment node-name, next, previous, up +@chapter An Introduction to Makefiles + +You need a file called a @dfn{makefile} to tell @code{make} what to +do. Most often, the makefile tells @code{make} how to compile and +link a program. + +In this chapter, we will discuss a simple makefile that describes how +to compile and link a text editor which consists of eight C source +files and three header files. The makefile also tells @code{make} how +to remove certain files when asked. To see a more complex example of +a makefile, see @ref{Complex Makefile}. + +When @code{make} recompiles the editor, each changed C source file +must be recompiled. If a header file has changed, each C source file +that includes the header file must be recompiled, to be safe. Each +compilation produces an object file corresponding to the source file. +Finally, if any source file has been recompiled, all the object files, +whether newly made or saved from previous compilations, must be linked +together to produce the new executable editor. + +@menu +* Parts of Makefiles:: The Parts of a Makefile +* Simple Makefile:: A Simple Makefile +* How Make Works:: How @code{make} Processes This Makefile +* Variables Simplify:: Variables Make Makefiles Simpler +* make Deduces:: Letting @code{make} Deduce the Commands +* Combine By Dependency:: Another Style of Makefile +* Cleanup:: Rules for Cleaning the Directory +@end menu + + +@node Parts of Makefiles, Simple Makefile, Introduction, Introduction +@comment node-name, next, previous, up +@section The Parts of a Makefile + +A simple makefile consists of ``rules'' with the following shape: + +@example +@group +@var{target} @dots{} : @var{dependencies} @dots{} + @var{command} + @dots{} + @dots{} +@end group +@end example + +A @dfn{target} is the name of a file that is generated by a program. +Examples of targets are executable or object files, or the name of an +action to carry out, such as @samp{clean}. + +A @dfn{dependency} is a file that is used as input to create the +target. A target often depends on several files. -To recompile the editor, each changed C source file must be recompiled. If -a header file has changed, to be safe each C source file that -includes the header file must be recompiled. Each compilation produces an -object file corresponding to the source file. Finally, if any source file -has been recompiled, all the object files, whether newly made or saved from -previous compilations, must be linked together to produce the new -executable editor. +A @dfn{command} is an action that @code{make} carries out. +A rule may have more than one command, each on its own line. +@emph{Please note:} you need to put a @key{TAB} at the beginning of +every command line! This is an obscurity that catches the unwary. -Here is a straightforward makefile that describes these criteria and says -how to compile and link when the time comes: +Often a command is in a rule with dependencies and serves to create a +target file if any of the dependencies change. However, a command +need not be part of a rule that has dependencies. For example, the +rule containing the delete command associated with the target +@samp{clean} does not have dependencies. + +A @dfn{rule}, then, explains how and when to remake certain files +which are the targets of the particular rule. @code{make} carries out +the commands on the dependencies to create or update the target. A +rule can also explain how and when to carry out an action. +@xref{Rules, , Writing Rules}. + +A makefile may contain other text besides rules, but a simple makefile +need only contain rules. Rules may look somewhat more complicated +than shown in this template, but all fit the pattern more or less. + +@node Simple Makefile, How Make Works, Parts of Makefiles, Introduction +@comment node-name, next, previous, up +@section A Simple Makefile + +Here is a straightforward makefile that describes the way an +executable file called @code{edit} depends on eight object files +which, in turn, depend on eight C source and three header files. + +In this example, all the C files include @file{defs.h}, but only those +defining editing commands include @file{commands.h}, and only low +level files that change the editor buffer include @file{buffer.h}. @example +@group edit : main.o kbd.o commands.o display.o \ insert.o search.o files.o utils.o cc -o edit main.o kbd.o commands.o display.o \ @@ -245,62 +899,108 @@ files.o : files.c defs.h buffer.h command.h cc -c files.c utils.o : utils.c defs.h cc -c utils.c +clean : + rm edit main.o kbd.o commands.o display.o \ + insert.o search.o files.o utils.o +@end group @end example +@noindent We split each long line into two lines using a backslash-newline; this is like using one long line, but is easier to read. -Each file that is generated by a program---that is to say, each file except -for source files---is the @dfn{target} of a @dfn{rule} (@pxref{Rules}). -(In this example, these are the object files such as @file{main.o}, -@file{kbd.o}, etc., and the executable file @file{edit}.) The target -appears at the beginning of a line, followed by a colon. +To use this makefile to create the executable file called @file{edit}, +type: -After the colon come the target's @dfn{dependencies}: all the files that -are used as input when the target file is updated. A target file needs to -be recompiled or relinked if any of its dependencies changes. In addition, -any dependencies that are themselves automatically generated should be -updated first. In this example, @file{edit} depends on each of the eight -object files; the object file @file{main.o} depends on the source file -@file{main.c} and on the header file @file{defs.h}. +@example +make +@end example -By default, @code{make} starts with the first rule (not counting rules -whose target names start with @samp{.}). This is called the @dfn{default -goal}. Therefore, we put the rule for the executable program @file{edit} -first. The other rules are processed because their targets appear as -dependencies of the goal. - -After each line containing a target and dependencies come one or more lines -of shell commands that say how to update the target file. These lines -start with a tab to tell @code{make} that they are command lines. But -@code{make} does not know anything about how the commands work. It is up -to you to supply commands that will update the target file properly. -All @code{make} does is execute the commands you have specified when the -target file needs to be updated. +To use this makefile to delete the executable file and all the object +files from the directory, type: + +@example +make clean +@end example + +In the example makefile, the targets include the executable file +@samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}. The +dependencies are files such as @samp{main.c} and @samp{defs.h}. +Commands include @samp{cc -c main.c} and @samp{cc -c kbd.c}. + +When a target is a file, it needs to be recompiled or relinked if any +of its dependencies changes. In addition, any dependencies that are +themselves automatically generated should be updated first. In this +example, @file{edit} depends on each of the eight object files; the +object file @file{main.o} depends on the source file @file{main.c} and +on the header file @file{defs.h}. +A shell command follows each line that contains a target and +dependencies. These shell commands say how to update the target file. +A @key{TAB} must come at the beginnning of every command line to +distinguish commands lines from other lines in the makefile. (Bear in +mind that @code{make} does not know anything about how the commands +work. It is up to you to supply commands that will update the target +file properly. All @code{make} does is execute the commands you have +specified when the target file needs to be updated.) + +The target @samp{clean} is not a file, but merely the name of an +action; so @code{make} never does anything with it unless you tell it +specifically. (Note that this rule does not have any dependencies. +@xref{Phony Targets, ,Phony Targets}, to see how to prevent a real file called +@file{clean} from causing confusion. @xref{Errors, , Errors in +Commands}, to see how to force @code{rm} to work in spite of errors.) + +@node How Make Works, Variables Simplify, Simple Makefile, Introduction +@comment node-name, next, previous, up @section How @code{make} Processes This Makefile -After reading the makefile, @code{make} begins its real work by processing -the first rule, the one for relinking @file{edit}; but before it can fully -process this rule, it must process the rules for the files @file{edit} -depends on: all the object files. Each of these files is processed -according to its own rule. These rules say to update the @samp{.o} file by -compiling its source file. The recompilation must be done if the source -file, or any of the header files named as dependencies, is more recent than -the object file, or if the object file does not exist. +By default, @code{make} starts with the first rule (not counting rules +whose target names start with @samp{.}). This is called the +@dfn{default goal}. (@dfn{Goals} are the targets that @code{make} +strives ultimately to update. @xref{Goals, , Arguments to Specify the +Goals}.) + +In the simple example, the default goal is to update the executable +program @file{edit}; therefore, we put that rule first. + +Thus, when you give the command: + +@example +make +@end example + +@noindent +@code{make} reads the makefile in the current directory and begins by +processing the first rule. In the example of the simple makefile +shown in the preceding section, this rule is for relinking +@file{edit}; but before @code{make} can fully process this rule, it +must process the rules for the files that @file{edit} depends on, +which in this case are the object files. Each of these files is +processed according to its own rule. These rules say to update each +@samp{.o} file by compiling its source file. The recompilation must +be done if the source file, or any of the header files named as +dependencies, is more recent than the object file, or if the object +file does not exist. + +The other rules are processed because their targets appear as +dependencies of the goal. If another rule does not have any +dependency, it is not processed, unless you tell @code{make} to do so +(with a command such as @code{make clean}). Before recompiling an object file, @code{make} considers updating its dependencies, the source file and header files. This makefile does not specify anything to be done for them---the @samp{.c} and @samp{.h} files -are not the targets of any rules---so nothing needs to be done. But -automatically generated C programs, such as made by Bison or Yacc, would -be updated by their own rules at this time. +are not the targets of any rules---so @code{make} does nothing for +these files. But @code{make} would update +automatically generated C programs, such as those made by Bison or Yacc, +by their own rules at this time. -After recompiling whichever object files need it, @code{make} can now -decide whether to relink @file{edit}. This must be done if the file +After recompiling whichever object files need it, @code{make} +decides whether to relink @file{edit}. This must be done if the file @file{edit} does not exist, or if any of the object files are newer than it. If an object file was just recompiled, it is now newer than -@file{edit}, so @file{edit} will be relinked. +@file{edit}, so @file{edit} is relinked. Thus, if we change the file @file{insert.c} and run @code{make}, @code{make} will compile that file to update @file{insert.o}, and then @@ -308,24 +1008,27 @@ link @file{edit}. If we change the file @file{command.h} and run @code{make}, @code{make} will recompile the object files @file{kbd.o}, @file{commands.o} and @file{files.o} and then link file @file{edit}. +@node Variables Simplify, make Deduces, How Make Works, Introduction @section Variables Make Makefiles Simpler In our example, we had to list all the object files twice in the rule for @file{edit} (repeated here): @example +@group edit : main.o kbd.o commands.o display.o \ insert.o search.o files.o utils.o cc -o edit main.o kbd.o commands.o display.o \ insert.o search.o files.o utils.o +@end group @end example @vindex objects Such duplication is error-prone; if a new object file is added to the system, we might add it to one list and forget the other. We can eliminate -the risk and simplify the makefile by using a @dfn{variable}. Variables +the risk and simplify the makefile by using a variable. @dfn{Variables} allow a text string to be defined once and substituted in multiple places -later (@pxref{Variables}). +later (@pxref{Using Variables, ,How to Use Variables}). It is standard practice for every makefile to have a variable named @code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj} or @@ -333,21 +1036,49 @@ It is standard practice for every makefile to have a variable named such a variable @code{objects} with a line like this in the makefile:@refill @example +@group objects = main.o kbd.o commands.o display.o \ insert.o search.o files.o utils.o +@end group @end example @noindent Then, each place we want to put a list of the object file names, we can substitute the variable's value by writing @samp{$(objects)} -(@pxref{Variables}). Here is how the rule for @code{edit} looks as a -result: +(@pxref{Using Variables, ,How to Use Variables}). + +Here is how the complete simple makefile looks when you use a variable +for the object files: @example +@group +objects = main.o kbd.o commands.o display.o \ + insert.o search.o files.o utils.o + edit : $(objects) cc -o edit $(objects) +main.o : main.c defs.h + cc -c main.c +kbd.o : kbd.c defs.h command.h + cc -c kbd.c +commands.o : command.c defs.h command.h + cc -c commands.c +display.o : display.c defs.h buffer.h + cc -c display.c +insert.o : insert.c defs.h buffer.h + cc -c insert.c +search.o : search.c defs.h buffer.h + cc -c search.c +files.o : files.c defs.h buffer.h command.h + cc -c files.c +utils.o : utils.c defs.h + cc -c utils.c +clean : + rm edit $(objects) +@end group @end example +@node make Deduces, Combine By Dependency, Variables Simplify, Introduction @section Letting @code{make} Deduce the Commands It is not necessary to spell out the commands for compiling the individual @@ -356,7 +1087,7 @@ C source files, because @code{make} can figure them out: it has an named @samp{.c} file using a @samp{cc -c} command. For example, it will use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into @file{main.o}. We can therefore omit the commands from the rules for the -object files. @xref{Implicit}.@refill +object files. @xref{Implicit Rules, ,Using Implicit Rules}.@refill When a @samp{.c} file is used automatically in this way, it is also automatically added to the list of dependencies. We can therefore omit @@ -366,6 +1097,7 @@ Here is the entire example, with both of these changes, and a variable @code{objects} as suggested above: @example +@group objects = main.o kbd.o commands.o display.o \ insert.o search.o files.o utils.o @@ -380,18 +1112,31 @@ insert.o : defs.h buffer.h search.o : defs.h buffer.h files.o : defs.h buffer.h command.h utils.o : defs.h + +.PHONY : clean +clean : + -rm edit $(objects) +@end group @end example @noindent -This is how we would write the makefile in actual practice. +This is how we would write the makefile in actual practice. (The +complications associated with @samp{clean} are described elsewhere. +See @ref{Phony Targets}, and @ref{Errors, ,Errors in Commands}.) +Because implicit rules are so convenient, they are important. You +will see them used frequently.@refill + +@node Combine By Dependency, Cleanup, make Deduces, Introduction @section Another Style of Makefile -Since the rules for the object files specify only dependencies, no -commands, one can alternatively combine them by dependency instead of by -target. Here is what it looks like: +When the objects of a makefile are created only by implicit rules, an +alternative style of makefile is possible. In this style of makefile, +you group entries by their dependencies instead of by their targets. +Here is what one looks like: @example +@group objects = main.o kbd.o commands.o display.o \ insert.o search.o files.o utils.o @@ -401,6 +1146,7 @@ edit : $(objects) $(objects) : defs.h kbd.o commands.o files.o : command.h display.o insert.o search.o files.o : buffer.h +@end group @end example @noindent @@ -412,29 +1158,51 @@ Whether this is better is a matter of taste: it is more compact, but some people dislike it because they find it clearer to put all the information about each target in one place. +@node Cleanup, , Combine By Dependency, Introduction @section Rules for Cleaning the Directory Compiling a program isn't the only thing you might want to write rules for. Makefiles commonly tell how to do a few other things besides -compiling the program: for example, how to delete all the object files -and executables so that the directory is ``clean''. Here is how we -would write a @code{make} rule for cleaning our example editor: +compiling a program: for example, how to delete all the object files +and executables so that the directory is ``clean''. + +Here is how we +could write a @code{make} rule for cleaning our example editor: @example +@group clean: rm edit $(objects) +@end group +@end example + +In practice, we might want to write the rule in a somewhat more +complicated manner to handle unanticipated situations. We would do this: + +@example +@group +.PHONY : clean +clean : + -rm edit $(objects) +@end group @end example @noindent -This rule would be added at the end of the makefile, because we don't -want it to run by default! We want the rule for @code{edit}, which -recompiles the editor, to remain the default goal. +This prevents @code{make} from getting confused by an actual file +called @file{clean} and empowers @code{rm} to continue in spite of errors. +(See @ref{Phony Targets}, and @ref{Errors, ,Errors in Commands}.) + +@noindent +A rule such as this should not be placed at the beginning of the +makefile, because we don't want it to run by default! Thus, in the +example makefile, we want the rule for @code{edit}, which recompiles +the editor, to remain the default goal. Since @code{clean} is not a dependency of @code{edit}, this rule won't run at all if we give the command @samp{make} with no arguments. In order to make the rule run, we have to type @samp{make clean}. -@node Makefiles, Rules, Simple, Top +@node Makefiles, Rules, Introduction, Top @chapter Writing Makefiles @cindex makefile @@ -442,12 +1210,12 @@ The information that tells @code{make} how to recompile a system comes from reading a data base called the @dfn{makefile}. @menu -* Contents: Makefile Contents. Overview of what you put in a makefile. -* Names: Makefile Names. Where @code{make} finds the makefile. -* Include:: How one makefile can use another makefile. -* MAKEFILES Variable:: The environment can specify extra makefiles. -* Remaking Makefiles:: How makefiles get remade. -* Overriding Makefiles:: How to override part of one makefile +* Makefile Contents:: What makefiles contain. +* Makefile Names:: How to name your makefile. +* Include:: How one makefile can use another makefile. +* MAKEFILES Variable:: The environment can specify extra makefiles. +* Remaking Makefiles:: How makefiles get remade. +* Overriding Makefiles:: How to override part of one makefile with another makefile. @end menu @@ -455,7 +1223,7 @@ reading a data base called the @dfn{makefile}. @section What Makefiles Contain Makefiles contain four kinds of things: @dfn{rules}, @dfn{variable -definitions}, @dfn{directives} and @dfn{comments}. Rules, variables and +definitions}, @dfn{directives}, and @dfn{comments}. Rules, variables, and directives are described at length in later chapters.@refill @itemize @bullet @@ -463,14 +1231,15 @@ directives are described at length in later chapters.@refill A rule says when and how to remake one or more files, called the rule's @dfn{targets}. It lists the other files that the targets @dfn{depend on}, and may also give commands to use to create or update the targets. -@xref{Rules}. +@xref{Rules, ,Writing Rules}. @item -A variable definition is a line that specifies a text string value -for a @dfn{variable} that can be substituted into the text later. -The simple makefile example (@pxref{Simple}) shows a variable definition -for @code{objects} as a list of all object files. -@xref{Variables}, for full details. +A variable definition is a line that specifies a text string value for +a @dfn{variable} that can be substituted into the text later. The +simple makefile example (@pxref{Simple Makefile, , A Simple Makefile}) +shows a variable definition for @code{objects} as a list of all object +files. @xref{Using Variables, ,How to Use Variables}, for full +details. @item A directive is a command for @code{make} to do something special while @@ -478,15 +1247,15 @@ reading the makefile. These include: @itemize @bullet @item -Reading another makefile (@pxref{Include}). +Reading another makefile (@pxref{Include, ,Including Other Makefiles}). @item Deciding (based on the values of variables) whether to use or -ignore a part of the makefile (@pxref{Conditionals}). +ignore a part of the makefile (@pxref{Conditionals, ,Conditional Parts of Makefiles}). @item Defining a variable from a verbatim string containing multiple lines -(@pxref{Defining}). +(@pxref{Defining, ,Defining Variables Verbatim}). @end itemize @item @@ -506,8 +1275,10 @@ perhaps spaces before it) is effectively blank, and is ignored.@refill @cindex names of makefiles @cindex default makefile names -By default, when @code{make} looks for the makefile, it tries the names -@file{GNUmakefile}, @file{makefile} and @file{Makefile}, in that order. +@c !!! following paragraph rewritten to avoid overfull hbox +By default, when @code{make} looks for the makefile, it tries the +following names, in order: @file{GNUmakefile}, @file{makefile} +and @file{Makefile}.@refill Normally you should call your makefile either @file{makefile} or @file{Makefile}. (We recommend @file{Makefile} because it appears @@ -521,7 +1292,7 @@ use this name if you have a makefile that is specific to GNU If @code{make} finds none of these names, it does not use any makefile. Then you must specify a goal with a command argument, and @code{make} will attempt to figure out how to remake it using only its built-in -implicit rules. @xref{Implicit}. +implicit rules. @xref{Implicit Rules, ,Using Implicit Rules}. @cindex @code{-f} If you want to use a nonstandard name for your makefile, you can specify @@ -551,7 +1322,7 @@ a command line.) Whitespace is required between @code{include} and @var{filename}; extra whitespace is ignored there and at the end of the directive. A comment starting with @samp{#} is allowed at the end of the line. If @var{filename} contains any variable or function references, they -are expanded. (@xref{Variables}.) +are expanded. @xref{Using Variables, ,How to Use Variables}. When @code{make} processes an @code{include} directive, it suspends reading of the containing makefile and reads from @var{filename} @@ -560,11 +1331,11 @@ makefile in which the directive appears. One occasion for using @code{include} directives is when several programs, handled by individual makefiles in various directories, need to use a -common set of variable definitions (@pxref{Setting}) or pattern rules -(@pxref{Pattern Rules}). +common set of variable definitions (@pxref{Setting, ,Setting Variables}) or pattern rules +(@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}). -Another such occasion is when you want to automatically generate -dependencies from source files; the dependencies can be put in a file that +Another such occasion is when you want to generate +dependencies from source files automatically; the dependencies can be put in a file that is included by the main makefile. This practice is generally cleaner than that of somehow appending the dependencies to the end of the main makefile as has been traditionally done with other versions of @code{make}. @@ -572,7 +1343,7 @@ as has been traditionally done with other versions of @code{make}. If the specified name does not start with a slash, and the file is not found in the current directory, several other directories are searched. First, any directories you have specified with the @samp{-I} option are -searched (@pxref{Options}). Then the following directories (if they +searched (@pxref{Options Summary, ,Summary of Options}). Then the following directories (if they exist) are searched, in this order: @file{/usr/gnu/include}, @file{/usr/local/include}, @file{/usr/include}. If an included makefile cannot be found in any of these directories, a @@ -587,12 +1358,12 @@ If the environment variable @code{MAKEFILES} is defined, @code{make} considers its value as a list of names (separated by whitespace) of additional makefiles to be read before the others. This works much like the @code{include} directive: various directories are searched for those -files (@pxref{Include}). In addition, the default goal is never taken +files (@pxref{Include, ,Including Other Makefiles}). In addition, the default goal is never taken from one of these makefiles and it is not an error if the files listed in @code{MAKEFILES} are not found.@refill The main use of @code{MAKEFILES} is in communication between recursive -invocations of @code{make} (@pxref{Recursion}). It usually isn't +invocations of @code{make} (@pxref{Recursion, ,Recursive Use of @code{make}}). It usually isn't desirable to set the environment variable before a top-level invocation of @code{make}, because it is usually better not to mess with a makefile from outside. However, if you are running @code{make} without a specific @@ -618,7 +1389,7 @@ files. If a makefile can be remade from other files, you probably want To this end, after reading in all makefiles, @code{make} will consider each as a goal target and attempt to update it. If a makefile has a rule which says how to update it (found either in that very makefile or -in another one) or if an implicit rule applies to it (@pxref{Implicit}), +in another one) or if an implicit rule applies to it (@pxref{Implicit Rules, ,Using Implicit Rules}), it will be updated if necessary. After all makefiles have been checked, if any have actually been changed, @code{make} starts with a clean slate and reads all the makefiles over again. (It will also attempt to update @@ -635,7 +1406,7 @@ else. So, to avoid this, @code{make} will @emph{not} attempt to remake makefiles which are specified as targets but have no dependencies.@refill If you do not specify any makefiles to be read with @samp{-f} options, -@code{make} will try the default makefile names; @pxref{Makefile Names}. +@code{make} will try the default makefile names; @pxref{Makefile Names, ,What Name to Give Your Makefile}. Unlike makefiles explicitly requested with @samp{-f} options, @code{make} is not certain that these makefiles should exist. However, if a default makefile does not exist but can be created by running @@ -644,7 +1415,7 @@ makefile can be used. Therefore, if none of the default makefiles exists, @code{make} will try to make each of them in the same order in which they are searched for -(@pxref{Makefile Names}) until it succeeds in making one, or it runs out +(@pxref{Makefile Names, ,What Name to Give Your Makefile}) until it succeeds in making one, or it runs out of names to try. Note that it is not an error if @code{make} cannot find or make any makefile; a makefile is not always necessary.@refill @@ -682,15 +1453,18 @@ However, if the two makefiles give different commands for the same target, @code{make} will not let you just do this. But there is another way. In the containing makefile (the one that wants to include the other), -you can use the @code{.DEFAULT} special target to say that to remake any -target that cannot be made from the information in the containing +you can use the @code{.DEFAULT} special target to say that to remake +any target that cannot be made from the information in the containing makefile, @code{make} should look in another makefile. @xref{Last -Resort}, for more information on @code{.DEFAULT}. +Resort, , Defining Last-Resort Default Rules}, for more information on +@code{.DEFAULT}. For example, if you have a makefile called @file{Makefile} that says how to make the target @samp{foo} (and other targets), you can write a makefile called @file{GNUmakefile} that contains: +@c !!! following is confusing. + @example foo: frobnicate > foo @@ -710,10 +1484,10 @@ will apply the rule. And likewise for any other target that @node Rules, Commands, Makefiles, Top @chapter Writing Rules - @cindex rule @cindex target @cindex dependency + A @dfn{rule} appears in the makefile and says when and how to remake certain files, called the rule's @dfn{targets} (usually only one per rule). It lists the other files that are the @dfn{dependencies} of the target, and @@ -724,39 +1498,37 @@ The order of rules is not significant, except for determining the not otherwise specify one. The default goal is the target of the first rule in the first makefile, except that targets starting with a period do not count unless they contain slashes as well; also, a target that -defines a pattern rule (@pxref{Pattern Rules}) or a suffix rule -(@pxref{Suffix Rules}) has no effect on the default goal. +defines a pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}) or a suffix rule +(@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}) has no effect on the default goal. Therefore, we usually write the makefile so that the first rule is the one for compiling the entire program or all the programs described by -the makefile. @xref{Goals}. +the makefile. @xref{Goals, ,Arguments to Specify the Goals}. @menu -* Rule Example:: An explained example of a rule. -* Rule Syntax:: General syntax of rules, with explanation. - -* Wildcards:: Using wildcard characters like `*' in file names. -* Directory Search:: Searching other directories for source files. - -* Phony Targets:: Using a target that isn't a real file's name. -* Force Targets:: A target without commands or dependencies can - be used to mark other targets as phony. -* Special Targets:: Targets with special built-in meanings. -* Empty Targets:: Real files that are empty--only the date matters. -* Multiple Targets:: When it is useful to have several targets in a rule. -* Static Pattern:: Static pattern rules apply to multiple targets - and can vary the dependencies according to the - target name. -* Multiple Rules:: Using several rules with the same target. -* Double-Colon:: Special kind of rule allowing - several independent rules for one target. -* Commands:: Special features and details of how commands - in a rule are executed. +* Rule Example:: An example explained. +* Rule Syntax:: General syntax explained. +* Wildcards:: Using wildcard characters such as `*'. +* Directory Search:: Searching other directories for source files. +* Phony Targets:: Using a target that isn't a real file's name. +* Force Targets:: You can use a target without commands + or dependencies to mark other + targets as phony. +* Empty Targets:: When only the date matters and the + files are empty. +* Special Targets:: Targets with special built-in meanings. +* Multiple Targets:: When to make use of several targets in a rule. +* Static Pattern:: Static pattern rules apply to multiple targets + and can vary the dependencies according to + the target name. +* Multiple Rules:: How to use several rules with the same target. +* Double-Colon:: How to use a special kind of rule to allow + several independent rules for one target. @end menu @ifinfo @node Rule Example, Rule Syntax, Rules, Rules -@isection Rule Example +@section Rule Example Here is an example of a rule: @@ -793,8 +1565,7 @@ In general, a rule looks like this: @example @var{targets} : @var{dependencies} @var{command} - @var{command} - ... + @dots{} @end example @noindent @@ -803,25 +1574,25 @@ or like this: @example @var{targets} : @var{dependencies} ; @var{command} @var{command} - @var{command} - ... + @dots{} @end example The @var{targets} are file names, separated by spaces. Wild card -characters may be used (@pxref{Wildcards}) and a name of the form -@file{@var{a}(@var{m})} represents member @var{m} in archive file -@var{a} (@pxref{Archive Members}). Usually there is only one target -per rule, but occasionally there is a reason to have more; @xref{Multiple -Targets}.@refill +characters may be used (@pxref{Wildcards, ,Using Wildcard Characters +in File Names}) and a name of the form @file{@var{a}(@var{m})} +represents member @var{m} in archive file @var{a} (@pxref{Archive +Members, ,Archive Members as Targets}). Usually there is only one +target per rule, but occasionally there is a reason to have more; +@xref{Multiple Targets, , Multiple Targets in a Rule}.@refill The @var{command} lines start with a tab character. The first command may appear on the line after the dependencies, with a tab character, or may appear on the same line, with a semicolon. Either way, the effect is the -same. @xref{Commands}. +same. @xref{Commands, ,Writing the Commands in Rules}. Because dollar signs are used to start variable references, if you really want a dollar sign in the rule you must write two of them (@samp{$$}). -@xref{Variables}. You may split a long line by inserting a backslash +@xref{Using Variables, ,How to Use Variables}. You may split a long line by inserting a backslash followed by a newline, but this is not required, as @code{make} places no limit on the length of a line in a makefile. @@ -839,10 +1610,10 @@ file are no longer necessarily valid. How to update is specified by @var{commands}. These are lines to be executed by the shell (normally @samp{sh}), but with some extra features -(@pxref{Commands}). +(@pxref{Commands, ,Writing the Commands in Rules}). @node Wildcards, Directory Search, Rule Syntax, Rules -@section Using Wildcards Characters in File Names +@section Using Wildcard Characters in File Names @cindex wildcard @cindex file name @@ -857,8 +1628,8 @@ The character @samp{~} at the beginning of a file name also has special significance. If alone, or followed by a slash, it represents your home directory. For example @file{~/bin} expands to @file{/home/you/bin}. If the @samp{~} is followed by a word, the string represents the home -directory of the user named by that word. For example @file{~me/bin} -expands to @file{/home/me/bin}.@refill +directory of the user named by that word. For example @file{~john/bin} +expands to @file{/home/john/bin}.@refill Wildcard expansion happens automatically in targets, in dependencies, and in commands. In other contexts, wildcard expansion happens only if you @@ -870,11 +1641,10 @@ specific file whose name consists of @samp{foo}, an asterisk, and @samp{bar}.@refill @menu -* Examples: Wildcard Examples. Some simple examples. -* Pitfall: Wildcard Pitfall. @code{*.o} won't do what you want! -* Function: Wildcard Function. - How to do wildcard expansion when defining a variable - using the function @code{wildcard}. +* Wildcard Examples:: Several examples +* Wildcard Pitfall:: Problems to avoid. +* Wildcard Function:: How to cause wildcard expansion where + it does not normally take place. @end menu @node Wildcard Examples, Wildcard Pitfall, Wildcards, Wildcards @@ -899,7 +1669,7 @@ print: *.c @end example @noindent -This rule uses @file{print} as an empty target file; @pxref{Empty Targets}. +This rule uses @file{print} as an empty target file; @pxref{Empty Targets, ,Empty Target Files to Record Events}. Wildcard expansion does not happen when you define a variable. Thus, if you write this: @@ -943,7 +1713,7 @@ Actually it is possible to obtain the desired result with wildcard expansion, but you need more sophisticated techniques, including the @code{wildcard} function and string substitution. @ifinfo -@xref{Wildcard Function}. +@xref{Wildcard Function, ,The Function @code{wildcard}}. @end ifinfo @iftex These are described in the following section. @@ -982,7 +1752,7 @@ $(subst .c,.o,$(wildcard *.c)) @noindent (Here we have used another function, @code{subst}. -@xref{Text Functions}.)@refill +@xref{Text Functions, ,Functions for String Substitution and Analysis}.)@refill Thus, a makefile to compile all C source files in the directory and then link them together could be written as follows: @@ -997,7 +1767,7 @@ foo : $(objects) @noindent (This takes advantage of the implicit rule for compiling C programs, so there is no need to write explicit rules for compiling the files. -@xref{Flavors}, for an explanation of @samp{:=}, which is a variant of +@xref{Flavors, ,The Two Flavors of Variables}, for an explanation of @samp{:=}, which is a variant of @samp{=}.) @node Directory Search, Phony Targets, Wildcards, Rules @@ -1015,14 +1785,14 @@ to find a dependency. When you redistribute the files among directories, you do not need to change the individual rules, just the search paths. @menu -* General Search:: The @code{VPATH} variable specifies a search path - that applies to every dependency. -* Selective Search:: The @code{vpath} directive specifies a search path - for a specified class of names. -* Commands/Search:: How to write shell commands that work together - with search paths. -* Implicit/Search:: How search paths affect implicit rules. -* Libraries/Search:: Directory search for link libraries. +* General Search:: Specifying a search path that applies + to every dependency. +* Selective Search:: Specifying a search path + for a specified class of names. +* Commands/Search:: How to write shell commands that work together + with search paths. +* Implicit/Search:: How search paths affect implicit rules. +* Libraries/Search:: Directory search for link libraries. @end menu @node General Search, Selective Search, Directory Search, Directory Search @@ -1067,7 +1837,7 @@ is found in the directory @file{src}. @subsection The @code{vpath} Directive Similar to the @code{VPATH} variable but more selective is the @code{vpath} -directive, which allows you to specify a search path for a particular class +directive (note lower case), which allows you to specify a search path for a particular class of filenames, those that match a particular pattern. Thus you can supply certain search directories for one class of filenames and other directories (or none) for other filenames. @@ -1094,7 +1864,9 @@ Clear all search paths previously specified with @code{vpath} directives. A @code{vpath} pattern is a string containing a @samp{%} character. The string must match the filename of a dependency that is being searched for, the @samp{%} character matching any sequence of zero or more characters (as -in pattern rules; @pxref{Pattern Rules}). (If there is no @samp{%}, the +in pattern rules; @pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}). For example, @code{%.h} +matches files that end in @code{.h}. +(If there is no @samp{%}, the pattern must match the dependency, which is not useful very often.) @samp{%} characters in a @code{vpath} directive's pattern can be quoted @@ -1107,8 +1879,9 @@ that are not in danger of quoting @samp{%} characters go unmolested.@refill When a dependency fails to exist in the current directory, if the @var{pattern} in a @code{vpath} directive matches the name of the dependency file, then the @var{directories} in that directive are searched -just like (and before) the directories in the @code{VPATH} variable. For -example, +just like (and before) the directories in the @code{VPATH} variable. + +For example, @example vpath %.h ../headers @@ -1133,7 +1906,7 @@ Therefore, you must write the commands with care so that they will look for the dependency in the directory where @code{make} finds it. This is done with the @dfn{automatic variables} such as @samp{$^} -(@pxref{Automatic}). For instance, the value of @samp{$^} is a +(@pxref{Automatic, ,Automatic Variables}). For instance, the value of @samp{$^} is a list of all the dependencies of the rule, including the names of the directories in which they were found, and the value of @samp{$@@} is the target. Thus:@refill @@ -1144,14 +1917,14 @@ foo.o : foo.c @end example @noindent -The variable @code{CFLAGS} exists so you can specify flags for C +(The variable @code{CFLAGS} exists so you can specify flags for C compilation by implicit rule; we use it here for consistency so it will -affect all C compilations uniformly (@pxref{Implicit Variables}). +affect all C compilations uniformly; @pxref{Implicit Variables, ,Variables Used by Implicit Rules}.) Often the dependencies include header files as well, which you don't want to mention in the commands. The function @code{firstword} can be used to extract just the first dependency from the entire list, as shown here -(@pxref{Filename Functions}): +(@pxref{Filename Functions, ,Functions for File Names}): @example VPATH = src:../headers @@ -1160,16 +1933,17 @@ foo.o : foo.c defs.h hack.h @end example @noindent -Here the value of @samp{$^} would be something like @samp{src/foo.c -../headers/defs.h hack.h}, from which @samp{$(firstword $^)} extracts just -@samp{src/foo.c}.@refill +@c !!! following paragraph rewritten to avoid overfull hbox +In this example, the value of @samp{$^} would be something such as +@samp{src/foo.c ../headers/defs.h hack.h}, from which +@samp{$(firstword $^)} extracts just @samp{src/foo.c}.@refill @node Implicit/Search, Libraries/Search, Commands/Search, Directory Search @subsection Directory Search and Implicit Rules The search through the directories specified in @code{VPATH} or with @code{vpath} happens also during consideration of implicit rules -(@pxref{Implicit}). +(@pxref{Implicit Rules, ,Using Implicit Rules}). For example, when a file @file{foo.o} has no explicit rule, @code{make} considers implicit rules, such as to compile @file{foo.c} if that file @@ -1244,7 +2018,7 @@ named @file{clean} in this directory. Since it has no dependencies, the file @file{clean} would inevitably be considered up to date, and its commands would not be executed. To avoid this problem, you can explicitly declare the target to be phony, using the special target @code{.PHONY} -(@pxref{Special Targets}) as follows: +(@pxref{Special Targets, ,Special Built-in Target Names}) as follows: @example .PHONY : clean @@ -1254,10 +2028,19 @@ declare the target to be phony, using the special target @code{.PHONY} Once this is done, @samp{make clean} will run the commands regardless of whether there is a file named @file{clean}. +Thus, you first write the line that states that @code{clean} is a +phony target, then you write the rule, like this: + +@example +.PHONY: clean +clean: + rm *.o temp +@end example + A phony target should not be a dependency of a real target file; strange things can result from that. As long as you don't do that, the phony target commands will be executed only when the phony target is a specified -goal (@pxref{Goals}). +goal (@pxref{Goals, ,Arguments to Specify the Goals}). Phony targets can have dependencies. When one directory contains multiple programs, it is most convenient to describe all of the programs in one @@ -1353,7 +2136,7 @@ print: foo.c bar.c With this rule, @samp{make print} will execute the @code{lpr} command if either source file has changed since the last @samp{make print}. The automatic variable @samp{$?} is used to print only those files that have -changed (@pxref{Automatic}). +changed (@pxref{Automatic, ,Automatic Variables}). @node Special Targets, Multiple Targets, Empty Targets, Rules @section Special Built-in Target Names @@ -1367,26 +2150,26 @@ The dependencies of the special target @code{.PHONY} are considered to be phony targets. When it is time to consider such a target, @code{make} will run its commands unconditionally, regardless of whether a file with that name exists or what its last-modification -time is. @xref{Phony Targets}. +time is. @xref{Phony Targets, ,Phony Targets}. @item .SUFFIXES The dependencies of the special target @code{.SUFFIXES} are the list of suffixes to be used in checking for suffix rules. @xref{Suffix -Rules}. +Rules, , Old-Fashioned Suffix Rules}. @item .DEFAULT The commands specified for @code{.DEFAULT} are used for any target for which no other commands are known (either explicitly or through an implicit rule). If @code{.DEFAULT} commands are specified, every nonexistent file mentioned as a dependency will have these commands -executed on its behalf. @xref{Search Algorithm}. +executed on its behalf. @xref{Search Algorithm, ,Implicit Rule Search Algorithm}. @item .PRECIOUS @cindex precious targets The targets which @code{.PRECIOUS} depends on are given this special treatment: if @code{make} is killed or interrupted during the execution of their commands, the target is not deleted. -@xref{Interrupts}. +@xref{Interrupts, ,Interrupting or Killing @code{make}}. @item .IGNORE Simply by being mentioned as a target, @code{.IGNORE} says to ignore @@ -1396,7 +2179,7 @@ errors in execution of commands. The dependencies and commands for @samp{.IGNORE} exists for historical compatibility. Since @code{.IGNORE} affects every command in the makefile, it is not very useful; we recommend you use the more selective ways to ignore errors -in specific commands. @xref{Errors}. +in specific commands. @xref{Errors, ,Errors in Commands}. @item .SILENT Simply by being mentioned as a target, @code{.SILENT} says not to @@ -1405,7 +2188,7 @@ for @code{.SILENT} are not meaningful. @samp{.SILENT} exists for historical compatibility. We recommend you use the more selective ways to silence specific commands. -@xref{Echoing}. +@xref{Echoing, ,Command Echoing}. @end table Any defined implicit rule suffix also counts as a special target if it @@ -1415,7 +2198,7 @@ defining implicit rules (but a way still widely used). In principle, any target name could be special in this way if you break it in two and add both pieces to the suffix list. In practice, suffixes normally begin with @samp{.}, so these special target names also begin with @samp{.}. -@xref{Suffix Rules}. +@xref{Suffix Rules, ,Old-Fashioned Suffix Rules}. @node Multiple Targets, Static Pattern, Special Targets, Rules @section Multiple Targets in a Rule @@ -1444,7 +2227,7 @@ mentioned. Similar commands work for all the targets. The commands do not need to be absolutely identical, since the automatic variable @samp{$@@} can be used to substitute the particular target to be remade into the -commands (@pxref{Automatic}). For example: +commands (@pxref{Automatic, ,Automatic Variables}). For example: @example @group @@ -1473,7 +2256,7 @@ types of output, one if given @samp{-big} and one if given Suppose you would like to vary the dependencies according to the target, much as the variable @samp{$@@} allows you to vary the commands. You cannot do this with multiple targets in an ordinary rule, but you can -do it with a @dfn{static pattern rule}. @xref{Static Pattern}. +do it with a @dfn{static pattern rule}. @xref{Static Pattern, ,Static Pattern Rules}. @end ifinfo @node Static Pattern, Multiple Rules, Multiple Targets, Rules @@ -1488,8 +2271,8 @@ targets don't have to have identical dependencies. Their dependencies must be @emph{analogous}, but not necessarily @emph{identical}. @menu -* Usage: Static Usage. How to use static pattern rules. -* Static vs Implicit:: When are they better than implicit rules? +* Static Usage:: The syntax of static pattern rules. +* Static vs Implicit:: When are they better than implicit rules? @end menu @node Static Usage, Static vs Implicit, Static Pattern, Static Pattern @@ -1506,7 +2289,7 @@ Here is the syntax of a static pattern rule: @noindent The @var{targets} gives the list of targets that the rule applies to. The targets can contain wildcard characters, just like the targets of ordinary -rules (@pxref{Wildcards}). +rules (@pxref{Wildcards, ,Using Wildcard Characters in File Names}). The @var{target-pattern} and @var{dep-patterns} say how to compute the dependencies of each target. Each target is matched against the @@ -1532,7 +2315,7 @@ dependency is the same for all targets. backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%} characters can be quoted with more backslashes. Backslashes that quote @samp{%} characters or other backslashes are removed from the pattern -before it is compared file names or has a stem substituted into it. +before it is compared to file names or has a stem substituted into it. Backslashes that are not in danger of quoting @samp{%} characters go unmolested. For example, the pattern @file{the\%weird\\%pattern\\} has @samp{the%weird\} preceding the operative @samp{%} character, and @@ -1552,7 +2335,7 @@ $(objects): %.o: %.c Each target specified must match the target pattern; a warning is issued for each target that does not. If you have a list of files, only some of which will match the pattern, you can use the @code{filter} function to -remove nonmatching filenames (@pxref{Text Functions}): +remove nonmatching filenames (@pxref{Text Functions, ,Functions for String Substitution and Analysis}): @example files = foo.elc bar.o lose.o @@ -1574,7 +2357,7 @@ from @file{foo.el}.@refill @subsection Static Pattern Rules versus Implicit Rules A static pattern rule has much in common with an implicit rule defined as a -pattern rule (@pxref{Pattern Rules}). Both have a pattern for the target +pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}). Both have a pattern for the target and patterns for constructing the names of dependencies. The difference is in how @code{make} decides @emph{when} the rule applies. @@ -1628,7 +2411,7 @@ An extra rule with just dependencies can be used to give a few extra dependencies to many files at once. For example, one usually has a variable named @code{objects} containing a list of all the compiler output files in the system being made. An easy way to say that all of them must -be recompiled if @file{config.h} changes is to write +be recompiled if @file{config.h} changes is to write the following: @example objects = foo.o bar.o @@ -1642,8 +2425,8 @@ say how to make the object files, making it a convenient form to use if you wish to add the additional dependency intermittently. Another wrinkle is that the additional dependencies could be specified with -a variable that you could set with a command argument to @code{make} -(@pxref{Overriding}). For example, +a variable that you set with a command argument to @code{make} +(@pxref{Overriding, ,Overriding Variables}). For example, @example @group @@ -1659,7 +2442,7 @@ will not. If none of the explicit rules for a target has commands, then @code{make} searches for an applicable implicit rule to find some commands. -@xref{Implicit}. +@xref{Implicit Rules, ,Using Implicit Rules}. @node Double-Colon, , Multiple Rules, Rules @section Double-Colon Rules @@ -1689,9 +2472,9 @@ differs depending on which dependency files caused the update, and such cases are rare. Each double-colon rule should specify commands; if it does not, an -implicit rule will be used if one applies. @xref{Implicit}. +implicit rule will be used if one applies. @xref{Implicit Rules, ,Using Implicit Rules}. -@node Commands, Variables, Rules, Top +@node Commands, Using Variables, Rules, Top @chapter Writing the Commands in Rules @cindex commands @@ -1702,25 +2485,23 @@ semicolon in between. Blank lines and lines of just comments may appear among the command lines; they are ignored. Users use many different shell programs, but commands in makefiles are -always interpreted by @file{/bin/sh} unless the makefile specifies otherwise. +always interpreted by @file{/bin/sh} unless the makefile specifies +otherwise. @xref{Execution, ,Command Execution}. +@c !!! for a comment, can a # be followed by a space? --text implies no. Whether comments can be written on command lines, and what syntax they use, is under the control of the shell that is in use. If it is @file{/bin/sh}, a @samp{#} at the start of a word starts a comment. @menu -* Echoing:: Normally commands are echoed before execution, - but you can control this in several ways. -* Execution:: How commands are executed. -* Parallel:: Commands of several rules can be executed in parallel, - to reduce total time. -* Errors:: What happens after an error in command execution. - How to ignore errors in certain commands. -* Interrupts:: If a command is interrupted or killed, - the target may be deleted. -* Recursion:: Invoking @code{make} from commands in makefiles. -* Sequences:: Defining canned sequences of commands. -* Empty Commands::Defining commands that do nothing (but are useful). +* Echoing:: How to control when commands are echoed. +* Execution:: How commands are executed. +* Parallel:: How commands can be executed in parallel. +* Errors:: What happens after a command execution error. +* Interrupts:: What happens when a command is interrupted. +* Recursion:: Invoking @code{make} from makefiles. +* Sequences:: Defining canned sequences of commands. +* Empty Commands:: Defining useful, do-nothing commands. @end menu @node Echoing, Execution, Commands, Commands @@ -1744,7 +2525,7 @@ the makefile: @end example When @code{make} is given the flag @samp{-n}, echoing is all that happens, -no execution. @xref{Options}. In this case and only this case, even the +no execution. @xref{Options Summary, ,Summary of Options}. In this case and only this case, even the commands starting with @samp{@@} are printed. This flag is useful for finding out which commands @code{make} thinks are necessary without actually doing them. @@ -1753,7 +2534,7 @@ actually doing them. @findex .SILENT The @samp{-s} flag to @code{make} prevents all echoing, as if all commands started with @samp{@@}. A rule in the makefile for the special target -@code{.SILENT} has the same effect (@pxref{Special Targets}). +@code{.SILENT} has the same effect (@pxref{Special Targets, ,Special Built-in Target Names}). @code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill @node Execution, Parallel, Echoing, Commands @@ -1765,6 +2546,7 @@ When it is time to execute commands to update a target, they are executed by making a new subshell for each line. (In practice, @code{make} may take shortcuts that do not affect the results.) +@c !!! this is important, should be emphasized This implies that shell commands such as @code{cd} that set variables local to each process will not affect the following command lines. If you want to use @code{cd} to affect the next command, put the two on a single line @@ -1795,12 +2577,12 @@ foo : bar/lose The program used as the shell is taken from the variable @code{SHELL}. By default, the program @file{/bin/sh} is used. -Unlike most variables, the variable @code{SHELL} will not be set from the -environment, except in a recursive @code{make}. This is because the -environment variable @code{SHELL} is used to specify your personal choice -of shell program for interactive use. It would be very bad for personal -choices like this to affect the functioning of makefiles. -@xref{Environment}. +Unlike most variables, the variable @code{SHELL} will not be set from +the environment, except in a recursive @code{make}. This is because the +@code{SHELL} environment variable is used to specify your personal +choice of shell program for interactive use. It would be very bad for +personal choices like this to affect the functioning of makefiles. +@xref{Environment, ,Variables from the Environment}. @node Parallel, Errors, Execution, Commands @section Parallel Execution @@ -1823,12 +2605,13 @@ One unpleasant consequence of running several commands simultaneously is that output from all of the commands comes when the commands send it, so messages from different commands may be interspersed. -Another problem is that two processes cannot both take input from the same -device; so to make sure that only one command tries to take input from the -terminal at once, @code{make} will invalidate the standard input streams of -all but one running command. This means that attempting to read from -standard input, for most child processes if there are several, will usually -be a fatal error (a @samp{Broken pipe} signal). +Another problem is that two processes cannot both take input from the +same device; so to make sure that only one command tries to take input +from the terminal at once, @code{make} will invalidate the standard +input streams of all but one running command. This means that +attempting to read from standard input will usually be a fatal error (a +@samp{Broken pipe} signal) for most child processes if there are +several. It is unpredictable which command will have a valid standard input stream (which will come from the terminal, or wherever you redirect the standard @@ -1843,12 +2626,12 @@ if you are not using this feature, then standard input works normally in all commands. If a command fails (is killed by a signal or exits with a nonzero -status), and errors are not ignored for that command (@pxref{Errors}), +status), and errors are not ignored for that command (@pxref{Errors, ,Errors in Commands}), the remaining command lines to remake the same target will not be run. If a command fails and the @samp{-k} option was not given -(@pxref{Options}), @code{make} aborts execution. If make terminates for -any reason (including a signal) with child processes running, it waits -for them to finish before actually exiting.@refill +(@pxref{Options Summary, ,Summary of Options}), @code{make} aborts execution. If make +terminates for any reason (including a signal) with child processes +running, it waits for them to finish before actually exiting.@refill When the system is heavily loaded, you will probably want to run fewer jobs than when it is lightly loaded. You can use the @samp{-l} option to tell @@ -1877,8 +2660,9 @@ By default, there is no load limit. @cindex error (in commands) After each shell command returns, @code{make} looks at its exit status. -If the command completed successfully, the next command line is executed in -a new shell, or after the last command line is executed, the rule is finished. +If the command completed successfully, the next command line is executed +in a new shell; after the last command line is finished, the rule is +finished. If there is an error (the exit status is nonzero), @code{make} gives up on the current rule, and perhaps on all rules. @@ -1891,24 +2675,29 @@ report an error, but you probably want @code{make} to continue regardless. @cindex - (in commands) To ignore errors in a command line, write a @samp{-} at the beginning of the line's text (after the initial tab). The @samp{-} is discarded before -the command is passed to the shell for execution. For example, +the command is passed to the shell for execution. + +For example, @example clean: -rm -f *.o @end example +@noindent +This causes @code{rm} to continue even if it us unable to remove a file. + @cindex @code{-i} @findex .IGNORE -When @code{make} is run with the @samp{-i} flag, errors are ignored in +When you run @code{make} with the @samp{-i} flag, errors are ignored in all commands of all rules. A rule in the makefile for the special target @code{.IGNORE} has the same effect. These ways of ignoring errors are obsolete because @samp{-} is more flexible. When errors are to be ignored, because of either a @samp{-} or the @samp{-i} flag, @code{make} treats an error return just like success, -except that it prints out a message telling you the status code the -command exited with and saying that the error has been ignored. +except that it prints out a message that tells you the status code +the command exited with, and says that the error has been ignored. When an error happens that @code{make} has not been told to ignore, it implies that the current target cannot be correctly remade, and neither @@ -1922,15 +2711,16 @@ continues to consider the other dependencies of the pending targets, remaking them if necessary, before it gives up and returns nonzero status. For example, after an error in compiling one object file, @samp{make -k} will continue compiling other object files even though it already knows -that linking them will be impossible. @xref{Options}. +that linking them will be impossible. @xref{Options Summary, ,Summary of Options}. The usual behavior assumes that your purpose is to get the specified targets up to date; once @code{make} learns that this is impossible, it might as well report the failure immediately. The @samp{-k} option says -that the real purpose is to test as much as possible of the changes made in -the program, perhaps to find several independent problems so that you can -correct them all before the next attempt to compile. This is why Emacs's -@code{compile} command passes the @samp{-k} flag by default. +that the real purpose is to test as many of the changes made in the +program as possible, perhaps to find several independent problems so +that you can correct them all before the next attempt to compile. This +is why Emacs's @code{compile} command passes the @samp{-k} flag by +default. @node Interrupts, Recursion, Errors, Commands @section Interrupting or Killing @code{make} @@ -1981,7 +2771,7 @@ subsystem: @end example @noindent -or, equivalently, this (@pxref{Options}): +or, equivalently, this (@pxref{Options Summary, ,Summary of Options}): @example subsystem: @@ -1993,11 +2783,11 @@ but there are many things to know about how they work and why, and about how the sub-@code{make} relates to the top-level @code{make}. @menu -* MAKE Variable:: Special effects of using @samp{$(MAKE)}. -* Variables/Recursion:: How variables are communicated to a sub-@code{make}. -* Options/Recursion:: How options are communicated to a sub-@code{make}. -* -w Option:: The @samp{-w} option facilitates debugging - makefiles with recursive @code{make} commands. +* MAKE Variable:: The special effects of using @samp{$(MAKE)}. +* Variables/Recursion:: How to communicate variables to a sub-@code{make}. +* Options/Recursion:: How to communicate options to a sub-@code{make}. +* -w Option:: How to use the @samp{-w} option to debug + makefiles with recursive @code{make} commands. @end menu @node MAKE Variable, Variables/Recursion, Recursion, Recursion @@ -2025,20 +2815,24 @@ sub-@code{make} is run with @samp{cd subdir; /bin/make CFLAGS=-O}.@refill As a special feature, using the variable @code{MAKE} in the commands of a rule alters the effects of the @samp{-t}, @samp{-n} or @samp{-q} option. -(@xref{Instead of Execution}.)@refill - -Consider the command @samp{make -t} in the above example. Following the -usual definition of @samp{-t}, this would create a file named -@file{subsystem} and do nothing else. What you really want it to do is run -@samp{cd subdir; make -t}; but that would require executing the command, -and @samp{-t} says not to execute commands.@refill +(@xref{Instead of Execution, ,Instead of Executing the Commands}.)@refill + +@c !!! check whether the following is correct. +Consider the command @samp{make -t} in the above example. (The +@samp{make -t} option marks targets as up to date without actually +doing anything.) Following the usual +definition of @samp{-t}, a @samp{make -t} command in the example would +create a file named @file{subsystem} and do nothing else. What you +really want it to do is run @samp{cd subdir; make -t}; but that would +require executing the command, and @samp{-t} says not to execute +commands.@refill The special feature makes this do what you want: whenever a rule's commands use the variable @code{MAKE}, the flags @samp{-t}, @samp{-n} or @samp{-q} do not apply to that rule. The commands of that rule are executed normally despite the presence of a flag that causes most commands not to be run. The usual @code{MAKEFLAGS} mechanism passes the flags to the -sub-@code{make} (@pxref{Options/Recursion}), so your request to touch the +sub-@code{make} (@pxref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}), so your request to touch the files, or print the commands, is propagated to the subsystem.@refill @node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion @@ -2056,13 +2850,13 @@ variable names consisting of characters other than letters, numbers, and underscores. Variable are @emph{not} passed down if they were created by default by -@code{make} (@pxref{Implicit Variables}). The sub-@code{make} will +@code{make} (@pxref{Implicit Variables, ,Variables Used by Implicit Rules}). The sub-@code{make} will define these for itself.@refill The way this works is that @code{make} adds each variable and its value to the environment for running each command. The sub-@code{make}, in turn, uses the environment to initialize its table of variable values. -@xref{Environment}. +@xref{Environment, ,Variables from the Environment}. @vindex MAKELEVEL As a special feature, the variable @code{MAKELEVEL} is changed when it is @@ -2073,7 +2867,7 @@ sub-sub-@code{make}, and so on. The incrementation happens when @code{make} sets up the environment for a command.@refill The main use of @code{MAKELEVEL} is to test it in a conditional directive -(@pxref{Conditionals}); this way you can write a makefile that behaves one +(@pxref{Conditionals, ,Conditional Parts of Makefiles}); this way you can write a makefile that behaves one way if run recursively and another way if run directly by you. @vindex MAKEFILES @@ -2082,7 +2876,7 @@ commands to use additional makefiles. The value of @code{MAKEFILES} is a whitespace-separated list of filenames. This variable, if defined in the outer-level makefile, is passed down through the environment as usual; then it serves as a list of extra makefiles for the sub-@code{make} to read -before the usual or specified ones. @xref{MAKEFILES Variable}. +before the usual or specified ones. @xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}. @node Options/Recursion, -w Option, Variables/Recursion, Recursion @subsection Communicating Options to a Sub-@code{make} @@ -2097,12 +2891,12 @@ set up automatically by @code{make} to contain the flag letters that As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS} in its environment. In response, it takes the flags from that value and -processes them as if they had been given as arguments. @xref{Options}. +processes them as if they had been given as arguments. @xref{Options Summary, ,Summary of Options}. The options @samp{-C}, @samp{-f}, @samp{-I}, @samp{-o}, and @samp{-W} are not put into @code{MAKEFLAGS}; these options are not passed down.@refill -The @samp{-j} (@pxref{Parallel}) option is a special case. If you set +The @samp{-j} option is a special case (@pxref{Parallel, ,Parallel Execution}). If you set it to some numeric value, @samp{-j 1} is always put into @code{MAKEFLAGS} instead of the value you specified. This is because if the @samp{-j} option were passed down to sub-@code{make}s, you would get @@ -2146,7 +2940,7 @@ but now @code{MAKEFLAGS} makes this usage redundant. @cindex setting options in makefiles @cindex options, setting in makefiles The @code{MAKEFLAGS} and @code{MFLAGS} variables can also be useful if you -want to have certain options, such as @samp{-k} (@pxref{Options}) set each +want to have certain options, such as @samp{-k} (@pxref{Options Summary, ,Summary of Options}) set each time you run @code{make}. Just put @samp{MAKEFLAGS=k} or @samp{MFLAGS=-k} in your environment. These variables may also be set in makefiles, so a makefile can specify additional flags that should also be in effect for @@ -2209,7 +3003,7 @@ Here @code{run-yacc} is the name of the variable being defined; commands. The @code{define} directive does not expand variable references and function calls in the canned sequence; the @samp{$} characters, parentheses, variable names, and so on, all become part of the value of the -variable you are defining. @xref{Defining}, for a complete explanation of +variable you are defining. @xref{Defining, ,Defining Variables Verbatim}, for a complete explanation of @code{define}. The first command in this example runs Yacc on the first dependency (of @@ -2218,7 +3012,7 @@ always named @file{y.tab.c}. The second command moves the output to the rule's target file name. To use the canned sequence, substitute the variable into the commands of a -rule. You can substitute it like any other variable (@pxref{Reference}). +rule. You can substitute it like any other variable (@pxref{Reference, ,Basics of Variable References}). Because variables defined by @code{define} are recursively expanded variables, all the variable references you wrote inside the @code{define} are expanded now. For example: @@ -2234,7 +3028,7 @@ foo.c : foo.y This is a realistic example, but this particular one is not needed in practice because @code{make} has an implicit rule to figure out these -commands based on the file names involved. @xref{Implicit}. +commands based on the file names involved. @xref{Implicit Rules, ,Using Implicit Rules}. @node Empty Commands, , Sequences, Commands @section Defining Empty Commands @@ -2253,18 +3047,19 @@ defines an empty command string for @file{target}. You could also use a line beginning with a tab character to define an empty command string, but this would be confusing because such a line looks empty. -You may be wondering why you would want to define a command string that -does nothing. The only reason this is useful is to prevent a target -from getting implicit commands (from implicit rules or the -@code{.DEFAULT} special target; @pxref{Implicit} and @pxref{Last Resort}). +You may be wondering why you would want to define a command string +that does nothing. The only reason this is useful is to prevent a +target from getting implicit commands (from implicit rules or the +@code{.DEFAULT} special target; @pxref{Implicit Rules} and @pxref{Last +Resort, ,Defining Last-Resort Default Rules}). You may be inclined to define empty command strings for targets that are not actual files, but only exist so that their dependencies can be remade. However, this is not the best way to do that, because if the target file actually does exist, its dependencies may not be remade. -@xref{Phony Targets}, for a better way to do this. +@xref{Phony Targets, ,Phony Targets}, for a better way to do this. -@node Variables, Conditionals, Commands, Top +@node Using Variables, Conditionals, Commands, Top @chapter How to Use Variables @cindex variable @cindex value @@ -2285,27 +3080,28 @@ A variable name may be any sequence characters not containing @samp{:}, variable names containing characters other than letters, numbers and underscores should be avoided, as they may be given special meanings in the future, and they are not passed through the environment to a -sub-@code{make} (@pxref{Variables/Recursion}). +sub-@code{make} (@pxref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}). It is traditional to use upper case letters in variable names, but we recommend using lower case letters for variable names that serve internal purposes in the makefile, and reserving upper case for parameters that control implicit rules or for parameters that the user should override with -command options (@pxref{Overriding}). +command options (@pxref{Overriding, ,Overriding Variables}). @menu -* Reference:: How to use the value of a variable. -* Flavors:: Variables come in two flavors. -* Advanced:: Advanced features for referencing a variable. -* Values:: All the ways variables get their values. -* Setting:: How to set a variable in the makefile. -* Override Directive:: Setting a variable in the makefile - even if the user has set it with a command argument. -* Defining:: An alternate way to set a variable to a verbatim string. -* Environment:: Variable values can come from the environment. +* Reference:: How to use the value of a variable. +* Flavors:: Variables come in two flavors. +* Advanced:: Advanced features for referencing a variable. +* Values:: All the ways variables get their values. +* Setting:: How to set a variable in the makefile. +* Override Directive:: How to set a variable in the makefile even if + the user has set it with a command argument. +* Defining:: An alternate way to set a variable + to a verbatim string. +* Environment:: Variable values can come from the environment. @end menu -@node Reference, Flavors, Variables, Variables +@node Reference, Flavors, Using Variables, Using Variables @section Basics of Variable References To substitute a variable's value, write a dollar sign followed by the name @@ -2345,20 +3141,20 @@ A dollar sign followed by a character other than a dollar sign, open-parenthesis or open-brace treats that single character as the variable name. Thus, you could reference the variable @code{x} with @samp{$x}. However, this practice is strongly discouraged, except in -the case of the automatic variables (@pxref{Automatic}). +the case of the automatic variables (@pxref{Automatic, ,Automatic Variables}). -@node Flavors, Advanced, Reference, Variables +@node Flavors, Advanced, Reference, Using Variables @section The Two Flavors of Variables @cindex flavors (of variables) @cindex recursive variable expansion -There are two ways that a variables in GNU @code{make} can have a value; -we call them two @dfn{flavors} of variables. The two flavors are +There are two ways that a variable in GNU @code{make} can have a value; +we call them the two @dfn{flavors} of variables. The two flavors are distinguished in how they are defined and in what they do when expanded. The first flavor of variable is a @dfn{recursively expanded} variable. Variables of this sort are defined by lines using @samp{=} -(@pxref{Setting}). The value you specify is installed verbatim; if it +(@pxref{Setting, ,Setting Variables}). The value you specify is installed verbatim; if it contains references to other variables, these references are expanded whenever this variable is substituted (in the course of expanding some other string). When this happens, it is called @dfn{recursive @@ -2400,7 +3196,7 @@ CFLAGS = $(CFLAGS) -O because it will cause an infinite loop in the variable expansion. (Actually @code{make} detects the infinite loop and reports an error.) -Another disadvantage is that any functions (@pxref{Functions}) +Another disadvantage is that any functions (@pxref{Functions, ,Functions for Transforming Text}) referenced in the definition will be executed every time the variable is expanded. This makes @code{make} run slower; worse, it causes the @code{wildcard} and @code{shell} functions to give unpredictable results @@ -2411,7 +3207,7 @@ To avoid all the problems and inconveniences of recursively expanded variables, there is another flavor: @dfn{simply expanded} variables. Simply expanded variables are defined by lines using @samp{:=} -(@pxref{Setting}). The value of a simply expanded variable is scanned +(@pxref{Setting, ,Setting Variables}). The value of a simply expanded variable is scanned once and for all, expanding any references to other variables and functions, when the variable is defined. The actual value of the simply expanded variable is the result of expanding the text that you write. @@ -2439,7 +3235,7 @@ Simply expanded variables generally make complicated makefile programming more predictable because they work like variables in most programming languages. They allow you to redefine a variable using its own value (or its value processed in some way by one of the expansion functions) and to -use the expansion functions much more efficiently (@pxref{Functions}). +use the expansion functions much more efficiently (@pxref{Functions, ,Functions for Transforming Text}). You can also use them to introduce controlled leading or trailing spaces into variable values. Such spaces are discarded from your input before @@ -2455,7 +3251,7 @@ space := $(nullstring) $(nullstring) @noindent Here the value of the variable @code{space} is precisely one space. -@node Advanced, Values, Flavors, Variables +@node Advanced, Values, Flavors, Using Variables @section Advanced Features for Reference to Variables @cindex reference to variables @@ -2463,8 +3259,9 @@ This section describes some advanced features you can use to reference variables in more flexible ways. @menu -* Substitution Refs:: Referencing a variable with substitutions on the value. -* Computed Names:: Computing the name of the variable to refer to. +* Substitution Refs:: Referencing a variable with + substitutions on the value. +* Computed Names:: Computing the name of the variable to refer to. @end menu @node Substitution Refs, Computed Names, Advanced, Advanced @@ -2490,10 +3287,10 @@ bar := $(foo:.o=.c) @end example @noindent -sets @samp{bar} to @samp{a.c b.c c.c}. @xref{Setting}. +sets @samp{bar} to @samp{a.c b.c c.c}. @xref{Setting, ,Setting Variables}. A substitution reference is actually an abbreviation for use of the -@code{patsubst} expansion function (@pxref{Text Functions}). We provide +@code{patsubst} expansion function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}). We provide substitution references as well as @code{patsubst} for compatibility with other implementations of @code{make}. @@ -2502,7 +3299,7 @@ Another type of substitution reference lets you use the full power of the @samp{$(@var{var}:@var{a}=@var{b})} described above, except that now @var{a} must contain a single @samp{%} character. This case is equivalent to @samp{$(patsubst @var{a},@var{b},$(@var{var}))}. -@xref{Text Functions}, for a description of the @code{patsubst} function. +@xref{Text Functions, ,Functions for String Substitution and Analysis}, for a description of the @code{patsubst} function. For example:@refill @example @@ -2521,10 +3318,10 @@ sets @samp{bar} to @samp{a.c b.c c.c}. Computed variable names are a complicated concept needed only for sophisticated makefile programming. For most purposes you need not -consider about them, except to know that making a variable with a dollar -sign in its name might have strange results. However, if you are the -type that wants to understand everything, or you are actually interested -in what they do, read on. +consider them, except to know that making a variable with a dollar sign +in its name might have strange results. However, if you are the type +that wants to understand everything, or you are actually interested in +what they do, read on. Variables may be referenced inside the name of a variable. This is called a @dfn{computed variable name} or a @dfn{nested variable @@ -2573,8 +3370,8 @@ defines @code{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))} which becomes @samp{$(z)} which becomes @samp{Hello}. Nested variable references can also contain modified references and -function invocations (@pxref{Functions}), just like any other reference. -For example, using the @code{subst} function (@pxref{Text Functions}): +function invocations (@pxref{Functions, ,Functions for Transforming Text}), just like any other reference. +For example, using the @code{subst} function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}): @example x = variable1 @@ -2662,10 +3459,10 @@ This restriction could be removed in the future if that change is shown to be a good idea. Note that @dfn{nested variable references} are quite different from -@dfn{recursively expanded variables} (@pxref{Flavors}), though both are +@dfn{recursively expanded variables} (@pxref{Flavors, ,The Two Flavors of Variables}), though both are used together in complex ways when doing makefile programming.@refill -@node Values, Setting, Advanced, Variables +@node Values, Setting, Advanced, Using Variables @section How Variables Get Their Values Variables can get values in several different ways: @@ -2673,26 +3470,26 @@ Variables can get values in several different ways: @itemize @bullet @item You can specify an overriding value when you run @code{make}. -@xref{Overriding}. +@xref{Overriding, ,Overriding Variables}. @item You can specify a value in the makefile, either -with an assignment (@pxref{Setting}) or with a -verbatim definition (@pxref{Defining}).@refill +with an assignment (@pxref{Setting, ,Setting Variables}) or with a +verbatim definition (@pxref{Defining, ,Defining Variables Verbatim}).@refill @item -Values are inherited from the environment. @xref{Environment}. +Values are inherited from the environment. @xref{Environment, ,Variables from the Environment}. @item Several @dfn{automatic} variables are given new values for each rule. -Each of these has a single conventional use. @xref{Automatic}. +Each of these has a single conventional use. @xref{Automatic, ,Automatic Variables}. @item Several variables have constant initial values. -@xref{Implicit Variables}. +@xref{Implicit Variables, ,Variables Used by Implicit Rules}. @end itemize -@node Setting, Override Directive, Values, Variables +@node Setting, Override Directive, Values, Using Variables @section Setting Variables @cindex setting variables @cindex = @@ -2713,7 +3510,7 @@ name and immediately after the @samp{=} is ignored. Variables defined with @samp{=} are @dfn{recursively expanded} variables. Variables defined with @samp{:=} are @dfn{simply expanded} variables; these definitions can contain variable references which will be expanded before -the definition is made. @xref{Flavors}. +the definition is made. @xref{Flavors, ,The Two Flavors of Variables}. There is no limit on the length of the value of a variable except the amount of swapping space on the computer. When a variable definition is @@ -2725,16 +3522,16 @@ to read. Most variable names are considered to have the empty string as a value if you have never set them. Several variables have built-in initial values that are not empty, but can be set by you in the usual ways -(@pxref{Implicit Variables}). Several special variables are set +(@pxref{Implicit Variables, ,Variables Used by Implicit Rules}). Several special variables are set automatically to a new value for each rule; these are called the -@dfn{automatic} variables (@pxref{Automatic}). +@dfn{automatic} variables (@pxref{Automatic, ,Automatic Variables}). -@node Override Directive, Defining, Setting, Variables +@node Override Directive, Defining, Setting, Using Variables @section The @code{override} Directive @findex override @cindex overriding with @code{override} -If a variable has been set with a command argument (@pxref{Overriding}), +If a variable has been set with a command argument (@pxref{Overriding, ,Overriding Variables}), then ordinary assignments in the makefile are ignored. If you want to set the variable in the makefile even though it was set with a command argument, you can use an @code{override} directive, which is a line that @@ -2777,25 +3574,25 @@ endef See the next section. @end iftex @ifinfo -@xref{Defining}. +@xref{Defining, ,Defining Variables Verbatim}. @end ifinfo -@node Defining, Environment, Override Directive, Variables +@node Defining, Environment, Override Directive, Using Variables @section Defining Variables Verbatim @findex define @findex endef Another way to set the value of a variable is to use the @code{define} -directive. This directive has a different syntax which allows newline +directive. This directive has an unusual syntax which allows newline characters to be included in the value, which is convenient for defining -canned sequences of commands (@pxref{Sequences}). +canned sequences of commands (@pxref{Sequences, ,Defining Canned Command Sequences}). The @code{define} directive is followed on the same line by the name of the variable and nothing more. The value to give the variable appears on the following lines. The end of the value is marked by a line containing just the word @code{endef}. Aside from this difference in syntax, @code{define} works just like @samp{=}; it creates a recursively-expanded variable -(@pxref{Flavors}). +(@pxref{Flavors, ,The Two Flavors of Variables}). @example define two-lines @@ -2830,19 +3627,19 @@ endef @end example @noindent -@xref{Override Directive}. +@xref{Override Directive, ,The @code{override} Directive}. -@node Environment, , Defining, Variables +@node Environment, , Defining, Using Variables @section Variables from the Environment @cindex environment -Variables in @code{make} can come from the environment with which +Variables in @code{make} can come from the environment in which @code{make} is run. Every environment variable that @code{make} sees when it starts up is transformed into a @code{make} variable with the same name and value. But an explicit assignment in the makefile, or with a command argument, overrides the environment. (If the @samp{-e} flag is specified, then values from the environment override assignments in the makefile. -@xref{Options}. But this is not recommended practice.) +@xref{Options Summary, ,Summary of Options}. But this is not recommended practice.) Thus, by setting the variable @code{CFLAGS} in your environment, you can cause all C compilations in most makefiles to use the compiler switches you @@ -2853,7 +3650,7 @@ and therefore are not affected by the value in the environment.) When @code{make} is invoked recursively, variables defined in the outer invocation are automatically passed to inner invocations through the -environment (@pxref{Recursion}). This is the main purpose of turning +environment (@pxref{Recursion, ,Recursive Use of @code{make}}). This is the main purpose of turning environment variables into @code{make} variables, and it requires no attention from you.@refill @@ -2870,27 +3667,27 @@ affect @code{make}. So @code{make} ignores the environment value of @code{SHELL} if the value of @code{MAKELEVEL} is zero (which is normally true except in recursive invocations of @code{make}).@refill -@node Conditionals, Functions, Variables, Top +@node Conditionals, Functions, Using Variables, Top @chapter Conditional Parts of Makefiles @cindex conditionals A @dfn{conditional} causes part of a makefile to be obeyed or ignored -depending on the values of variables. Conditionals can compare the value -of one variable with another, or the value of a variable with a constant -string. Conditionals control what @code{make} actually ``sees'' in the -makefile, so they @emph{cannot} be used to control shell commands at the -time of execution.@refill +depending on the values of variables. Conditionals can compare the +value of one variable to another, or the value of a variable to +a constant string. Conditionals control what @code{make} actually +``sees'' in the makefile, so they @emph{cannot} be used to control shell +commands at the time of execution.@refill @menu -* Example: Conditional Example. An annotated example. -* Syntax: Conditional Syntax. Precise rules for syntax of conditionals. -* Flags: Testing Flags. Conditionals testing flags such as @samp{-t}. +* Conditional Example:: Example of a conditional +* Conditional Syntax:: The syntax of conditionals. +* Testing Flags:: Conditionals that test flags. @end menu @node Conditional Example, Conditional Syntax, Conditionals, Conditionals @section Example of a Conditional -This conditional tells @code{make} to use one set of libraries if the +The following example of a conditional tells @code{make} to use one set of libraries if the @code{CC} variable is @samp{gcc}, and a different set of libraries otherwise. It works by controlling which of two command lines will be used as the command for a rule. The result is that @samp{CC=gcc} as an argument @@ -3092,7 +3889,7 @@ endif The @code{echo} command does nothing when executed; but its presence, with a reference to the variable @code{MAKE}, marks the rule as ``recursive'' so that its commands will be executed despite use of the @samp{-t} flag. -@xref{Recursion}. +@xref{Recursion, ,Recursive Use of @code{make}}. @node Functions, Running, Conditionals, Top @chapter Functions for Transforming Text @@ -3106,12 +3903,12 @@ function's processing is substituted into the makefile at the point of the call, just as a variable might be substituted. @menu -* Syntax of Functions:: How to write a function call. -* Text Functions:: General-purpose text manipulation functions. -* Filename Functions:: Functions for manipulating file names. -* Foreach Function:: Repeat some text with controlled variation. -* Origin Function:: Find where a variable got its value. -* Shell Function:: Substitute the output of a shell command. +* Syntax of Functions:: How to write a function call. +* Text Functions:: General-purpose text manipulation functions. +* Filename Functions:: Functions for manipulating file names. +* Foreach Function:: Repeat some text with controlled variation. +* Origin Function:: Find where a variable got its value. +* Shell Function:: Substitute the output of a shell command. @end menu @node Syntax of Functions, Text Functions, Functions, Functions @@ -3309,21 +4106,24 @@ each directory name into a @samp{-I} flag. These can be added to the value of the variable @code{CFLAGS}, which is passed automatically to the C compiler, like this: -@example +@c !!! used smallexample here +@smallexample override CFLAGS:= $(CFLAGS) $(patsubst %,-I%,$(subst :, ,$(VPATH))) -@end example +@end smallexample @noindent The effect is to append the text @samp{-Isrc -I../headers} to the previously given value of @code{CFLAGS}. The @code{override} directive is used so that the new value is assigned even if the previous value of @code{CFLAGS} was specified with a command argument (@pxref{Override -Directive}). +Directive, , The @code{override} Directive}). The function @code{strip} can be very useful when used in conjunction with conditionals. When comparing something with the null string @samp{""} using @code{ifeq} or @code{ifneq}, you usually want a string -of just whitespace to match the null string. Thus, +of just whitespace to match the null string. + +Thus, the following may fail to have the desired results: @example .PHONY: all @@ -3335,7 +4135,7 @@ endif @end example @noindent -might fail to have the desired results. Replacing the variable reference +Replacing the variable reference @samp{"$(needs_made)"} with the function call @samp{"$(strip $(needs_made))"} in the @code{ifneq} directive would make it more robust. @@ -3505,7 +4305,7 @@ The argument @var{pattern} is a file name pattern, typically containing wildcard characters. The result of @code{wildcard} is a space-separated list of the names of existing files that match the pattern. -Wildcards are expanded automatically in rules. @xref{Wildcards}. +Wildcards are expanded automatically in rules. @xref{Wildcards, ,Using Wildcard Characters in File Names}. But they are not normally expanded when a variable is set, or inside the arguments of other functions. Those occasions are when the @code{wildcard} function is useful.@refill @@ -3583,15 +4383,16 @@ the same as they were beforehand. The other values which are taken from @code{foreach}. The variable @var{var} is a simply-expanded variable during the execution of @code{foreach}. If @var{var} was undefined before the @code{foreach} function call, it is undefined after the call. -@xref{Flavors}.@refill +@xref{Flavors, ,The Two Flavors of Variables}.@refill You must take care when using complex variable expressions that result in variable names because many strange things are valid variable names, but are probably not what you intended. For example, -@example +@c !!! used smallexample here +@smallexample files := $(foreach Es escrito en espanol!,b c ch,$(find_files)) -@end example +@end smallexample @noindent might be useful if the value of @code{find_files} references the variable @@ -3626,17 +4427,17 @@ if @var{variable} was never defined. @item default if @var{variable} has a default definition, as is usual with @code{CC} -and so on. @xref{Implicit Variables}. Note that if you have +and so on. @xref{Implicit Variables, ,Variables Used by Implicit Rules}. Note that if you have redefined a default variable, the @code{origin} function will return the origin of the later definition. @item environment if @var{variable} was defined as an environment variable and the -@samp{-e} option is @emph{not} turned on (@pxref{Options}). +@samp{-e} option is @emph{not} turned on (@pxref{Options Summary, ,Summary of Options}). @item environment override if @var{variable} was defined as an environment variable and the -@samp{-e} option @emph{is} turned on (@pxref{Options}). +@samp{-e} option @emph{is} turned on (@pxref{Options Summary, ,Summary of Options}). @item file if @var{variable} was defined in a makefile. @@ -3646,7 +4447,7 @@ if @var{variable} was defined on the command line. @item override if @var{variable} was defined with an @code{override} directive in a -makefile (@pxref{Override Directive}). +makefile (@pxref{Override Directive, ,The @code{override} Directive}). @item automatic if @var{variable} is an automatic variable defined for the @@ -3697,7 +4498,7 @@ Here the redefinition takes place if @samp{$(origin bletch)} returns either @cindex backquotes The @code{shell} function is unlike any other function except the -@code{wildcard} function (@pxref{Wildcard Function}) in that it +@code{wildcard} function (@pxref{Wildcard Function, ,The Function @code{wildcard}}) in that it communicates with the world outside of @code{make}. The @code{shell} function performs the same function that backquotes @@ -3732,7 +4533,7 @@ sets @code{files} to the expansion of @samp{*.c}. Unless @code{make} is using a very strange shell, this has the same result as @samp{$(wildcard *.c)}.@refill -@node Running, Implicit, Functions, Top +@node Running, Implicit Rules, Functions, Top @chapter How to Run @code{make} A makefile that says how to recompile a program can be used in more than @@ -3747,24 +4548,19 @@ By specifying arguments when you run @code{make}, you can do any of these things or many others. @menu -* Makefile Arguments:: Arguments to specify which makefile to use. - -* Goals:: Goal arguments specify which parts of the makefile - should be used. - -* Instead of Execution:: Mode flags specify what kind of thing to do - with the commands in the makefile - other than simply execute them. - -* Avoiding Compilation:: How to avoid recompiling certain files. - -* Overriding:: Overriding a variable can specify an alternate - compiler, or alternate flags for the compiler, - or whatever else you program into the makefile. - -* Testing:: How to proceed past some errors, to test compilation. - -* Options:: Summary of all options @code{make} accepts. +* Makefile Arguments:: How to specify which makefile to use. +* Goals:: How to use goal arguments to specify which + parts of the makefile to use. +* Instead of Execution:: How to use mode flags to specify what + kind of thing to do with the commands + in the makefile other than simply + execute them. +* Avoiding Compilation:: How to avoid recompiling certain files. +* Overriding:: How to override a variable to specify + an alternate compiler and other things. +* Testing:: How to proceed past some errors, to + test compilation. +* Options Summary:: Summary of Options @end menu @node Makefile Arguments, Goals, Running, Running @@ -3774,13 +4570,12 @@ The way to specify the name of the makefile is with the @samp{-f} option. For example, @samp{-f altmake} says to use the file @file{altmake} as the makefile. -If you use the @samp{-f} flag several times (each time with a -following argument), all the specified files are used jointly as +If you use the @samp{-f} flag several times and follow each @samp{-f} with an argument, all the specified files are used jointly as makefiles. If you do not use the @samp{-f} flag, the default is to try @file{GNUmakefile}, @file{makefile}, or @file{Makefile}, in that order, and -use the first of these three which exists. @xref{Makefiles}.@refill +use the first of these three which exists. @xref{Makefiles, ,Writing Makefiles}.@refill @node Goals, Instead of Execution, Makefile Arguments, Running @section Arguments to Specify the Goals @@ -3823,7 +4618,7 @@ of the program that is compiled specially for testing, which has a rule in the makefile but isn't a dependency of the default goal. Another use of specifying a goal is to run the commands associated with a -phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty Targets}). +phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty Targets, ,Empty Target Files to Record Events}). Many makefiles contain a phony target named @file{clean} which deletes everything except source files. Naturally, this is done only if you request it explicitly with @samp{make clean}. Here is a list of typical @@ -3942,7 +4737,7 @@ files.@refill Note that the options @samp{-p} and @samp{-v} allow you to obtain other information about @code{make} or about the makefiles in use. -@xref{Options}.@refill +@xref{Options Summary, ,Summary of Options}.@refill @node Avoiding Compilation, Overriding, Instead of Execution, Running @section Avoiding Recompilation of Some Files @@ -3978,7 +4773,7 @@ header files will not cause any recompilation. If you have already changed the header file at a time when some files do need recompilation, it is too late to do this. Instead, you can use the @samp{-o @var{file}} flag, which marks a specified file as ``old'' -(@pxref{Options}). This means that the file itself won't be remade, +(@pxref{Options Summary, ,Summary of Options}). This means that the file itself won't be remade, and nothing else will be remade on its account. Follow this procedure: @enumerate @@ -4027,7 +4822,7 @@ override it.) The variable @code{CFLAGS} is only one of many standard variables that exist just so that you can change them this way. @xref{Implicit -Variables}, for a complete list. +Variables, , Variables Used by Implicit Rules}, for a complete list. You can also program the makefile to look at additional variables of your own, giving the user the ability to control other aspects of how the @@ -4044,9 +4839,9 @@ variable you create. There is one way that the makefile can change a variable that you have overridden. This is to use the @code{override} directive, which is a line that looks like this: @samp{override @var{variable} = @var{value}}. -@xref{Override Directive}. +@xref{Override Directive, ,The @code{override} Directive}. -@node Testing, Options, Overriding, Running +@node Testing, Options Summary, Overriding, Running @section Testing the Compilation of a Program @cindex testing compilation @@ -4070,7 +4865,7 @@ already knows that linking them will be impossible. In addition to continuing after failed shell commands, @samp{make -k} will continue as much as possible after discovering that it doesn't know how to make a target or dependency file. This will always cause an error message, but without -@samp{-k}, it is a fatal error. @xref{Options}. +@samp{-k}, it is a fatal error. @xref{Options Summary, ,Summary of Options}. The usual behavior of @code{make} assumes that your purpose is to get the goals up to date; once @code{make} learns that this is impossible, it might @@ -4080,7 +4875,7 @@ program, perhaps to find several independent problems so that you can correct them all before the next attempt to compile. This is why Emacs's @kbd{M-x compile} command passes the @samp{-k} flag by default. -@node Options, , Testing, Running +@node Options Summary, , Testing, Running @section Summary of Options @cindex options @cindex flags @@ -4097,7 +4892,7 @@ Change to directory @var{dir} before reading the makefiles. If multiple @samp{-C} options are specified, each is interpreted relative to the previous one: @samp{-C / -C etc} is equivalent to @samp{-C /etc}. This is typically used with recursive invocations of @code{make} -(@pxref{Recursion}). +(@pxref{Recursion, ,Recursive Use of @code{make}}). @item -d Print debugging information in addition to normal processing. The @@ -4109,18 +4904,18 @@ considered and which are applied---everything interesting about how @item -e Give variables taken from the environment precedence -over variables from makefiles. @xref{Environment}. +over variables from makefiles. @xref{Environment, ,Variables from the Environment}. @item -f @var{file} -Use file @var{file} as a makefile. @xref{Makefiles}. +Use file @var{file} as a makefile. @xref{Makefiles, ,Writing Makefiles}. @item -i Ignore all errors in commands executed to remake files. -@xref{Errors}. +@xref{Errors, ,Errors in Commands}. @item -I @var{dir} Specifies a directory @var{dir} to search for included makefiles. -@xref{Include}. If several @samp{-I} options are used to specify several +@xref{Include, ,Including Other Makefiles}. If several @samp{-I} options are used to specify several directories, the directories are searched in the order specified. Unlike the arguments to other flags of @code{make}, directories given with @samp{-I} flags may come directly after the flag: @samp{-I@var{dir}} is @@ -4130,30 +4925,30 @@ compatibility with the C preprocessor's @samp{-I} flag.@refill @item -j @var{jobs} Specifies the number of jobs (commands) to run simultaneously. If there is more than one @samp{-j} option, the last one is effective. -@xref{Execution}, for more information on how commands are run. +@xref{Execution, ,Command Execution}, for more information on how commands are run. @item -k Continue as much as possible after an error. While the target that failed, and those that depend on it, cannot be remade, the other dependencies of these targets can be processed all the same. -@xref{Testing}. +@xref{Testing, ,Testing the Compilation of a Program}. @item -l @var{load} @item -l Specifies that no new jobs (commands) should be started if there are others jobs running and the load average is at least @var{load} (a floating-point number). With no argument, removes a previous load -limit. @xref{Parallel}. +limit. @xref{Parallel, ,Parallel Execution}. @item -n Print the commands that would be executed, but do not execute them. -@xref{Instead of Execution}. +@xref{Instead of Execution, ,Instead of Executing the Commands}. @item -o @var{file} Do not remake the file @var{file} even if it is older than its dependencies, and do not remake anything on account of changes in @var{file}. Essentially the file is treated as very old and its rules -are ignored. @xref{Avoiding Compilation}. +are ignored. @xref{Avoiding Compilation, ,Avoiding Recompilation of Some Files}. @item -p Print the data base (rules and variable values) that results from @@ -4165,28 +4960,28 @@ trying to remake any files, use @samp{make -p -f /dev/null}. @item -q ``Question mode''. Do not run any commands, or print anything; just return an exit status that is zero if the specified targets are -already up to date, nonzero otherwise. @xref{Instead of Execution}. +already up to date, nonzero otherwise. @xref{Instead of Execution, ,Instead of Executing the Commands}. @item -r -Eliminate use of the built-in implicit rules (@pxref{Implicit}). +Eliminate use of the built-in implicit rules (@pxref{Implicit Rules, ,Using Implicit Rules}). Also clear out the default list of suffixes for suffix rules -(@pxref{Suffix Rules}). +(@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}). @item -s Silent operation; do not print the commands as they are executed. -@xref{Echoing}. +@xref{Echoing, ,Command Echoing}. @item -S Cancel the effect of the @samp{-k} option. This is never necessary except in a recursive @code{make} where @samp{-k} might be inherited -from the top-level @code{make} via @code{MAKEFLAGS} (@pxref{Recursion}) +from the top-level @code{make} via @code{MAKEFLAGS} (@pxref{Recursion, ,Recursive Use of @code{make}}) or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill @item -t Touch files (mark them up to date without really changing them) instead of running their commands. This is used to pretend that the commands were done, in order to fool future invocations of -@code{make}. @xref{Instead of Execution}. +@code{make}. @xref{Instead of Execution, ,Instead of Executing the Commands}. @item -v Print the version of the @code{make} program plus a copyright, a list @@ -4199,7 +4994,7 @@ information without doing anything else, use @samp{make -v -f Print a message containing the working directory both before and after executing the makefile. This may be useful for tracking down errors from complicated nests of recursive @code{make} commands. -@xref{Recursion}. +@xref{Recursion, ,Recursive Use of @code{make}}. @item -W @var{file} Pretend that the target @var{file} has just been modified. When used @@ -4210,7 +5005,7 @@ running a @code{touch} command on the given file before running imagination of @code{make}.@refill @end table -@node Implicit, Archives, Running, Top +@node Implicit Rules, Archives, Running, Top @chapter Using Implicit Rules @cindex implicit rule @@ -4220,8 +5015,9 @@ using the C compiler, @code{cc}. @dfn{Implicit rules} tell @code{make} how to use customary techniques so that you don't have to specify them in detail when you want to use them. -For example, there is an implicit rule for C compilation. Implicit rules -work based on file names. For example, C compilation typically takes a +For example, there is an implicit rule for C compilation. +File names determine which implicit rules are run. +For example, C compilation typically takes a @file{.c} file and makes a @file{.o} file. So @code{make} applies the implicit rule for C compilation when it sees this combination of file-name endings. @@ -4229,7 +5025,7 @@ endings. A chain of implicit rules can apply in sequence; for example, @code{make} will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file. @iftex -@xref{Chained Rules}. +@xref{Chained Rules, ,Chains of Implicit Rules}. @end iftex The built-in implicit rules use several variables in their commands so @@ -4237,35 +5033,29 @@ that, by changing the values of the variables, you can change the way the implicit rule works. For example, the variable @code{CFLAGS} controls the flags given to the C compiler by the implicit rule for C compilation. @iftex -@xref{Implicit Variables}. +@xref{Implicit Variables, ,Variables Used by Implicit Rules}. @end iftex You can define your own implicit rules by writing @dfn{pattern rules}. @iftex -@xref{Pattern Rules}. +@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}. @end iftex @menu -* Using Implicit:: How to use an existing implicit rule - to get the commands for updating a file. - -* Catalogue of Rules:: Catalogue of built-in implicit rules. - -* Implicit Variables:: By changing certain variables, you can - change what the predefined implicit rules do. - -* Chained Rules:: Using a chain of implicit rules. - -* Pattern Rules:: Defining new implicit rules. - -* Last Resort:: Defining commands for rules which can't find any. - -* Suffix Rules:: The old-fashioned style of implicit rule. - -* Search Algorithm:: Precise algorithm for applying implicit rules. +* Using Implicit:: How to use an existing implicit rule + to get the commands for updating a file. +* Catalogue of Rules:: A list of built-in implicit rules. +* Implicit Variables:: How to change what predefined rules do. +* Chained Rules:: How to use a chain of implicit rules. +* Pattern Rules:: How to define new implicit rules. +* Last Resort:: How to defining commands for rules + which can't find any. +* Suffix Rules:: The old-fashioned style of implicit rule. +* Search Algorithm:: The precise algorithm for applying + implicit rules. @end menu -@node Using Implicit, Catalogue of Rules, Implicit, Implicit +@node Using Implicit, Catalogue of Rules, Implicit Rules, Implicit Rules @section Using Implicit Rules To allow @code{make} to find a customary method for updating a target file, @@ -4303,7 +5093,7 @@ compiler; and so on. Of course, when you write the makefile, you know which implicit rule you want @code{make} to use, and you know it will choose that one because you know which possible dependency files are supposed to exist. -@xref{Catalogue of Rules}, for a catalogue of all the predefined implicit +@xref{Catalogue of Rules, ,Catalogue of Implicit Rules}, for a catalogue of all the predefined implicit rules. Above, we said an implicit rule applies if the required dependencies ``exist @@ -4311,31 +5101,31 @@ or can be made''. A file ``can be made'' if it is mentioned explicitly in the makefile as a target or a dependency, or if an implicit rule can be recursively found for how to make it. When an implicit dependency is the result of another implicit rule, we say that @dfn{chaining} is occurring. -@xref{Chained Rules}. +@xref{Chained Rules, ,Chains of Implicit Rules}. In general, @code{make} searches for an implicit rule for each target, and for each double-colon rule, that has no commands. A file that is mentioned only as a dependency is considered a target whose rule specifies nothing, -so implicit rule search happens for it. @xref{Search Algorithm}, for the +so implicit rule search happens for it. @xref{Search Algorithm, ,Implicit Rule Search Algorithm}, for the details of how the search is done. If you don't want an implicit rule to be used for a target that has no commands, you can give that target empty commands by writing a semicolon. -@xref{Empty Commands}. +@xref{Empty Commands, ,Defining Empty Commands}. -@node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit +@node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules @section Catalogue of Implicit Rules Here is a catalogue of predefined implicit rules which are always available unless the makefile explicitly overrides or cancels them. -@xref{Canceling Rules}, for information on canceling or overriding an +@xref{Canceling Rules, ,Canceling Implicit Rules}, for information on canceling or overriding an implicit rule. The @samp{-r} option cancels all predefined rules. Not all of these rules will always be defined, even when the @samp{-r} option is not given. Many of the predefined implicit rules are implemented in @code{make} as suffix rules, so which ones will be defined depends on the @dfn{suffix list} (the list of dependencies of -the special target @code{.SUFFIXES}). @xref{Suffix Rules}. +the special target @code{.SUFFIXES}). @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}. The default suffix list is: @samp{.out}, @samp{.a}, @samp{.o}, @samp{.c}, @samp{.cc}, @samp{.C}, @samp{.p}, @samp{.f}, @samp{.F}, @samp{.r}, @samp{.e}, @samp{.y}, @samp{.ye}, @samp{.yr}, @samp{.l}, @samp{.s}, @@ -4512,13 +5302,13 @@ shell scripts that are checked into SCCS. Since RCS preserves the execution permission of a file, you don't need to use this feature with RCS.@refill -We recommend that you avoid the use of SCCS. RCS is widely held to be +We recommend that you avoid using of SCCS. RCS is widely held to be superior, and is also free. By choosing free software in place of comparable (or inferior) proprietary software, you support the free software movement. @end table -@node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit +@node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit Rules @section Variables Used by Implicit Rules @cindex flags for compilers @@ -4549,7 +5339,7 @@ Here is a table of variables used as names of programs: @table @code @item AR @vindex AR -Archive-maintaing program; default @samp{ar}. +Archive-maintaining program; default @samp{ar}. @item AS @vindex AS @@ -4615,7 +5405,8 @@ programs; default @samp{yacc -e}. @item MAKEINFO @vindex MAKEINFO -Program to make Info files from Texinfo source; default @samp{makeinfo}. +Program to convert a Texinfo source file into an Info file; default +@samp{makeinfo}. @item TEX @vindex TEX @@ -4713,7 +5504,7 @@ Extra flags to give to the Fortran compiler for Ratfor programs. Extra flags to give to Yacc. @end table -@node Chained Rules, Pattern Rules, Implicit Variables, Implicit +@node Chained Rules, Pattern Rules, Implicit Variables, Implicit Rules @section Chains of Implicit Rules @cindex chains of rules @@ -4747,7 +5538,9 @@ implicit rule so as to preserve certain intermediate files. You can also list the target pattern of an implicit rule (such as @samp{%.o}) as a dependency file of the special target @code{.PRECIOUS} to preserve intermediate files whose target patterns match that file's name.)@refill -@cindex preserving intermediate files with .PRECIOUS +@cindex intermediate files, preserving +@cindex preserving intermediate files +@cindex preserving with .PRECIOUS A chain can involve more than two implicit rules. For example, it is possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS, @@ -4769,7 +5562,7 @@ and linking with a single @code{cc} command. The optimized rule is used in preference to the step-by-step chain because it comes earlier in the ordering of rules. -@node Pattern Rules, Last Resort, Chained Rules, Implicit +@node Pattern Rules, Last Resort, Chained Rules, Implicit Rules @section Defining and Redefining Pattern Rules You define an implicit rule by writing a @dfn{pattern rule}. A pattern @@ -4783,24 +5576,14 @@ Thus, a pattern rule @samp{%.o : %.c} says how to make any file @file{@var{stem}.o} from another file @file{@var{stem}.c}.@refill @menu -* Intro: Pattern Intro. Basics of writing pattern rules. -* Examples: Pattern Examples. Real examples of pattern rule definitions. - -* Vars: Automatic. The automatic variables enable the commands - in pattern rules to act on the right files. - -* Matching: Pattern Match. Details of how patterns match. - -* Match-Anything Rules:: Precautions in defining a rules that can - match any target file whatever. - -* Canceling Rules:: Overriding or canceling built-in rules. - -* Last Resort:: How to define a last-resort rule - that applies to any target that no other - rule applies to. - -* Suffix Rules:: The old-fashioned way to define implicit rules. +* Pattern Intro:: An introduction to pattern rules. +* Pattern Examples:: Examples of pattern rules. +* Automatic:: Automatic variables. +* Pattern Match:: How patterns match. +* Match-Anything Rules:: Precautions you should take prior to + defining rules that can match any + target file whatever. +* Canceling Rules:: How to override or cancel built-in rules. @end menu @node Pattern Intro, Pattern Examples, Pattern Rules, Pattern Rules @@ -4878,7 +5661,7 @@ files:@refill defines a rule that can make any file @file{@var{x}.o} from @file{@var{x}.c}. The command uses the automatic variables @samp{$@@} and @samp{$<} to substitute the names of the target file and the source file -in each case where the rule applies (@pxref{Automatic}).@refill +in each case where the rule applies (@pxref{Automatic, ,Automatic Variables}).@refill Here is a second built-in rule: @@ -4888,12 +5671,12 @@ Here is a second built-in rule: @end example @noindent -defines a rule that can make any file @file{@var{x}} whatever from a +defines a rule that can make any file @file{@var{x}} whatsoever from a corresponding file @file{@var{x},v} in the subdirectory @file{RCS}. Since the target is @samp{%}, this rule will apply to any file whatever, provided the appropriate dependency file exists. The double colon makes the rule @dfn{terminal}, which means that its dependency may not be an intermediate -file (@pxref{Match-Anything Rules}).@refill +file (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}).@refill This pattern rule has two targets: @@ -4903,15 +5686,17 @@ This pattern rule has two targets: @end example @noindent -This tells @code{make} that the command @samp{bison -d @var{x}.y} -will make both @file{@var{x}.tab.c} and @file{@var{x}.tab.h}. If the file -@file{foo} depends on the files @file{parse.tab.o} and @file{scan.o} and -@file{scan.o} depends on @file{parse.tab.h}, when @file{parse.y} is -changed, the command @samp{bison -d parse.y} will be executed only once, -and the dependencies of both @file{parse.tab.o} and @file{scan.o} will be -satisfied. (Presumably, @file{parse.tab.o} will be recompiled from -@file{parse.tab.c} and @file{scan.o} from @file{scan.c}, and @file{foo} -will be linked from @file{parse.tab.o}, @file{scan.o}, and its other +@c The following paragraph is rewritten to avoid overfull hboxes +This tells @code{make} that the command @samp{bison -d @var{x}.y} will +make both @file{@var{x}.tab.c} and @file{@var{x}.tab.h}. If the file +@file{foo} depends on the files @file{parse.tab.o} and @file{scan.o} +and the file @file{scan.o} depends on the file @file{parse.tab.h}, +when @file{parse.y} is changed, the command @samp{bison -d parse.y} +will be executed only once, and the dependencies of both +@file{parse.tab.o} and @file{scan.o} will be satisfied. (Presumably, +the file @file{parse.tab.o} will be recompiled from @file{parse.tab.c} +and the file @file{scan.o} from @file{scan.c}, and @file{foo} will be +linked from @file{parse.tab.o}, @file{scan.o}, and its other dependencies, and it will execute happily ever after.)@refill @node Automatic, Pattern Match, Pattern Examples, Pattern Rules @@ -4953,14 +5738,14 @@ newer than the target, with spaces between them. The names of all the dependencies, with spaces between them. @item $* -The stem with which an implicit rule matches (@pxref{Pattern Match}). +The stem with which an implicit rule matches (@pxref{Pattern Match, ,How Patterns Match}). If the target is @file{dir/a.foo.b} and the target pattern is @file{a.%.b} then the stem is @file{dir/foo}. The stem is useful for constructing names of related files.@refill In an explicit rule, there is no stem; so @samp{$*} cannot be determined in that way. Instead, if the target name ends with a -recognized suffix (@pxref{Suffix Rules}), @samp{$*} is set to the +recognized suffix (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}), @samp{$*} is set to the target name minus the suffix. For example, if the target name is @samp{foo.c}, then @samp{$*} is set to @samp{foo}, since @samp{.c} is a suffix.@refill @@ -4980,13 +5765,14 @@ lib: foo.o bar.o lose.o win.o @end example Of the variables listed above, four have values that are single file -names, and two have values that are lists of file names. These six have -variants that get just the file's directory name or just the file name -within the directory. The variant variables' names are formed by +names, and two have values that are lists of file names. These six +have variants that get just the file's directory name or just the file +name within the directory. The variant variables' names are formed by appending @samp{D} or @samp{F}, respectively. These variants are semi-obsolete in GNU @code{make} since the functions @code{dir} and @code{notdir} can be used to get an equivalent effect (@pxref{Filename -Functions}). Here is a table of the variants:@refill +Functions, , Functions for File Names}). Here is a table of the +variants:@refill @table @samp @item $(@@D) @@ -5011,7 +5797,7 @@ The directory part and the file-within-directory part of the target archive member name. This makes sense only for archive member targets of the form @file{@var{archive}(@var{member})} and useful only when @var{member} may contain a directory name. -(@xref{Archive Members}.) +(@xref{Archive Members, ,Archive Members as Targets}.) @item $(<D) @itemx $(<F) @@ -5140,7 +5926,7 @@ specific target pattern and thereby prevent time from being wasted looking for @file{foo.p.o} or @file{foo.p.c}. Dummy pattern rules such as the one for @samp{%.p} are made for every -suffix listed as valid for use in suffix rules. @xref{Suffix Rules}. +suffix listed as valid for use in suffix rules. @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}. @node Canceling Rules, , Match-Anything Rules, Pattern Rules @subsection Canceling Implicit Rules @@ -5159,7 +5945,7 @@ would cancel the rule that runs the assembler: %.o : %.s @end example -@node Last Resort, Suffix Rules, Pattern Rules, Implicit +@node Last Resort, Suffix Rules, Pattern Rules, Implicit Rules @section Defining Last-Resort Default Rules @findex .DEFAULT @@ -5191,11 +5977,12 @@ If you give @code{.DEFAULT} with no commands or dependencies: the commands previously stored for @code{.DEFAULT} are cleared. Then @code{make} acts as if you had never defined @code{.DEFAULT} at all. -If you want a target not to get the commands from @code{.DEFAULT}, but nor -do you want any commands to be run for the target, you can give it empty -commands. @xref{Empty Commands}. +If you don't want a target to get the commands from @code{.DEFAULT}, but +you also +do not want any commands to be run for the target, you can give it empty +commands. @xref{Empty Commands, ,Defining Empty Commands}. -@node Suffix Rules, Search Algorithm, Last Resort, Implicit +@node Suffix Rules, Search Algorithm, Last Resort, Implicit Rules @section Old-Fashioned Suffix Rules @cindex suffix rules @@ -5259,7 +6046,7 @@ which tells how to make @code{.o} files from @code{.c} files, and makes all Suffix rules with no commands are also meaningless. They do not remove previous rules as do pattern rules with no commands (@pxref{Canceling -Rules}). They simply enter the suffix or pair of suffixes concatenated as +Rules, , Canceling Implicit Rules}). They simply enter the suffix or pair of suffixes concatenated as a target in the data base.@refill @findex .SUFFIXES @@ -5293,7 +6080,7 @@ before @code{make} reads any makefiles. You can change the list of suffixes with a rule for the special target @code{.SUFFIXES}, but that does not alter this variable. -@node Search Algorithm, , Suffix Rules, Implicit +@node Search Algorithm, , Suffix Rules, Implicit Rules @section Implicit Rule Search Algorithm Here is the procedure @code{make} uses for searching for an implicit rule @@ -5391,9 +6178,9 @@ update status as the file @var{t}. When the commands of a pattern rule are executed for @var{t}, the automatic variables are set corresponding to the target and dependencies. -@xref{Automatic}. +@xref{Automatic, ,Automatic Variables}. -@node Archives, Features, Implicit, Top +@node Archives, Features, Implicit Rules, Top @chapter Using @code{make} to Update Archive Files @cindex archive @@ -5402,11 +6189,8 @@ variables are set corresponding to the target and dependencies. main use is as subroutine libraries for linking. @menu -* Members: Archive Members. How to name an archive member - as a target or dependency. -* Update: Archive Update. An implicit rule can update - most archive member targets just right. -* Symbols: Archive Symbols. Special things to do for library archives. +* Archive Members:: Archive members as targets. +* Archive Update:: The implicit rule for archive member targets. @end menu @node Archive Members, Archive Update, Archives, Archives @@ -5439,7 +6223,7 @@ foolib(hack.o) : hack.o In fact, nearly all archive member targets are updated in just this way and there is an implicit rule to do it for you. -@node Archive Update, Archive Symbols, Archive Members, Archives +@node Archive Update, , Archive Members, Archives @section Implicit Rule for Archive Member Targets Recall that a target that looks like @file{@var{a}(@var{m})} stands for the @@ -5470,7 +6254,7 @@ Here @code{make} has envisioned the file @file{bar.o} as an intermediate file. Implicit rules such as this one are written using the automatic variable -@samp{$%}. @xref{Automatic}. +@samp{$%}. @xref{Automatic, ,Automatic Variables}. An archive member name in an archive cannot contain a directory name, but it may be useful in a makefile to pretend that it does. If you write an @@ -5486,7 +6270,11 @@ which has the effect of copying the file @file{dir/foo.o} into a member named @file{foo.o}. In connection with such usage, the automatic variables @code{%D} and @code{%F} may be useful. -@node Archive Symbols, , Archive Update, Archives +@menu +* Archive Symbols:: How to update archive symbol directories. +@end menu + +@node Archive Symbols, , Archive Update, Archive Update @subsection Updating Archive Symbol Directories @cindex __.SYMDEF @@ -5531,32 +6319,32 @@ Many features come from the version of @code{make} in System V. @itemize @bullet @item The @code{VPATH} variable and its special meaning. @xref{Directory -Search}. This feature exists in System V @code{make}, but is undocumented. +Search, , Searching Directories for Dependencies}. This feature exists in System V @code{make}, but is undocumented. It is documented in 4.3 BSD @code{make} (which says it mimics System V's @code{VPATH} feature).@refill @item -Included makefiles. @xref{Include}. +Included makefiles. @xref{Include, ,Including Other Makefiles}. @item Variables are read from and communicated via the environment. -@xref{Environment}. +@xref{Environment, ,Variables from the Environment}. @item Options passed through the variable @code{MAKEFLAGS} to recursive -invocations of @code{make}. @xref{Options/Recursion}. +invocations of @code{make}. @xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}. @item The automatic variable @code{$%} is set to the member name -in an archive reference. @xref{Automatic}. +in an archive reference. @xref{Automatic, ,Automatic Variables}. @item The automatic variables @code{$@@}, @code{$*}, @code{$<} and @code{$%} have corresponding forms like @code{$(@@F)} and @code{$(@@D)}. -@xref{Automatic}.@refill +@xref{Automatic, ,Automatic Variables}.@refill @item -Substitution variable references. @xref{Reference}. +Substitution variable references. @xref{Reference, ,Basics of Variable References}. @item The command-line options @samp{-b} and @samp{-m}, accepted and ignored. @@ -5564,12 +6352,12 @@ The command-line options @samp{-b} and @samp{-m}, accepted and ignored. @item Execution of recursive commands to run @code{make} via the variable @code{MAKE} even if @samp{-n}, @samp{-q} or @samp{-t} is specified. -@xref{Recursion}. +@xref{Recursion, ,Recursive Use of @code{make}}. @item Support for suffix @samp{.a} in suffix rules. In GNU @code{make}, this is actually implemented by chaining with one pattern rule for -installing members in an archive. @xref{Chained Rules}.@refill +installing members in an archive. @xref{Chained Rules, ,Chains of Implicit Rules}.@refill @item The arrangement of lines and backslash-newline combinations in @@ -5587,7 +6375,7 @@ which others. Pattern rules using @samp{%}. This has been implemented in several versions of @code{make}. We're not sure who invented it first, but it's been spread around a bit. -@xref{Pattern Rules}.@refill +@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.@refill @item Rule chaining and implicit intermediate files. @@ -5595,25 +6383,25 @@ This was implemented by Stu Feldman in his version of @code{make} for AT&T Eighth Edition Research Unix, and later by Andrew Hume of AT&T Bell Labs in his @code{mk} program. We don't really know if we got this from either of them or thought it up ourselves at the -same time. @xref{Chained Rules}. +same time. @xref{Chained Rules, ,Chains of Implicit Rules}. @item The automatic variable @code{$^} containing a list of all dependencies of the current target. We didn't invent this, but we have no idea who did. -@xref{Automatic}. +@xref{Automatic, ,Automatic Variables}. @item The ``what if'' flag (@samp{-W} in GNU @code{make}) was (as far as we know) -invented by Andrew Hume in @code{mk}. @xref{Instead of Execution}. +invented by Andrew Hume in @code{mk}. @xref{Instead of Execution, ,Instead of Executing the Commands}. @item The concept of doing several things at once (parallelism) exists in many incarnations of @code{make} and similar programs, though not in the -System V or BSD implementations. @xref{Execution}. +System V or BSD implementations. @xref{Execution, ,Command Execution}. @item Modified variable references using pattern substitution come from -SunOS 4.0. @xref{Reference}. This functionality was provided in GNU +SunOS 4.0. @xref{Reference, ,Basics of Variable References}. This functionality was provided in GNU @code{make} by the @code{patsubst} function before the alternate syntax was implemented for compatibility with SunOS 4.0. It is not altogether clear who inspired whom, since GNU @code{make} had @code{patsubst} @@ -5621,7 +6409,7 @@ before SunOS 4.0 was released.@refill @item The special significance of @samp{+} characters preceding command lines -(@pxref{Instead of Execution}) is mandated by draft 8 of IEEE Std 1003.2 +(@pxref{Instead of Execution, ,Instead of Executing the Commands}) is mandated by draft 8 of IEEE Std 1003.2 (POSIX).@refill @end itemize @@ -5629,86 +6417,90 @@ The remaining features are inventions new in GNU @code{make}: @itemize @bullet @item -The @samp{-v} option to print version and copyright information. +Use the @samp{-v} option to print version and copyright information. @item -Simply-expanded variables. @xref{Flavors}. +Simply-expand variables. @xref{Flavors, ,The Two Flavors of Variables}. @item -Passing command-line variable assignments automatically through the +Pass command-line variable assignments automatically through the variable @code{MAKE} to recursive @code{make} invocations. -@xref{Recursion}. +@xref{Recursion, ,Recursive Use of @code{make}}. @item -The @samp{-C} command option to change directory. @xref{Options}. +Use the @samp{-C} command option to change directory. @xref{Options Summary, ,Summary of Options}. @item -Verbatim variable definitions made with @code{define}. @xref{Defining}. +Make verbatim variable definitions with @code{define}. @xref{Defining, ,Defining Variables Verbatim}. @item -Phony targets declared with the special target @code{.PHONY}. -A similar feature with a different syntax was implemented by -Andrew Hume of AT&T Bell Labs in his @code{mk} program. This -seems to be a case of parallel discovery. @xref{Phony Targets}. +Declare phony targets with the special target @code{.PHONY}. + +Andrew Hume of AT&T Bell Labs implemented a similar feature with a +different syntax in his @code{mk} program. This seems to be a case of +parallel discovery. @xref{Phony Targets, ,Phony Targets}. @item -Text manipulation by calling functions. @xref{Functions}. +Manipulate text by calling functions. @xref{Functions, ,Functions for Transforming Text}. @item -The @samp{-o} option to pretend a file's modification-time is old. -@xref{Avoiding Compilation}. +Use the @samp{-o} option to pretend a file's modification-time is old. +@xref{Avoiding Compilation, ,Avoiding Recompilation of Some Files}. @item Conditional execution. -This has been implemented numerous times in various versions of -@code{make}; it seems a natural extension derived from the features + +This feature has been implemented numerous times in various versions +of @code{make}; it seems a natural extension derived from the features of the C preprocessor and similar macro languages and is not a -revolutionary concept. @xref{Conditionals}. +revolutionary concept. @xref{Conditionals, ,Conditional Parts of Makefiles}. @item -The included makefile search path. @xref{Include}. +Specify the included makefile search path. @xref{Include, ,Including +Other Makefiles}. @item -Specifying extra makefiles to read. @xref{MAKEFILES Variable}. +Specify the extra makefiles to read. @xref{MAKEFILES Variable, ,The +Variable @code{MAKEFILES}}. @item -Stripping leading sequences of @samp{./} from file names, so that +Strip leading sequences of @samp{./} from file names, so that @file{./@var{file}} and @file{@var{file}} are considered to be the same file.@refill @item -Special search method for library dependencies written in the form -@samp{-l@var{name}}. @xref{Libraries/Search}. +Use a special search method for library dependencies written in the +form @samp{-l@var{name}}. @xref{Libraries/Search, ,Directory Search for Link Libraries}. @item -Allowing suffixes for suffix rules (@pxref{Suffix Rules}) to contain -any characters. In other version of @code{make}, they must begin with +Allow suffixes for suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}) to contain any +characters. In other version of @code{make}, they must begin with @samp{.} and not contain any @samp{/} characters. @item -The variable @code{MAKELEVEL} which keeps track of the current level -of @code{make} recursion. @xref{Recursion}. +Keep track of the current level of @code{make} recursion using the +variable @code{MAKELEVEL}. @xref{Recursion, ,Recursive Use of @code{make}}. @item -Static pattern rules. @xref{Static Pattern}. +Specify static pattern rules. @xref{Static Pattern, ,Static Pattern Rules}. @item -Selective @code{vpath} search. @xref{Directory Search}. +Provide selective @code{vpath} search. @xref{Directory Search, ,Searching Directories for Dependencies}. @item -Recursive variable references. @xref{Reference}. +Provide recursive variable references. @xref{Reference, ,Basics of Variable References}. @item -Updated makefiles. @xref{Remaking Makefiles}. +Update makefiles. @xref{Remaking Makefiles, ,How Makefiles Are Remade}. System V @code{make} has a very, very limited form of this functionality in that it will check out SCCS files for makefiles. @item -Several new built-in implicit rules. @xref{Catalogue of Rules}. +Various new built-in implicit rules. @xref{Catalogue of Rules, ,Catalogue of Implicit Rules}. @end itemize -@node Missing, Concept Index, Features, Top -@chapter Missing Features in GNU @code{make} +@node Missing, Complex Makefile, Features, Top +@chapter Missing Features of GNU @code{make} The @code{make} programs in various other systems support a few features that are not implemented in GNU @code{make}. Draft 11.1 of the POSIX.2 @@ -5723,7 +6515,7 @@ being an object file which defines the linker symbol @var{entry}.@refill This feature was not put into GNU @code{make} because of the nonmodularity of putting knowledge into @code{make} of the internal -format of archive file symbol directories. @xref{Archive Symbols}. +format of archive file symbol directories. @xref{Archive Symbols, ,Updating Archive Symbol Directories}. @item Suffixes (used in suffix rules) that end with the character @samp{~} @@ -5731,11 +6523,11 @@ have a special meaning; they refer to the SCCS file that corresponds to the file one would get without the @samp{~}. For example, the suffix rule @samp{.c~.o} would make the file @file{@var{n}.o} file from the SCCS file @file{s.@var{n}.c}. For complete coverage, a whole -series of such suffix rules is required. @xref{Suffix Rules}.@refill +series of such suffix rules is required. @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.@refill In GNU @code{make}, this entire series of cases is handled by two pattern rules for extraction from SCCS, in combination with the -general feature of rule chaining. @xref{Chained Rules}. +general feature of rule chaining. @xref{Chained Rules, ,Chains of Implicit Rules}. @item In System V @code{make}, the string @samp{$$@@} has the strange meaning @@ -5746,7 +6538,7 @@ This is not defined in GNU @code{make} because @samp{$$} should always stand for an ordinary @samp{$}. It is possible to get this functionality through the use of static pattern -rules (@pxref{Static Pattern}). The System V @code{make} rule: +rules (@pxref{Static Pattern, ,Static Pattern Rules}). The System V @code{make} rule: @example $(targets): $$@@.o lib.a @@ -5761,12 +6553,12 @@ $(targets): %: %.o lib.a @item In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search -(@pxref{Directory Search}) have their names changed inside command +(@pxref{Directory Search, ,Searching Directories for Dependencies}) have their names changed inside command strings. We feel it is much cleaner to always use automatic variables and thus make this feature obsolete.@refill @item -In some Unix @code{make}s, implicit rule search (@pxref{Implicit}) is +In some Unix @code{make}s, implicit rule search (@pxref{Implicit Rules, ,Using Implicit Rules}) is apparently done for @emph{all} targets, not just those without commands. This means you can do:@refill @@ -5784,16 +6576,302 @@ We feel that such usage is broken. The dependency properties of and doing such a thing simply does not fit the model.@refill @end itemize -@node Concept Index, Name Index, Missing, Top +@node Complex Makefile, Concept Index, Missing, Top +@appendix Complex Makefile + +Here is the makefile for the GNU @code{tar} program. This is a +moderately complex makefile. + +Because it is the first target, the default goal is @samp{all}. An +interesting feature of this makefile is that @file{testpad.h} is a +source file automatically created by the @code{testpad} program, +itself compiled from @file{testpad.c}. + +If you type @kbd{make} or @kbd{make all}, then @code{make} creates +the @code{tar} executable, the @code{rmt} daemon that provides +remote tape access, and the @file{tar.info} Info file. + +If you type @kbd{make install}, then @code{make} not only creates +@code{tar}, @code{rmt}, and @file{tar.info}, but also installs +them. + +If you type @kbd{make clean}, then @code{make} removes the @code{*.o} +files, and the @code{tar}, @code{rmt}, @code{testpad}, +@code{testpad.h}, and @code{core} files. + +If you type @kbd{make distclean}, then @code{make} not only removes +the same files as does @kbd{make clean} but also the +@file{TAGS}, @file{Makefile}, and @file{config.status} files. +(Although it is not evident, this makefile (and +@file{config.status}) is generated by the user with the +@code{configure} program, which is provided in the @code{tar} +distribution, but is not shown here.) + +If you type @kbd{make realclean}, then @code{make} removes the same +files as does @kbd{make distclean} and also the Info files +generated from @file{tar.texinfo}. + +In addition, there are targets @code{shar} and @code{dist} that create +distribution kits. + +@example +@group +# Generated automatically from Makefile.in by configure. +# Un*x Makefile for GNU tar program. +# Copyright (C) 1991 Free Software Foundation, Inc. +@end group + +@group +# This program is free software; you can redistribute +# it and/or modify it under the terms of the GNU +# General Public License as published by the Free +# Software Foundation; either version 2, or (at your +# option) any later version. +@end group + +# This program is distributed in the hope that it will +# be useful, but WITHOUT ANY WARRANTY; without even +# the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. +# See the GNU General Public License for more details. + +@group +# You should have received a copy of the GNU General +# Public License along with this program; if not, +# write to the Free Software Foundation, Inc., +# 675 Mass Ave, Cambridge, MA 02139, USA. +@end group + +SHELL = /bin/sh + +#### Start of system configuration section. #### + +srcdir = . + +@group +# If you use gcc, you should either run the +# fixincludes script that comes with it or else use +# gcc with the -traditional option. Otherwise ioctl +# calls will be compiled incorrectly on some systems. +CC = gcc -O +YACC = bison -y +INSTALL = /usr/local/bin/install -c +INSTALLDATA = /usr/local/bin/install -c -m 644 +@end group + +# Things you might add to DEFS: +# -DSTDC_HEADERS If you have ANSI C headers and +# libraries. +# -DPOSIX If you have POSIX.1 headers and +# libraries. +# -DBSD42 If you have sys/dir.h (unless +# you use -DPOSIX), sys/file.h, +# and st_blocks in `struct stat'. +# -DUSG If you have System V/ANSI C +# string and memory functions +# and headers, sys/sysmacros.h, +# fcntl.h, getcwd, no valloc, +# and ndir.h (unless +# you use -DDIRENT). +# -DNO_MEMORY_H If USG or STDC_HEADERS but don't +# include memory.h. +# -DDIRENT If USG and you have dirent.h +# instead of ndir.h. +# -DSIGTYPE=int If your signal handlers +# return int, not void. +# -DNO_MTIO If you lack sys/mtio.h +# (magtape ioctls). +# -DNO_REMOTE If you do not have a remote shell +# or rexec. +# -DUSE_REXEC To use rexec for remote tape +# operations instead of +# forking rsh or remsh. +# -DVPRINTF_MISSING If you lack vprintf function +# (but have _doprnt). +# -DDOPRNT_MISSING If you lack _doprnt function. +# Also need to define +# -DVPRINTF_MISSING. +# -DFTIME_MISSING If you lack ftime system call. +# -DSTRSTR_MISSING If you lack strstr function. +# -DVALLOC_MISSING If you lack valloc function. +# -DMKDIR_MISSING If you lack mkdir and +# rmdir system calls. +# -DRENAME_MISSING If you lack rename system call. +# -DFTRUNCATE_MISSING If you lack frtruncate +# system call. +# -DV7 On Version 7 Unix (not +# tested in a long time). +# -DEMUL_OPEN3 If you lack a 3-argument version +# of open, and want to emulate it +# with system calls you do have. +# -DNO_OPEN3 If you lack the 3-argument open +# and want to disable the tar -k +# option instead of emulating open. +# -DXENIX If you have sys/inode.h +# and need it 94 to be included. + +DEFS = -DSIGTYPE=int -DDIRENT -DSTRSTR_MISSING \ + -DVPRINTF_MISSING -DBSD42 +# Set this to rtapelib.o unless you defined NO_REMOTE, +# in which case make it empty. +RTAPELIB = rtapelib.o +LIBS = +DEF_AR_FILE = /dev/rmt8 +DEFBLOCKING = 20 + +@group +CDEBUG = -g +CFLAGS = $(CDEBUG) -I. -I$(srcdir) $(DEFS) \ + -DDEF_AR_FILE=\"$(DEF_AR_FILE)\" \ + -DDEFBLOCKING=$(DEFBLOCKING) +LDFLAGS = -g +@end group + +@group +prefix = /usr/local +# Prefix for each installed program, +# normally empty or `g'. +binprefix = + +# The directory to install tar in. +bindir = $(prefix)/bin + +# The directory to install the info files in. +infodir = $(prefix)/info +@end group + +#### End of system configuration section. #### + +SRC1 = tar.c create.c extract.c buffer.c \ + getoldopt.c update.c gnu.c mangle.c +SRC2 = version.c list.c names.c diffarch.c \ + port.c wildmat.c getopt.c +SRC3 = getopt1.c regex.c getdate.y +SRCS = $(SRC1) $(SRC2) $(SRC3) +OBJ1 = tar.o create.o extract.o buffer.o \ + getoldopt.o update.o gnu.o mangle.o +OBJ2 = version.o list.o names.o diffarch.o \ + port.o wildmat.o getopt.o +OBJ3 = getopt1.o regex.o getdate.o $(RTAPELIB) +OBJS = $(OBJ1) $(OBJ2) $(OBJ3) +@group +AUX = README COPYING ChangeLog Makefile.in \ + makefile.pc configure configure.in \ + tar.texinfo tar.info* texinfo.tex \ + tar.h port.h open3.h getopt.h regex.h \ + rmt.h rmt.c rtapelib.c alloca.c \ + msd_dir.h msd_dir.c tcexparg.c \ + level-0 level-1 backup-specs testpad.c +@end group + +all: tar rmt tar.info + +@group +tar: $(OBJS) + $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS) +@end group + +@group +rmt: rmt.c + $(CC) $(CFLAGS) $(LDFLAGS) -o $@ rmt.c +@end group + +@group +tar.info: tar.texinfo + makeinfo tar.texinfo +@end group + +@group +install: all + $(INSTALL) tar $(bindir)/$(binprefix)tar + -test ! -f rmt || $(INSTALL) rmt /etc/rmt + $(INSTALLDATA) $(srcdir)/tar.info* $(infodir) +@end group + +@group +$(OBJS): tar.h port.h testpad.h +regex.o buffer.o tar.o: regex.h +# getdate.y has 8 shift/reduce conflicts. +@end group + +@group +testpad.h: testpad + ./testpad +@end group + +@group +testpad: testpad.o + $(CC) -o $@ testpad.o +@end group + +@group +TAGS: $(SRCS) + etags $(SRCS) +@end group + +@group +clean: + rm -f *.o tar rmt testpad testpad.h core +@end group + +@group +distclean: clean + rm -f TAGS Makefile config.status +@end group + +@group +realclean: distclean + rm -f tar.info* +@end group + +@group +shar: $(SRCS) $(AUX) + shar $(SRCS) $(AUX) | compress \ + > tar-`sed -e '/version_string/!d' \ + -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \ + -e q + version.c`.shar.Z +@end group + +@group +dist: $(SRCS) $(AUX) + echo tar-`sed \ + -e '/version_string/!d' \ + -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \ + -e q + version.c` > .fname + -rm -rf `cat .fname` + mkdir `cat .fname` + ln $(SRCS) $(AUX) `cat .fname` + -rm -rf `cat .fname` .fname + tar chZf `cat .fname`.tar.Z `cat .fname` +@end group + +@group +tar.zoo: $(SRCS) $(AUX) + -rm -rf tmp.dir + -mkdir tmp.dir + -rm tar.zoo + for X in $(SRCS) $(AUX) ; do \ + echo $$X ; \ + sed 's/$$/^M/' $$X \ + > tmp.dir/$$X ; done + cd tmp.dir ; zoo aM ../tar.zoo * + -rm -rf tmp.dir +@end group +@end example + +@node Concept Index, Name Index, Complex Makefile, Top @unnumbered Index of Concepts @printindex cp @node Name Index, , Concept Index, Top -@unnumbered Index of Functions, Variables, and Directives +@unnumbered Index of Functions, Variables, & Directives @printindex fn @summarycontents @contents @bye + |