OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / gnumake / info / make.i01

Wrap

Text File | 1992-03-14 | 51KB | 1,062 lines

Info file make.info, produced by Makeinfo, -*- Text -*- from input file make.texinfo. This file documents the GNU Make utility. Copyright (C) 1988-1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. 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 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. File: make.info, Node: Top, Next: Overview, Up: (dir) The GNU `make' utility determines automatically 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: * Menu: * Overview:: Introducing `make'. * Copying:: Copying conditions for GNU `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 `make'. * Running:: How to run `make'; how you can adjust the way `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 `make' to update archive files. * Features:: GNU `make''s advanced features and how GNU `make' relates to other versions of `make'. * Missing:: Features of other `make's not supported by GNU `make'. * Concept Index::Index of cross-references to where concepts are discussed. * Name Index:: Index of cross-references for names of `make''s variables, functions, special targets and directives. File: make.info, Node: Overview, Next: Copying, Prev: Top, Up: Top Overview of `make' ****************** The purpose of the `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 `make', which was implemented by Richard Stallman and Roland McGrath. Our examples show C programs, since they are most common, but you can use `make' with any programming language whose compiler can be run with a shell command. In fact, `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. To prepare to use `make', you must write a file called the "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 files, which are in turn made by compiling source files. Once a suitable makefile exists, each time you change some source files, this simple shell command: make suffices to perform all necessary recompilations. The `make' program 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. File: make.info, Node: Copying, Next: Bugs, Prev: Overview, Up: Top GNU GENERAL PUBLIC LICENSE ************************** Version 2, June 1991 Copyright (C) 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. 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. TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 1. 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. 2. 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. 3. 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: a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. b) 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. c) 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.) 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. 4. 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: a) 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, b) 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, c) 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.) 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. 5. 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. 6. 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. 7. 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. 8. 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. 9. 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. 10. 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. 11. 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. NO WARRANTY 12. 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. 13. 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 OF TERMS AND CONDITIONS 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. ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. Copyright (C) 19YY 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. 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. 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: Gnomovision version 69, Copyright (C) 19YY 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. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `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: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker. SIGNATURE OF TY COON, 1 April 1989 Ty Coon, President of Vice 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. File: make.info, Node: Bugs, Next: Simple, Prev: Copying, Up: Top Problems and Bugs ***************** If you have problems with GNU `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. 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 what you're trying to do. If it's not clear whether you should be able to do something or not, report that too; it's a bug in the documentation! Before reporting a bug or trying to fix it yourself, try to isolate it to the smallest possible makefile that reproduces the problem. Then send us the makefile and the exact results `make' gave you. Also say what you expected to occur; this will help us decide whether the problem was really in the documentation. Once you've got a precise problem, send email to (Internet) `bug-gnu-utils@prep.ai.mit.edu' or (UUCP) `mit-eddie!prep.ai.mit.edu!bug-gnu-utils'. Please include the version number of `make' you are using. You can get this information with the command `make -v -f /dev/null'. 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 `roland@prep.ai.mit.edu' or UUCP path `mit-eddie!prep.ai.mit.edu!roland'. File: make.info, Node: Simple, Next: Makefiles, Prev: Bugs, Up: Top Simple Example of `make' ************************ Suppose we have a text editor consisting of eight C source files and three header files. We need a makefile to tell `make' how to compile and link the editor. Assume that all the C files include `defs.h', but only those defining editing commands include `commands.h' and only low level files that change the editor buffer include `buffer.h'. 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. Here is a straightforward makefile that describes these criteria and says how to compile and link when the time comes: 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 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 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 "target" of a "rule" (*note Rules::.). (In this example, these are the object files such as `main.o', `kbd.o', etc., and the executable file `edit'.) The target appears at the beginning of a line, followed by a colon. After the colon come the target's "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, `edit' depends on each of the eight object files; the object file `main.o' depends on the source file `main.c' and on the header file `defs.h'. By default, `make' starts with the first rule (not counting rules whose target names start with `.'). This is called the "default goal". Therefore, we put the rule for the executable program `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 `make' that they are command lines. But `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 `make' does is execute the commands you have specified when the target file needs to be updated. How `make' Processes This Makefile ================================== After reading the makefile, `make' begins its real work by processing the first rule, the one for relinking `edit'; but before it can fully process this rule, it must process the rules for the files `edit' depends on: all the object files. Each of these files is processed according to its own rule. These rules say to update the `.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. Before recompiling an object file, `make' considers updating its dependencies, the source file and header files. This makefile does not specify anything to be done for them--the `.c' and `.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. After recompiling whichever object files need it, `make' can now decide whether to relink `edit'. This must be done if the 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 `edit', so `edit' will be relinked. Thus, if we change the file `insert.c' and run `make', `make' will compile that file to update `insert.o', and then link `edit'. If we change the file `command.h' and run `make', `make' will recompile the object files `kbd.o', `commands.o' and `files.o' and then link file `edit'. Variables Make Makefiles Simpler ================================ In our example, we had to list all the object files twice in the rule for `edit' (repeated here): 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 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 "variable". Variables allow a text string to be defined once and substituted in multiple places later (*note Variables::.). It is standard practice for every makefile to have a variable named `objects', `OBJECTS', `objs', `OBJS', `obj' or `OBJ' which is a list of all object file names. We would define such a variable `objects' with a line like this in the makefile: objects = main.o kbd.o commands.o display.o \ insert.o search.o files.o utils.o Then, each place we want to put a list of the object file names, we can substitute the variable's value by writing `$(objects)' (*note Variables::.). Here is how the rule for `edit' looks as a result: edit : $(objects) cc -o edit $(objects) Letting `make' Deduce the Commands ================================== It is not necessary to spell out the commands for compiling the individual C source files, because `make' can figure them out: it has an "implicit rule" for updating a `.o' file from a correspondingly named `.c' file using a `cc -c' command. For example, it will use the command `cc -c main.c -o main.o' to compile `main.c' into `main.o'. We can therefore omit the commands from the rules for the object files. *Note Implicit::. When a `.c' file is used automatically in this way, it is also automatically added to the list of dependencies. We can therefore omit the `.c' files from the dependencies, provided we omit the commands. Here is the entire example, with both of these changes, and a variable `objects' as suggested above: 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 : defs.h kbd.o : defs.h command.h commands.o : defs.h command.h display.o : defs.h buffer.h insert.o : defs.h buffer.h search.o : defs.h buffer.h files.o : defs.h buffer.h command.h utils.o : defs.h This is how we would write the makefile in actual practice. 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: objects = main.o kbd.o commands.o display.o \ insert.o search.o files.o utils.o edit : $(objects) cc -o edit $(objects) $(objects) : defs.h kbd.o commands.o files.o : command.h display.o insert.o search.o files.o : buffer.h Here `defs.h' is given as a dependency of all the object files; `commands.h' and `buffer.h' are dependencies of the specific object files listed for them. 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. 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 `make' rule for cleaning our example editor: clean: rm edit $(objects) 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 `edit', which recompiles the editor, to remain the default goal. Since `clean' is not a dependency of `edit', this rule won't run at all if we give the command `make' with no arguments. In order to make the rule run, we have to type `make clean'. File: make.info, Node: Makefiles, Next: Rules, Prev: Simple, Up: Top Writing Makefiles ***************** The information that tells `make' how to recompile a system comes from reading a data base called the "makefile". * Menu: * Contents: Makefile Contents. Overview of what you put in a makefile. * Names: Makefile Names. Where `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 with another makefile. File: make.info, Node: Makefile Contents, Next: Makefile Names, Prev: Makefiles, Up: Makefiles What Makefiles Contain ====================== Makefiles contain four kinds of things: "rules", "variable definitions", "directives" and "comments". Rules, variables and directives are described at length in later chapters. * A rule says when and how to remake one or more files, called the rule's "targets". It lists the other files that the targets "depend on", and may also give commands to use to create or update the targets. *Note Rules::. * A variable definition is a line that specifies a text string value for a "variable" that can be substituted into the text later. The simple makefile example (*note Simple::.) shows a variable definition for `objects' as a list of all object files. *Note Variables::, for full details. * A directive is a command for `make' to do something special while reading the makefile. These include: * Reading another makefile (*note Include::.). * Deciding (based on the values of variables) whether to use or ignore a part of the makefile (*note Conditionals::.). * Defining a variable from a verbatim string containing multiple lines (*note Defining::.). * `#' in a line of a makefile starts a comment. It and the rest of the line are ignored, except that a trailing backslash not escaped by another backslash will continue the comment across multiple lines. Comments may appear on any of the lines in the makefile, except within a `define' directive, and perhaps within commands (where the shell decides what is a comment). A line containing just a comment (with perhaps spaces before it) is effectively blank, and is ignored. File: make.info, Node: Makefile Names, Next: Include, Prev: Makefile Contents, Up: Makefiles What Name to Give Your Makefile =============================== By default, when `make' looks for the makefile, it tries the names `GNUmakefile', `makefile' and `Makefile', in that order. Normally you should call your makefile either `makefile' or `Makefile'. (We recommend `Makefile' because it appears prominently near the beginning of a directory listing, right near other important files such as `README'.) The first name checked, `GNUmakefile', is not recommended for most makefiles. You should use this name if you have a makefile that is specific to GNU `make', and will not be understood by other versions of `make'. If `make' finds none of these names, it does not use any makefile. Then you must specify a goal with a command argument, and `make' will attempt to figure out how to remake it using only its built-in implicit rules. *Note Implicit::. If you want to use a nonstandard name for your makefile, you can specify the makefile name with the `-f' option. The arguments `-f NAME' tell `make' to read the file NAME as the makefile. If you use more than one `-f' option, you can specify several makefiles. All the makefiles are effectively concatenated in the order specified. The default makefile names `GNUmakefile', `makefile' and `Makefile' are not checked automatically if you specify `-f'. File: make.info, Node: Include, Next: MAKEFILES Variable, Prev: Makefile Names, Up: Makefiles Including Other Makefiles ========================= The `include' directive tells `make' to suspend reading the current makefile and read another makefile before continuing. The directive is a line in the makefile that looks like this: include FILENAME Extra spaces are allowed and ignored at the beginning of the line, but a tab is not allowed. (If the line begins with a tab, it will be considered a command line.) Whitespace is required between `include' and FILENAME; extra whitespace is ignored there and at the end of the directive. A comment starting with `#' is allowed at the end of the line. If FILENAME contains any variable or function references, they are expanded. (*Note Variables::.) When `make' processes an `include' directive, it suspends reading of the containing makefile and reads from FILENAME instead. When that is finished, `make' resumes reading the makefile in which the directive appears. One occasion for using `include' directives is when several programs, handled by individual makefiles in various directories, need to use a common set of variable definitions (*note Setting::.) or pattern rules (*note 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 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 `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 `-I' option are searched (*note Options::.). Then the following directories (if they exist) are searched, in this order: `/usr/gnu/include', `/usr/local/include', `/usr/include'. If an included makefile cannot be found in any of these directories, a warning message is generated, but it is not a fatal error; processing of the makefile containing the `include' continues. File: make.info, Node: MAKEFILES Variable, Next: Remaking Makefiles, Prev: Include, Up: Makefiles The Variable `MAKEFILES' ======================== If the environment variable `MAKEFILES' is defined, `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 `include' directive: various directories are searched for those files (*note Include::.). In addition, the default goal is never taken from one of these makefiles and it is not an error if the files listed in `MAKEFILES' are not found. The main use of `MAKEFILES' is in communication between recursive invocations of `make' (*note Recursion::.). It usually isn't desirable to set the environment variable before a top-level invocation of `make', because it is usually better not to mess with a makefile from outside. However, if you are running `make' without a specific makefile, a makefile in `MAKEFILES' can do useful things to help the built-in implicit rules work better, such as defining search paths. Some users are tempted to set `MAKEFILES' in the environment automatically on login, and program makefiles to expect this to be done. This is a very bad idea, because such makefiles will fail to work if run by anyone else. It is much better to write explicit `include' directives in the makefiles. File: make.info, Node: Remaking Makefiles, Next: Overriding Makefiles, Prev: MAKEFILES Variable, Up: Makefiles How Makefiles Are Remade ======================== Sometimes makefiles can be remade from other files, such as RCS or SCCS files. If a makefile can be remade from other files, you probably want `make' to get an up-to-date version of the makefile to read in. To this end, after reading in all makefiles, `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 (*note Implicit::.), it will be updated if necessary. After all makefiles have been checked, if any have actually been changed, `make' starts with a clean slate and reads all the makefiles over again. (It will also attempt to update each of them over again, but normally this will not change them again, since they are already up to date.) If the makefiles specify commands to remake a file but no dependencies, the file will always be remade. In the case of makefiles, a makefile that has commands but no dependencies will be remade every time `make' is run, and then again after `make' starts over and reads the makefiles in again. This would cause an infinite loop; `make' would constantly remake the makefile, and never do anything else. So, to avoid this, `make' will *not* attempt to remake makefiles which are specified as targets but have no dependencies. If you do not specify any makefiles to be read with `-f' options, `make' will try the default makefile names; *note Makefile Names::.. Unlike makefiles explicitly requested with `-f' options, `make' is not certain that these makefiles should exist. However, if a default makefile does not exist but can be created by running `make' rules, you probably want the rules to be run so that the makefile can be used. Therefore, if none of the default makefiles exists, `make' will try to make each of them in the same order in which they are searched for (*note Makefile Names::.) until it succeeds in making one, or it runs out of names to try. Note that it is not an error if `make' cannot find or make any makefile; a makefile is not always necessary. When you use the `-t' option (touch targets), you would not want to use an out-of-date makefile to decide which targets to touch. So the `-t' option has no effect on updating makefiles; they are really updated even if `-t' is specified. Likewise, `-q' and `-n' do not prevent updating of makefiles, because an out-of-date makefile would result in the wrong output for other targets. Thus, `make -f mfile -n foo' will update `mfile', read it in, and then print the commands to update `foo' and its dependencies without running them. The commands printed for `foo' will be those specified in the updated contents of `mfile'. However, on occasion you might actually wish to prevent updating of even the makefiles. You can do this by specifying the makefiles as goals in the command line as well as specifying them as makefiles. When the makefile name is specified explicitly as a goal, the options `-t' and so on do apply to them. Thus, `make -f mfile -n mfile foo' would read the makefile `mfile', print the commands needed to update it without actually running them, and then print the commands needed to update `foo' without running them. The commands for `foo' will be those specified by the existing contents of `mfile'. File: make.info, Node: Overriding Makefiles, Prev: Remaking Makefiles, Up: Makefiles Overriding Part of One Makefile with Another Makefile ===================================================== Sometimes it is useful to have a makefile that is mostly just like another makefile. You can often use the `include' directive to include one in the other, and add more targets or variable definitions. However, if the two makefiles give different commands for the same target, `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 `.DEFAULT' special target to say that to remake any target that cannot be made from the information in the containing makefile, `make' should look in another makefile. *Note Last Resort::, for more information on `.DEFAULT'. For example, if you have a makefile called `Makefile' that says how to make the target `foo' (and other targets), you can write a makefile called `GNUmakefile' that contains: foo: frobnicate > foo .DEFAULT: @$(MAKE) -f Makefile $@ If you say `make foo', `make' will find `GNUmakefile', read it, and see that to make `foo', it needs to run the command `frobnicate > foo'. If you say `make bar', `make' will find no way to make `bar' in `GNUmakefile', so it will use the commands from `.DEFAULT': `make -f Makefile bar'. If `Makefile' provides a rule for updating `bar', `make' will apply the rule. And likewise for any other target that `GNUmakefile' does not say how to make. File: make.info, Node: Rules, Next: Commands, Prev: Makefiles, Up: Top Writing Rules ************* A "rule" appears in the makefile and says when and how to remake certain files, called the rule's "targets" (usually only one per rule). It lists the other files that are the "dependencies" of the target, and "commands" to use to create or update the target. The order of rules is not significant, except for determining the "default goal": the target for `make' to consider, if you do 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 (*note Pattern Rules::.) or a suffix rule (*note 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. *Note 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. File: make.info, Node: Rule Example, Next: Rule Syntax, Prev: Rules, Up: Rules Rule Example ============ Here is an example of a rule: foo.o : foo.c defs.h # module for twiddling the frobs cc -c -g foo.c Its target is `foo.o' and its dependencies are `foo.c' and `defs.h'. It has one command, which is `cc -c -g foo.c'. The command line starts with a tab to identify it as a command. This rule says two things: * How to decide whether `foo.o' is out of date: it is out of date if it does not exist, or if either `foo.c' or `defs.h' is more recent than it. * How to update the file `foo.o': by running `cc' as stated. The command does not explicitly mention `defs.h', but we presume that `foo.c' includes it, and that that is why `defs.h' was added to the dependencies.