@c ISPELL CHECK: done, 10 June 1993 --roland
@c ISPELL CHECK: done, 2000-06-25 --Martin Buchholz
-
+@c ISPELL CHECK: done, 2023-08-30 --pds
@dircategory Software development
@direntry
Our examples show C programs, since they are most common, but you can use
@code{make} with any programming language whose compiler can be run with a
-shell command. Indeed, @code{make} is not limited to programs. You can
-use it to describe any task where some files must be updated automatically
+shell command. Indeed, @code{make} is not limited to building programs. You
+can use it to describe any task where some files must be updated automatically
from others whenever the others change.
@menu
@heading Preparing and Running Make
@end ifnottex
-To prepare to use @code{make}, you must write a file called
-the @dfn{makefile} that describes the relationships among files
-in your program and provides commands for updating each file.
-In a program, typically, the executable file is updated from object
-files, which are in turn made by compiling source files.
+To use @code{make}, you must write a file called the @dfn{makefile} that
+describes the relationships among files in your program and provides commands
+for updating each file. For example, in a typical program 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:
@noindent
suffices to perform all necessary recompilations. The @code{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 recipes recorded in the data base.
+uses the information in the makefile 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 recipes provided in the makefile.
You can provide command line arguments to @code{make} to control which
files should be recompiled, or how. @xref{Running, ,How to Run
@end iftex
If you are familiar with other @code{make} programs, see @ref{Features,
-,Features of GNU @code{make}}, which lists the enhancements GNU
-@code{make} has, and @ref{Missing, ,Incompatibilities and Missing
-Features}, which explains the few things GNU @code{make} lacks that
-others have.
+,Features of GNU @code{make}}, which lists the enhancements GNU Make has, and
+@ref{Missing, ,Incompatibilities and Missing Features}, which explains the few
+things GNU Make lacks that others have.
For a quick summary, see @ref{Options Summary}, @ref{Quick Reference},
and @ref{Special Targets}.
In addition to the information above, please be careful to include the
version number of @code{make} you are using. You can get this
information with the command @samp{make --version}. Be sure also to
-include the type of machine and operating system you are using. One
-way to obtain this information is by looking at the final lines of
-output from the command @samp{make --help}.
+include the type of machine and operating system you are using.
If you have a code change you'd like to submit, see the @file{README} file
section ``Submitting Patches'' for information.
@comment node-name, next, previous, up
@chapter An Introduction to Makefiles
-You need a file called a @dfn{makefile} to tell @code{make} what to do.
-Most often, the makefile tells @code{make} how to compile and link a
+You need a file called a @dfn{makefile} to tell @code{make} what to do. For
+example, the makefile might tell @code{make} how to compile and link a
program.
@cindex makefile
+A makefile is a combination of two different ``languages'' in a single file.
+Most of the makefile is written to be parsed by @code{make}, but also included
+in the makefile are @emph{recipes} which contain the commands used to update
+targets. These commands are passed to a shell to be parsed and run so they
+use shell syntax, not @code{make} syntax. It's important to keep in mind the
+difference between these two syntaxes when writing makefiles.
+
+For a detailed description of the content of makefiles, @pxref{Makefile
+Contents, ,What Makefiles Contain}.
+
+A makefile is not a procedural list of steps to be taken. Instead, it
+describes a @dfn{directed acyclic graph}, where each node in the graph is a
+potential target to be created and each edge in the graph is a prerequisite
+relationship. Every rule in a makefile defines (or updates) a node and
+(optionally) some of the edges starting from that node.
+
In this chapter, we will discuss a simple makefile that describes how to
compile and link a text editor which consists of eight C source files
and three header files. The makefile can also tell @code{make} how to
make clean
@end example
-In the example makefile, the targets include the executable file
-@samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}. The
-prerequisites are files such as @samp{main.c} and @samp{defs.h}.
-In fact, each @samp{.o} file is both a target and a prerequisite.
-Recipes include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}.
+In the example makefile, the targets include the executable file @samp{edit},
+and the object files @samp{main.o}, @samp{kbd.o}, etc. The prerequisites are
+files such as @samp{main.c} and @samp{defs.h}. You can see that each
+@samp{.o} file is both a target and a prerequisite: this is common in
+makefiles. Recipes include @w{@samp{cc -c main.c}} and @w{@samp{cc -c
+kbd.c}}.
-When a target is a file, it needs to be recompiled or relinked if any
-of its prerequisites change. In addition, any prerequisites that are
-themselves automatically generated should be updated first. In this
-example, @file{edit} depends on each of the eight object files; the
-object file @file{main.o} depends on the source file @file{main.c} and
-on the header file @file{defs.h}.
+When a target is a program, it needs to be recompiled or relinked if any of
+its prerequisites change. In addition, any prerequisites that are themselves
+automatically generated should be updated first. In this example, @file{edit}
+depends on the eight object files; the object file @file{main.o} depends on
+the source file @file{main.c} and on the header file @file{defs.h}.
A recipe may follow each line that contains a target and
prerequisites. These recipes say how to update the target file. A
After the first expansion phase the prerequisites list of the
@file{myfile} target will be @code{onefile} and @code{$(TWOVAR)}; the
-first (unescaped) variable reference to @var{ONEVAR} is expanded,
-while the second (escaped) variable reference is simply unescaped,
+first (un-escaped) variable reference to @var{ONEVAR} is expanded,
+while the second (escaped) variable reference is simply un-escaped,
without being recognized as a variable reference. Now during the
secondary expansion the first word is expanded again but since it
contains no variable or function references it remains the value
Obviously, this is not a very interesting case since the same result
could more easily have been achieved simply by having both variables
-appear, unescaped, in the prerequisites list. One difference becomes
+appear, un-escaped, in the prerequisites list. One difference becomes
apparent if the variables are reset; consider this example:
@example
@item p (@i{print})
Prints the recipe to be executed, even when the recipe is normally
-silent (due to @code{.SILENT} or @samp{@@}). Also prints the makefile
-name and line number where the recipe was defined.
+silent (due to @code{.SILENT} or @samp{@@}).
@item w (@i{why})
Explains why each target must be remade by showing which prerequisites
the jobserver.
As an example, suppose you are implementing a linker which provides
-for multithreaded operation. You would like to enhance the linker so
+for multi-threaded operation. You would like to enhance the linker so
that if it is invoked by GNU @code{make} it can participate in the
jobserver protocol to control how many threads are used during link.
First you will need to modify the linker to determine if the
projects / thirdparty / make.git / commitdiff
