⟦3bedbad9c⟧

TextFile

Info file make-info, produced by Makeinfo, -*- Text -*- from input
file make.texinfo.

This file documents the GNU Make utility.

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.

▶1f◀
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; it 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.

▶1f◀
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.

▶1f◀
File: make-info, Node: Copying, Next: Bugs, Prev: Overview, Up: Top

GNU GENERAL PUBLIC LICENSE
**************************

Version 1, February 1989

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble
=========

The license agreements of most software companies try to keep users
at the mercy of those companies. By contrast, our 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.
The General Public License applies to the Free Software Foundation's
software and to any other program whose authors commit to using it.
You can use it for your programs, too.

When we speak of free software, we are referring to freedom, not
price. Specifically, the General Public License is designed to make
sure that you have the freedom to give away or sell copies of free
software, 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 a 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 tell them 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.

The precise terms and conditions for copying, distribution and
modification follow.

TERMS AND CONDITIONS

1. This License Agreement 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 work containing the Program or a portion of it,
either verbatim or with modifications. Each licensee is
addressed as ``you''.

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 General Public License
and to the absence of any warranty; and give any other
recipients of the Program a copy of this General Public License
along with the Program. You may charge a fee for the physical
act of transferring a copy.

3. You may modify your copy or copies of the Program or any portion
of it, and copy and distribute such modifications under the
terms of Paragraph 1 above, provided that you also do the
following:

* cause the modified files to carry prominent notices stating
that you changed the files and the date of any change; and

* cause the whole of any work that you distribute or publish,
that in whole or in part contains the Program or any part
thereof, either with or without modifications, to be
licensed at no charge to all third parties under the terms
of this General Public License (except that you may choose
to grant warranty protection to some or all third parties,
at your option).

* If the modified program normally reads commands
interactively when run, you must cause it, when started
running for such interactive use in the simplest and most
usual 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
General Public License.

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

Mere aggregation of another independent work with the Program
(or its derivative) on a volume of a storage or distribution
medium does not bring the other work under the scope of these
terms.

4. You may copy and distribute the Program (or a portion or
derivative of it, under Paragraph 2) in object code or
executable form under the terms of Paragraphs 1 and 2 above
provided that you also do one of the following:

* accompany it with the complete corresponding
machine-readable source code, which must be distributed
under the terms of Paragraphs 1 and 2 above; or,

* accompany it with a written offer, valid for at least three
years, to give any third party free (except for a nominal
charge for the cost of distribution) a complete
machine-readable copy of the corresponding source code, to
be distributed under the terms of Paragraphs 1 and 2 above;
or,

* accompany it with the information you received as to where
the corresponding source code may be obtained. (This
alternative is allowed only for noncommercial distribution
and only if you received the program in object code or
executable form alone.)

Source code for a work means the preferred form of the work for
making modifications to it. For an executable file, complete
source code means all the source code for all modules it
contains; but, as a special exception, it need not include
source code for modules which are standard libraries that
accompany the operating system on which the executable file
runs, or for standard header files or definitions files that
accompany that operating system.

5. You may not copy, modify, sublicense, distribute or transfer the
Program except as expressly provided under this General Public
License. Any attempt otherwise to copy, modify, sublicense,
distribute or transfer the Program is void, and will
automatically terminate your rights to use the Program under
this License. However, parties who have received copies, or
rights to use copies, from you under this General Public License
will not have their licenses terminated so long as such parties
remain in full compliance.

6. By copying, distributing or modifying 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.

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.

8. 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 the 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 the license,
you may choose any version ever published by the Free Software
Foundation.

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

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

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

Appendix: 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 humanity, 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 1, 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 a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the
program `Gnomovision' (a program to direct compilers to make passes
at assemblers) written by James Hacker.

SIGNATURE OF TY COON, 1 April 1989
Ty Coon, President of Vice

That's all there is to it!

▶1f◀
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@wheaties.ai.mit.edu' or UUCP path
`mit-eddie!wheaties.ai.mit.edu!roland'.

▶1f◀
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 `all', which
recompiles the editor, to remain the default goal.

Since `clean' is not a dependency of `all', 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'.

▶1f◀
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.

▶1f◀
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.

▶1f◀
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'.

▶1f◀
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.

▶1f◀
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.

▶1f◀
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'.

▶1f◀
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.

▶1f◀
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.

▶1f◀
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.

▶1f◀
File: make-info, Node: Rule Syntax, Next: Wildcards, Prev: Rule Example, Up: Rules

Rule Syntax
===========

In general, a rule looks like this:

TARGETS : DEPENDENCIES
COMMAND
COMMAND
...

or like this:

TARGETS : DEPENDENCIES ; COMMAND
COMMAND
COMMAND
...

The TARGETS are file names, separated by spaces. Wild card
characters may be used (*note Wildcards::.) and a name of the form
`A(M)' represents member M in archive file A (*note Archive
Members::.). Usually there is only one target per rule, but
occasionally there is a reason to have more; *Note Multiple Targets::.

The 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. *Note Commands::.

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
(`$$'). *Note Variables::. You may split a long line by inserting a
backslash followed by a newline, but this is not required, as `make'
places no limit on the length of a line in a makefile.

A rule tells `make' two things: when the targets are out of date, and
how to update them when necessary.

The criterion for being out of date is specified in terms of the
DEPENDENCIES, which consist of file names separated by spaces.
(Wildcards and archive members are allowed here too.) A target is
out of date if it does not exist or if it is older than any of the
dependencies (by comparison of last-modification times). The idea is
that the contents of the target file are computed based on
information in the dependencies, so if any of the dependencies
changes, the contents of the existing target file are no longer
necessarily valid.

How to update is specified by COMMANDS. These are lines to be
executed by the shell (normally `sh'), but with some extra features
(*note Commands::.).

▶1f◀
File: make-info, Node: Wildcards, Next: Directory Search, Prev: Rule Syntax, Up: Rules

Using Wildcards Characters in File Names
========================================

A single file name can specify many files using "wildcard characters".
The wildcard characters in `make' are `*', `?' and `[...]', the same
as in the Bourne shell. For example, `*.c' specifies a list of all
the files (in the working directory) whose names end in `.c'.

The character `~' 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 `~/bin' expands to `/home/you/bin'. If
the `~' is followed by a word, the string represents the home
directory of the user named by that word. For example `~me/bin'
expands to `/home/me/bin'.

Wildcard expansion happens automatically in targets, in dependencies,
and in commands. In other contexts, wildcard expansion happens only
if you request it explicitly with the `wildcard' function.

The special significance of a wildcard character can be turned off by
preceding it with a backslash. Thus, `foo\*bar' would refer to a
specific file whose name consists of `foo', an asterisk, and `bar'.

* Menu:

* Examples: Wildcard Examples. Some simple examples.
* Pitfall: Wildcard Pitfall. `*.o' won't do what you want!
* Function: Wildcard Function.
How to do wildcard expansion when defining a variable
using the function `wildcard'.

▶1f◀
File: make-info, Node: Wildcard Examples, Next: Wildcard Pitfall, Prev: Wildcards, Up: Wildcards

Wildcard Examples
-----------------

Wildcards can be used in the commands of a rule. For example, here
is a rule to delete all the object files:

clean:
rm -f *.o

Wildcards are also useful in the dependencies of a rule. With the
following rule in the makefile, `make print' will print all the `.c'
files that have changed since the last time you printed them:

print: *.c
lpr -p $?
touch print

This rule uses `print' as an empty target file; *note Empty Targets::..

Wildcard expansion does not happen when you define a variable. Thus,
if you write this:

objects=*.o

then the value of the variable `objects' is the actual string `*.o'.
However, if you use the value of `objects' in a target, dependency or
command, wildcard expansion will take place at that time.

▶1f◀
File: make-info, Node: Wildcard Pitfall, Next: Wildcard Function, Prev: Wildcard Examples, Up: Wildcards

Pitfalls of Using Wildcards
---------------------------

Now here is an example of a naive way of using wildcard expansion,
that does not do what you would intend. Suppose you would like to
say that the executable file `foo' is made from all the object files
in the directory, and you write this:

objects=*.o

foo : $(objects)
cc -o foo $(CFLAGS) $(objects)

The value of `objects' is the actual string `*.o'. Wildcard
expansion happens in the rule for `foo', so that each *existing* `.o'
file becomes a dependency of `foo' and will be recompiled if necessary.

But what if you delete all the `.o' files? Then `*.o' will expand
into *nothing*. The target `foo' will have no dependencies and would
be remade by linking no object files. This is not what you want!

Actually it is possible to obtain the desired result with wildcard
expansion, but you need more sophisticated techniques, including the
`wildcard' function and string substitution.

*Note Wildcard Function::.

▶1f◀
File: make-info, Node: Wildcard Function, Prev: Wildcard Pitfall, Up: Wildcards

The Function `wildcard'
-----------------------

Wildcard expansion happens automatically in rules. But wildcard
expansion does not normally take place when a variable is set, or
inside the arguments of a function. If you want to do wildcard
expansion in such places, you need to use the `wildcard' function,
like this:

$(wildcard PATTERN)

This string, used anywhere in a makefile, is replaced by a
space-separated list of names of existing files that match the
pattern PATTERN.

One use of the `wildcard' function is to get a list of all the C
source files in a directory, like this:

$(wildcard *.c)

We can change the list of C source files into a list of object files
by substituting `.o' for `.c' in the result, like this:

$(subst .c,.o,$(wildcard *.c))

(Here we have used another function, `subst'. *Note Text Functions::.)

Thus, a makefile to compile all C source files in the directory and
then link them together could be written as follows:

objects:=$(subst .c,.o,$(wildcard *.c))

foo : $(objects)
cc -o foo $(LDFLAGS) $(objects)

(This takes advantage of the implicit rule for compiling C programs,
so there is no need to write explicit rules for compiling the files.
*Note Flavors::, for an explanation of `:=', which is a variant of
`='.)

DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦3bedbad9c⟧ TextFile

Derivation

TextFile