diff options
Diffstat (limited to 'make.texinfo')
| -rw-r--r-- | make.texinfo | 227 |
1 files changed, 169 insertions, 58 deletions
diff --git a/make.texinfo b/make.texinfo index 14b38fc..25c7ec9 100644 --- a/make.texinfo +++ b/make.texinfo @@ -37,7 +37,7 @@ and issues the commands to recompile them. This is Edition @value{EDITION}, last updated @value{UPDATED}, of @cite{The GNU Make Manual}, for @code{make}, Version @value{VERSION}. -Copyright (C) 1988, '89, '90, '91, '92, '93, '94, '95, '96 +Copyright (C) 1988, '89, '90, '91, '92, '93, '94, '95, '96, '97 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of @@ -264,7 +264,7 @@ Functions for Transforming Text * Syntax of Functions:: How to write a function call. * Text Functions:: General-purpose text manipulation functions. -* Filename Functions:: Functions for manipulating file names. +* File Name Functions:: Functions for manipulating file names. * Foreach Function:: Repeat some text with controlled variation. * Origin Function:: Find where a variable got its value. * Shell Function:: Substitute the output of a shell command. @@ -1102,6 +1102,8 @@ makefile as has been traditionally done with other versions of @cindex @code{-I} @cindex @code{--include-dir} +@cindex included makefiles, default directries +@cindex default directries for included makefiles @findex /usr/gnu/include @findex /usr/local/include @findex /usr/include @@ -1112,7 +1114,10 @@ First, any directories you have specified with the @samp{-I} or (@pxref{Options Summary, ,Summary of Options}). Then the following directories (if they exist) are searched, in this order: -@file{@var{prefix}/include} (normally @file{/usr/local/include}) +@file{@var{prefix}/include} (normally @file{/usr/local/include} +@footnote{GNU Make compiled for MS-DOS and MS-Windows behaves as if +@var{prefix} has been defined to be the root of the DJGPP tree +hierarchy.}) @file{/usr/gnu/include}, @file{/usr/local/include}, @file{/usr/include}. @@ -1464,7 +1469,10 @@ significance. If alone, or followed by a slash, it represents your home directory. For example @file{~/bin} expands to @file{/home/you/bin}. If the @samp{~} is followed by a word, the string represents the home directory of the user named by that word. For example @file{~john/bin} -expands to @file{/home/john/bin}.@refill +expands to @file{/home/john/bin}. On systems which don't have a home +directory for each user (such as MS-DOS or MS-Windows), this +functionality can be simulated by setting the environment variable +@var{HOME}.@refill Wildcard expansion happens automatically in targets, in dependencies, and in commands (where the shell does the expansion). In other @@ -1578,6 +1586,24 @@ expansion, but you need more sophisticated techniques, including the These are described in the following section. @end iftex +@cindex wildcards and MS-DOS/MS-Windows backslashes +@cindex backslashes in pathnames and wildcard expansion + +Microsoft operating systems (MS-DOS and MS-Windows) use backslashes to +separate directories in pathnames, like so: + +@example + c:\foo\bar\baz.c +@end example + +This is equivalent to the Unix-style @file{c:/foo/bar/baz.c} (the +@file{c:} part is the so-called drive letter). When @code{make} runs on +these systems, it supports backslashes as well as the Unix-style forward +slashes in pathnames. However, this support does @emph{not} include the +wildcard expansion, where backslash is a quote character. Therefore, +you @emph{must} use Unix-style slashes in these cases. + + @node Wildcard Function, , Wildcard Pitfall, Wildcards @subsection The Function @code{wildcard} @findex wildcard @@ -1676,13 +1702,15 @@ Thus, if a file that is listed as a target or dependency does not exist in the current directory, @code{make} searches the directories listed in @code{VPATH} for a file with that name. If a file is found in one of them, that file may become the dependency (see below). Rules may then -specify the names of source files in the dependencies as if they all +specify the names of files in the dependency list as if they all existed in the current directory. @xref{Commands/Search, ,Writing Shell Commands with Directory Search}. In the @code{VPATH} variable, directory names are separated by colons or blanks. The order in which directories are listed is the order followed -by @code{make} in its search. +by @code{make} in its search. (On MS-DOS and MS-Windows, semi-colons +are used as separators of directory names in @code{VPATH}, since the +colon can be used in the pathname itself, after the drive letter.) For example, @@ -1715,11 +1743,12 @@ is found in the directory @file{src}. @subsection The @code{vpath} Directive @findex vpath -Similar to the @code{VPATH} variable but more selective is the @code{vpath} -directive (note lower case), which allows you to specify a search path for a particular class -of file names, those that match a particular pattern. Thus you can supply -certain search directories for one class of file names and other directories -(or none) for other file names. +Similar to the @code{VPATH} variable, but more selective, is the +@code{vpath} directive (note lower case), which allows you to specify a +search path for a particular class of file names: those that match a +particular pattern. Thus you can supply certain search directories for +one class of file names and other directories (or none) for other file +names. There are three forms of the @code{vpath} directive: @@ -1729,8 +1758,8 @@ Specify the search path @var{directories} for file names that match @var{pattern}. The search path, @var{directories}, is a list of directories to be -searched, separated by colons or blanks, just like the search path used -in the @code{VPATH} variable. +searched, separated by colons (semi-colons on MS-DOS and MS-Windows) or +blanks, just like the search path used in the @code{VPATH} variable. @item vpath @var{pattern} Clear out the search path associated with @var{pattern}. @@ -1817,7 +1846,7 @@ will look for a file ending in @samp{.c} in @file{foo}, then When a dependency is found through directory search, regardless of type (general or selective), the pathname located may not be the one that -@code{make} actually provides you in the dependency list. Sometimes, +@code{make} actually provides you in the dependency list. Sometimes the path discovered through directory search is thrown away. The algorithm @code{make} uses to decide whether to keep or abandon a @@ -1829,7 +1858,7 @@ If a target file does not exist at the path specified in the makefile, directory search is performed. @item -If the directory search is successful that path is kept, and this file +If the directory search is successful, that path is kept and this file is tentatively stored as the target. @item @@ -1843,17 +1872,20 @@ rebuilt: @item If the target does @emph{not} need to be rebuilt, the path to the file found during directory search is used for any dependency lists which -contain this target. +contain this target. In short, if @code{make} doesn't need to rebuild +the target then you use the path found via directory search. @item If the target @emph{does} need to be rebuilt (is out-of-date), the pathname found during directory search is @emph{thrown away}, and the -target is rebuilt using the filename specified in the makefile. +target is rebuilt using the file name specified in the makefile. In +short, if @code{make} must rebuild, then the target is rebuilt locally, +not in the directory found via directory search. @end enumerate @end enumerate -This may seem overly complex, but in fact it is almost always exactly -what you want. +This algorithm may seem complex, but in practice it is quite often +exactly what you want. @cindex traditional directory search @cindex directory search, traditional @@ -1958,7 +1990,9 @@ handles it specially by searching for the file @file{lib@var{name}.a} in the current directory, in directories specified by matching @code{vpath} search paths and the @code{VPATH} search path, and then in the directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib} -(normally @file{/usr/local/lib}). +(normally @file{/usr/local/lib}, but MS-DOS/MS-Windows versions of +@code{make} behave as if @var{prefix} is defined to be the root of the +DJGPP installation tree). For example, @@ -2834,13 +2868,15 @@ by making a new subshell for each line. (In practice, @code{make} may take shortcuts that do not affect the results.) @cindex @code{cd} (shell command) -@strong{Please note:} this implies that shell commands such as -@code{cd} that set variables local to each process will not affect the -following command lines. If you want to use @code{cd} to affect the -next command, put the two on a single line with a semicolon between -them. Then @code{make} will consider them a single command and pass -them, together, to a shell which will execute them in sequence. For -example: +@strong{Please note:} this implies that shell commands such as @code{cd} +that set variables local to each process will not affect the following +command lines. @footnote{On MS-DOS, the value of current working +directory is @strong{global}, so changing it @emph{will} affect the +following command lines on those systems.} If you want to use @code{cd} +to affect the next command, put the two on a single line with a +semicolon between them. Then @code{make} will consider them a single +command and pass them, together, to a shell which will execute them in +sequence. For example: @example foo : bar/lose @@ -2871,13 +2907,75 @@ foo : bar/lose The program used as the shell is taken from the variable @code{SHELL}. By default, the program @file{/bin/sh} is used. +@vindex COMSPEC +On MS-DOS, if @code{SHELL} is not set, the value of the variable +@code{COMSPEC} (which is always set) is used instead. + +@cindex @code{SHELL}, MS-DOS specifics +The processing of lines that set the variable @code{SHELL} in Makefiles +is different on MS-DOS. The stock shell, @file{command.com}, is +ridiculously limited in its functionality and many users of @code{make} +tend to install a replacement shell. Therefore, on MS-DOS, @code{make} +examines the value of @code{SHELL}, and changes its behavior based on +whether it points to a Unix-style or DOS-style shell. This allows +reasonable functionality even if @code{SHELL} points to +@file{command.com}. + +If @code{SHELL} points to a Unix-style shell, @code{make} on MS-DOS +additionally checks whether that shell can indeed be found; if not, it +ignores the line that sets @code{SHELL}. In MS-DOS, GNU @code{make} +searches for the shell in the following places: + +@enumerate +@item +In the precise place pointed to by the value of @code{SHELL}. For +example, if the makefile specifies @samp{SHELL = /bin/sh}, @code{make} +will look in the directory @file{/bin} on the current drive. + +@item +In the current directory. + +@item +In each of the directories in the @code{PATH} variable, in order. + +@end enumerate + +In every directory it examines, @code{make} will first look for the +specific file (@file{sh} in the example above). If this is not found, +it will also look in that directory for that file with one of the known +extensions which identify executable files. For example @file{.exe}, +@file{.com}, @file{.bat}, @file{.btm}, @file{.sh}, and some others. + +If any of these attempts is successful, the value of @code{SHELL} will +be set to the full pathname of the shell as found. However, if none of +these is found, the value of @code{SHELL} will not be changed, and thus +the line that sets it will be effectively ignored. This is so +@code{make} will only support features specific to a Unix-style shell if +such a shell is actually installed on the system where @code{make} runs. + +Note that this extended search for the shell is limited to the cases +where @code{SHELL} is set from the Makefile; if it is set in the +environment or command line, you are expected to set it to the full +pathname of the shell, exactly as things are on Unix. + +The effect of the above DOS-specific processing is that a Makefile that +says @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work +on MS-DOS unaltered if you have e.g. @file{sh.exe} installed in some +directory along your @code{PATH}. + @cindex environment, @code{SHELL} in Unlike most variables, the variable @code{SHELL} is never set from the environment. This is because the @code{SHELL} environment variable is used to specify your personal choice of shell program for interactive -use. It would be very bad for personal choices like this to affect -the functioning of makefiles. @xref{Environment, ,Variables from the -Environment}. +use. It would be very bad for personal choices like this to affect the +functioning of makefiles. @xref{Environment, ,Variables from the +Environment}. However, on MS-DOS and MS-Windows the value of +@code{SHELL} in the environment @strong{is} used, since on those systems +most users do not set this variable, and therefore it is most likely set +specifically to be used by @code{make}. On MS-DOS, if the setting of +@code{SHELL} is not suitable for @code{make}, you can set the variable +@code{MAKESHELL} to the shell that @code{make} should use; this will +override the value of @code{SHELL}. @node Parallel, Errors, Execution, Commands @section Parallel Execution @@ -2894,6 +2992,9 @@ for it to finish before executing the next. However, the @samp{-j} or @samp{--jobs} option tells @code{make} to execute many commands simultaneously.@refill +On MS-DOS, the @samp{-j} option has no effect, since that system doesn't +support multi-processing. + If the @samp{-j} option is followed by an integer, this is the number of commands to execute at once; this is called the number of @dfn{job slots}. If there is nothing looking like an integer after the @samp{-j} option, @@ -3110,7 +3211,7 @@ subdirectory. You can do it by writing this: @example subsystem: - cd subdir; $(MAKE) + cd subdir && $(MAKE) @end example @noindent @@ -3146,13 +3247,13 @@ not the explicit command name @samp{make}, as shown here: @example @group subsystem: - cd subdir; $(MAKE) + cd subdir && $(MAKE) @end group @end example The value of this variable is the file name with which @code{make} was invoked. If this file name was @file{/bin/make}, then the command executed -is @samp{cd subdir; /bin/make}. If you use a special version of +is @samp{cd subdir && /bin/make}. If you use a special version of @code{make} to run the top-level makefile, the same special version will be executed for recursive invocations. @cindex @code{cd} (shell command) @@ -3169,7 +3270,7 @@ Consider the command @samp{make -t} in the above example. (The any commands; see @ref{Instead of Execution}.) Following the usual definition of @samp{-t}, a @samp{make -t} command in the example would create a file named @file{subsystem} and do nothing else. What you -really want it to do is run @samp{@w{cd subdir;} @w{make -t}}; but that would +really want it to do is run @samp{@w{cd subdir &&} @w{make -t}}; but that would require executing the command, and @samp{-t} says not to execute commands.@refill @cindex @code{-t}, and recursion @@ -3420,7 +3521,7 @@ value of @code{MAKEFLAGS}, like this: @example subsystem: - cd subdir; $(MAKE) MAKEFLAGS= + cd subdir && $(MAKE) MAKEFLAGS= @end example @vindex MAKEOVERRIDES @@ -3459,7 +3560,7 @@ this: @example subsystem: - cd subdir; $(MAKE) $(MFLAGS) + cd subdir && $(MAKE) $(MFLAGS) @end example @noindent @@ -4585,7 +4686,9 @@ Such problems would be especially likely with the variable @code{SHELL}, which is normally present in the environment to specify the user's choice of interactive shell. It would be very undesirable for this choice to affect @code{make}. So @code{make} ignores the environment value of -@code{SHELL}.@refill +@code{SHELL} (except on MS-DOS and MS-Windows, where @code{SHELL} is +usually not set. @xref{Execution, ,Special handling of SHELL on +MS-DOS}.)@refill @node Conditionals, Functions, Using Variables, Top @chapter Conditional Parts of Makefiles @@ -4882,7 +4985,7 @@ call, just as a variable might be substituted. @menu * Syntax of Functions:: How to write a function call. * Text Functions:: General-purpose text manipulation functions. -* Filename Functions:: Functions for manipulating file names. +* File Name Functions:: Functions for manipulating file names. * Foreach Function:: Repeat some text with controlled variation. * Origin Function:: Find where a variable got its value. * Shell Function:: Substitute the output of a shell command. @@ -4951,7 +5054,7 @@ bar:= $(subst $(space),$(comma),$(foo)) Here the @code{subst} function replaces each space with a comma, through the value of @code{foo}, and substitutes the result. -@node Text Functions, Filename Functions, Syntax of Functions, Functions +@node Text Functions, File Name Functions, Syntax of Functions, Functions @section Functions for String Substitution and Analysis @cindex functions, for text @@ -5215,7 +5318,7 @@ used so that the new value is assigned even if the previous value of @code{CFLAGS} was specified with a command argument (@pxref{Override Directive, , The @code{override} Directive}). -@node Filename Functions, Foreach Function, Text Functions, Functions +@node File Name Functions, Foreach Function, Text Functions, Functions @section Functions for File Names @cindex functions, for file names @cindex file name functions @@ -5282,11 +5385,11 @@ file names. For example, @example -$(suffix src/foo.c hacks) +$(suffix src/foo.c src-1.0/bar.c hacks) @end example @noindent -produces the result @samp{.c}. +produces the result @samp{.c .c}. @item $(basename @var{names}@dots{}) @findex basename @@ -5294,15 +5397,16 @@ produces the result @samp{.c}. @cindex file name, basename of Extracts all but the suffix of each file name in @var{names}. If the file name contains a period, the basename is everything starting up to -(and not including) the last period. Otherwise, the basename is the -entire file name. For example, +(and not including) the last period. Periods in the directory part are +ignored. If there is no period, the basename is the entire file name. +For example, @example -$(basename src/foo.c hacks) +$(basename src/foo.c src-1.0/bar hacks) @end example @noindent -produces the result @samp{src/foo hacks}. +produces the result @samp{src/foo src-1.0/bar hacks}. @c plural convention with dots (be consistent) @item $(addsuffix @var{suffix},@var{names}@dots{}) @@ -5429,7 +5533,7 @@ that match the pattern. @xref{Wildcards, ,Using Wildcard Characters in File Names}. @end table -@node Foreach Function, Origin Function, Filename Functions, Functions +@node Foreach Function, Origin Function, File Name Functions, Functions @section The @code{foreach} Function @findex foreach @cindex words, iterating over @@ -6197,6 +6301,7 @@ argument, @code{make} runs as many jobs simultaneously as possible. If there is more than one @samp{-j} option, the last one is effective. @xref{Parallel, ,Parallel Execution}, for more information on how commands are run. +Note that this option is ignored on MS-DOS. @item -k @cindex @code{-k} @@ -7355,7 +7460,7 @@ variants that get just the file's directory name or just the file name within the directory. The variant variables' names are formed by appending @samp{D} or @samp{F}, respectively. These variants are semi-obsolete in GNU @code{make} since the functions @code{dir} and -@code{notdir} can be used to get a similar effect (@pxref{Filename +@code{notdir} can be used to get a similar effect (@pxref{File Name Functions, , Functions for File Names}). Note, however, that the @samp{F} variants all omit the trailing slash which always appears in the output of the @code{dir} function. Here is a table of the variants: @@ -8529,43 +8634,43 @@ Sort the words in @var{list} lexicographically, removing duplicates.@* @item $(dir @var{names}@dots{}) Extract the directory part of each file name.@* -@xref{Filename Functions, ,Functions for File Names}. +@xref{File Name Functions, ,Functions for File Names}. @item $(notdir @var{names}@dots{}) Extract the non-directory part of each file name.@* -@xref{Filename Functions, ,Functions for File Names}. +@xref{File Name Functions, ,Functions for File Names}. @item $(suffix @var{names}@dots{}) Extract the suffix (the last @samp{.} and following characters) of each file name.@* -@xref{Filename Functions, ,Functions for File Names}. +@xref{File Name Functions, ,Functions for File Names}. @item $(basename @var{names}@dots{}) Extract the base name (name without suffix) of each file name.@* -@xref{Filename Functions, ,Functions for File Names}. +@xref{File Name Functions, ,Functions for File Names}. @item $(addsuffix @var{suffix},@var{names}@dots{}) Append @var{suffix} to each word in @var{names}.@* -@xref{Filename Functions, ,Functions for File Names}. +@xref{File Name Functions, ,Functions for File Names}. @item $(addprefix @var{prefix},@var{names}@dots{}) Prepend @var{prefix} to each word in @var{names}.@* -@xref{Filename Functions, ,Functions for File Names}. +@xref{File Name Functions, ,Functions for File Names}. @item $(join @var{list1},@var{list2}) Join two parallel lists of words.@* -@xref{Filename Functions, ,Functions for File Names}. +@xref{File Name Functions, ,Functions for File Names}. @item $(word @var{n},@var{text}) Extract the @var{n}th word (one-origin) of @var{text}.@* -@xref{Filename Functions, ,Functions for File Names}. +@xref{File Name Functions, ,Functions for File Names}. @item $(words @var{text}) Count the number of words in @var{text}.@* -@xref{Filename Functions, ,Functions for File Names}. +@xref{File Name Functions, ,Functions for File Names}. @item $(firstword @var{names}@dots{}) Extract the first word of @var{names}.@* -@xref{Filename Functions, ,Functions for File Names}. +@xref{File Name Functions, ,Functions for File Names}. @item $(wildcard @var{pattern}@dots{}) Find file names matching a shell file name pattern (@emph{not} a @@ -8669,6 +8774,12 @@ The name of the system default command interpreter, usually @file{/bin/sh}. You can set @code{SHELL} in the makefile to change the shell used to run commands. @xref{Execution, ,Command Execution}. +@item MAKESHELL + +On MS-DOS only, the name of the command interpreter that is to be used +by @code{make}. This value takes precedence over the value of +@code{SHELL}. @xref{Execution, ,MAKESHELL variable}. + @item MAKE The name with which @code{make} was invoked. |