GNU make - 3. Writing Makefiles

Go to the first, previous, next, last section, table of contents.

# 3. Writing Makefiles

The information that tells `make` how to recompile a system comes from reading a data base called the makefile.

## 3.1 What Makefiles Contain

Makefiles contain five kinds of things: explicit rules, implicit rules, variable definitions, directives, and comments. Rules, variables, and directives are described at length in later chapters.

- An explicit 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. See section 4. Writing Rules.
- An implicit rule says when and how to remake a class of files based on their names. It describes how a target may depend on a file with a name similar to the target and gives commands to create or update such a target. See section 10. Using Implicit 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 shows a variable definition for `objects` as a list of all object files (see section 2.4 Variables Make Makefiles Simpler).
- A directive is a command for `make` to do something special while reading the makefile. These include:
  - Reading another makefile (see section 3.3 Including Other Makefiles).
  - Deciding (based on the values of variables) whether to use or ignore a part of the makefile (see section 7. Conditional Parts of Makefiles).
  - Defining a variable from a verbatim string containing multiple lines (see section 6.8 Defining Variables Verbatim).
- ``#'` 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.

## 3.2 What Name to Give Your Makefile

By default, when `make` looks for the makefile, it tries the following names, in order: ``GNUmakefile'`, ``makefile'` and ``Makefile'`.

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`. Other `make` programs look for ``makefile'` and ``Makefile'`, but not ``GNUmakefile'`.

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. See section 10. Using Implicit Rules.

If you want to use a nonstandard name for your makefile, you can specify the makefile name with the ``-f'` or ``--file'` option. The arguments ``-f name'` or ``--file=name'` tell `make` to read the file name as the makefile. If you use more than one ``-f'` or ``--file'` 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'` or ``--file'`.

## 3.3 Including Other Makefiles

The `include` directive tells `make` to suspend reading the current makefile and read one or more other makefiles before continuing. The directive is a line in the makefile that looks like this:

    include filenames...

filenames can contain shell file name patterns.

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 the file names, and between file names; 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 the file names contain any variable or function references, they are expanded. See section 6. How to Use Variables.

For example, if you have three ``.mk'` files, ``a.mk'`, ``b.mk'`, and ``c.mk'`, and `$(bar)` expands to `bish bash`, then the following expression

    include foo *.mk $(bar)

is equivalent to

    include foo a.mk b.mk c.mk bish bash

When `make` processes an `include` directive, it suspends reading of the containing makefile and reads from each listed file in turn. 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 (see section 6.5 Setting Variables) or pattern rules (see section 10.5 Defining and Redefining Pattern Rules).

Another such occasion is when you want to generate dependencies from source files automatically; the dependencies can be put in a file that is included by the main makefile. This practice is generally cleaner than that of somehow appending the dependencies to the end of the main makefile as has been traditionally done with other versions of `make`. See section 4.12 Generating Dependencies Automatically.

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'` or ``--include-dir'` option are searched (see section 9.7 Summary of Options). Then the following directories (if they exist) are searched, in this order: ``prefix/include'` (normally ``/usr/local/include'` (1)) ``/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 an immediately fatal error; processing of the makefile containing the `include` continues. Once it has finished reading makefiles, `make` will try to remake any that are out of date or don't exist. See section 3.5 How Makefiles Are Remade. Only after it has tried to find a way to remake a makefile and failed, will `make` diagnose the missing makefile as a fatal error.

If you want `make` to simply ignore a makefile which does not exist and cannot be remade, with no error message, use the `-include` directive instead of `include`, like this:

    -include filenames...

This is acts like `include` in every way except that there is no error (not even a warning) if any of the filenames do not exist. For compatibility with some other `make` implementations, `sinclude` is another name for `-include`.

## 3.4 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 (see section 3.3 Including Other Makefiles). In addition, the default goal is never taken from one of these makefiles and it is not an error if the files listed in `MAKEFILES` are not found.

The main use of `MAKEFILES` is in communication between recursive invocations of `make` (see section 5.6 Recursive Use of `make`). It usually is not 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 (see section 4.3 Searching Directories for Dependencies).

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. See section 3.3 Including Other Makefiles.

## 3.5 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 (see section 10. Using Implicit Rules), 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 a double-colon rule to remake a file with commands but no dependencies, that file will always be remade (see section 4.11 Double-Colon Rules). In the case of makefiles, a makefile that has a double-colon rule with 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 double-colon targets but have no dependencies.

If you do not specify any makefiles to be read with ``-f'` or ``--file'` options, `make` will try the default makefile names; see section 3.2 What Name to Give Your Makefile. Unlike makefiles explicitly requested with ``-f'` or ``--file'` 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 (see section 3.2 What Name to Give Your Makefile) until it succeeds in making one, or it runs out of names to try. Note that it is not an error if `make` cannot find or make any makefile; a makefile is not always necessary.

When you use the ``-t'` or ``--touch'` option (see section 9.3 Instead of Executing the Commands), 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'` (or ``--question'`) and ``-n'` (or ``--just-print'`) 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'`.

## 3.6 Overriding Part of 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 a match-anything pattern rule to say that to remake any target that cannot be made from the information in the containing makefile, `make` should look in another makefile. See section 10.5 Defining and Redefining Pattern Rules, for more information on pattern rules.

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

    %: force
            @$(MAKE) -f Makefile $@
    force: ;

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 the pattern rule: ``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.

The way this works is that the pattern rule has a pattern of just ``%'`, so it matches any target whatever. The rule specifies a dependency ``force'`, to guarantee that the commands will be run even if the target file already exists. We give ``force'` target empty commands to prevent `make` from searching for an implicit rule to build it--otherwise it would apply the same match-anything rule to ``force'` itself and create a dependency loop!

Go to the first, previous, next, last section, table of contents.