[BACK]Return to make.1 CVS log [TXT][DIR] Up to [local] / src / usr.bin / make

Diff for /src/usr.bin/make/make.1 between version 1.94 and 1.95

version 1.94, 2012/09/21 07:55:20 version 1.95, 2012/10/02 10:18:37
Line 38 
Line 38 
 .Nd maintain program dependencies  .Nd maintain program dependencies
 .Sh SYNOPSIS  .Sh SYNOPSIS
 .Nm make  .Nm make
 .Op Fl BeiknPqrSst  .Op Fl BeiknpqrSst
 .Op Fl D Ar variable  .Op Fl D Ar variable
 .Op Fl d Ar flags  .Op Fl d Ar flags
 .Op Fl f Ar makefile  .Op Fl f Ar makefile
 .Op Fl I Ar directory  .Op Fl I Ar directory
 .Op Fl j Ar max_jobs  .Op Fl j Ar max_processes
 .Op Fl m Ar directory  .Op Fl m Ar directory
 .Op Fl V Ar variable  .Op Fl V Ar variable
 .Op Ar NAME Ns = Ns Ar value  .Op Ar NAME Ns = Ns Ar value
Line 53 
Line 53 
 .Sh DESCRIPTION  .Sh DESCRIPTION
 .Nm  .Nm
 is a program designed to simplify the maintenance of other programs.  is a program designed to simplify the maintenance of other programs.
 Its input is a list of specifications as to the files upon which programs  Its input is a
 and other files depend.  .Ar makefile :
 If the file  a list of specifications (target rules) describing creation
 .Sq Pa BSDmakefile  relationships between programs and other files.
 exists, it is read for this list of specifications.  By default, this
 If it does not exist, the files  .Ar makefile
   is determined as follows:
   first the file
   .Sq Pa BSDmakefile ,
   if it exists, then the files
 .Sq Pa makefile  .Sq Pa makefile
 and  and
 .Sq Pa Makefile  .Sq Pa Makefile ,
 are tried in order.  in that order.
 If the file  If none of these files exist,
   .Nm
   can still rely on a set of built-in system rules.
   .Pp
   In addition, if the file
 .Sq Pa .depend  .Sq Pa .depend
 exists, it is read in addition to the makefile (see  exists, it is also read on top of the main
   .Ar makefile
   (see
 .Xr mkdep 1 ) .  .Xr mkdep 1 ) .
 .Pp  .Pp
 The handling of  The handling of
Line 80 
Line 90 
 Specify that environment variables override macro assignments within  Specify that environment variables override macro assignments within
 makefiles.  makefiles.
 .It Fl f Ar makefile  .It Fl f Ar makefile
 Specify a makefile to read instead of the default  Specify a makefile to read instead of the default.
 .Sq Pa makefile  
 and  
 .Sq Pa Makefile .  
 If  If
 .Ar makefile  .Ar makefile
 is  is
Line 101 
Line 108 
 .It Fl n  .It Fl n
 Display the commands that would have been executed, but do not actually  Display the commands that would have been executed, but do not actually
 execute them.  execute them.
   .It Fl p
   Print a dump of the target rules and variables on stdout.
   Do not build anything.
 .It Fl q  .It Fl q
 Do not execute any commands, but exit with status 0 if the specified targets  Do not execute any commands, but exit with status 0 if the specified targets
 are up-to-date, and 1 otherwise.  are up-to-date, and 1 otherwise.
Line 130 
Line 140 
 Extended options are as follows:  Extended options are as follows:
 .Bl -tag -width Ds  .Bl -tag -width Ds
 .It Fl B  .It Fl B
 Try to be backwards compatible by executing a single shell per command and  Try to be backwards compatible by executing the commands to make
 by executing the commands to make the sources of a dependency line in sequence.  the prerequisites in a target rule in sequence.
 This is turned on by default unless  This is the default, in the absence of
 .Fl j  .Fl j Ar max_processes .
 is used.  
 .It Fl D Ar variable  .It Fl D Ar variable
 Define  Define
 .Ar variable  .Ar variable
Line 156 
Line 165 
 .It Ar d  .It Ar d
 Print debugging information about directory searching and caching.  Print debugging information about directory searching and caching.
 .It Ar e  .It Ar e
 Print debugging information about expensive jobs heuristics.  Print debugging information about expensive command heuristics.
 .It Ar f  .It Ar f
 Print debugging information about the expansion of for loops.  Print debugging information about the expansion of for loops.
 .It Ar "g1"  .It Ar "g1"
Line 165 
Line 174 
 Print the input graph after making everything, or before exiting  Print the input graph after making everything, or before exiting
 on error.  on error.
 .It Ar j  .It Ar j
 Print debugging information about external jobs forked.  Print debugging information about forking processes to run commands.
 .It Ar l  .It Ar l
 Print commands in Makefile targets regardless of whether or not they are  Print commands in Makefile targets regardless of whether or not they are
 prefixed by @.  prefixed by @.
Line 186 
Line 195 
 .Va RANDOM_DELAY  .Va RANDOM_DELAY
 is defined,  is defined,
 .Nm  .Nm
 will wait between 0 and ${RANDOM_DELAY} seconds at the start of each job.  will wait between 0 and ${RANDOM_DELAY} seconds before starting a command.
 A given random seed can be forced by setting  A given random seed can be forced by setting
 .Va RANDOM_SEED ,  .Va RANDOM_SEED ,
 but this does not guarantee reproductibility.  but this does not guarantee reproductibility.
Line 206 
Line 215 
 The system makefile directory (or directories, see the  The system makefile directory (or directories, see the
 .Fl m  .Fl m
 option) is automatically included as part of this list.  option) is automatically included as part of this list.
 .It Fl j Ar max_jobs  .It Fl j Ar max_processes
 Specify the maximum number of jobs that  Specify the maximum number of processes that
 .Nm  .Nm
 may have running at any one time.  may have running at any one time.
 Turns compatibility mode off, unless the  
 .Fl B  
 flag is also specified.  
 .It Fl m Ar directory  .It Fl m Ar directory
 Specify a directory in which to search for  Specify a directory in which to search for
 .Pa sys.mk  .Pa sys.mk
Line 225 
Line 231 
 for "..."-style inclusions (see the  for "..."-style inclusions (see the
 .Fl I  .Fl I
 option).  option).
 .It Fl P  
 Collate the output of a given job and display it only when the job finishes,  
 instead of mixing the output of parallel jobs together.  
 This option has no effect unless  
 .Fl j  
 is used too.  
 .It Fl V Ar variable  .It Fl V Ar variable
 Print  Print
 .Nm make Ns 's  .Nm make Ns 's
Line 242 
Line 242 
 with a blank line for each null or undefined variable.  with a blank line for each null or undefined variable.
 .El  .El
 .Pp  .Pp
 There are seven different types of lines in a makefile: file dependency  There are seven different types of lines in a makefile: dependency
 specifications, shell commands, variable assignments, include statements,  lines, shell commands, variable assignments, include statements,
 conditional directives, for loops, and comments.  conditional directives, for loops, and comments.
 Of these, include statements, conditional directives and for loops are  Of these, include statements, conditional directives and for loops are
 extensions.  extensions.
 .Pp  .Pp
   A complete target rule is composed of a dependency line,
   followed by a list of shell commands.
   .Pp
 In general, lines may be continued from one line to the next by ending  In general, lines may be continued from one line to the next by ending
 them with a backslash  them with a backslash
 .Pq Ql \e .  .Pq Ql \e .
 The trailing newline character and initial whitespace on the following  The trailing newline character and initial whitespace on the following
 line are compressed into a single space.  line are compressed into a single space.
 .Sh FILE DEPENDENCY SPECIFICATIONS  .Sh DEPENDENCY LINES
 Dependency lines consist of one or more targets, an operator, and zero  Dependency lines consist of one or more targets, an operator, and zero
 or more sources.  or more prerequisites.
 This creates a relationship where the targets  This creates a relationship where the targets
 .Dq depend  .Dq depend
 on the sources  on the prerequisites and are usually created from them.
 and are usually created from them.  The exact relationship between the target and the prerequisite is determined
 The exact relationship between the target and the source is determined  
 by the operator that separates them.  by the operator that separates them.
 Note that the use of several targets is merely a shorthand for duplicate  Note that the use of several targets is merely a shorthand for duplicate
 rules.  rules.
 Specifically,  Specifically,
 .Bd -literal -offset indent  .Bd -literal -offset indent
 target1 target2: depa depb  target1 target2: reqa reqa
         cmd1          cmd1
         cmd2          cmd2
 .Ed  .Ed
 .Pp  .Pp
 is just a short form of  is just a short form of
 .Bd -literal -offset indent  .Bd -literal -offset indent
 target1: depa depb  target1: reqa reqa
         cmd1          cmd1
         cmd2          cmd2
 target2: depa depb  target2: reqa reqa
         cmd1          cmd1
         cmd2          cmd2
 .Ed  .Ed
Line 284 
Line 286 
 .Nm  .Nm
 does not support Solaris syntax for true multiple targets:  does not support Solaris syntax for true multiple targets:
 .Bd -literal -offset indent  .Bd -literal -offset indent
 target1 + target2: depa depb  target1 + target2: reqa reqa
         cmd1          cmd1
         cmd2          cmd2
 .Ed  .Ed
Line 293 
Line 295 
 .Bl -tag -width flag  .Bl -tag -width flag
 .It Ic \&:  .It Ic \&:
 A target is considered out-of-date if its modification time is less than  A target is considered out-of-date if its modification time is less than
 those of any of its sources.  those of any of its prerequisites.
 Sources for a target accumulate over dependency lines when this operator  Prerequisites for a target accumulate over dependency lines
 is used.  when this operator is used.
 The target is removed if  The target is removed if
 .Nm  .Nm
 is interrupted.  is interrupted.
 .It Ic \&!  .It Ic \&!
 Targets are always re-created, but not until all sources have been  Targets are always re-created, but not until all prerequisites have been
 examined and re-created as necessary.  examined and re-created as necessary.
 Sources for a target accumulate over dependency lines when this operator  Prerequisites for a target accumulate over dependency lines when this
 is used.  operator is used.
 The target is removed if  The target is removed if
 .Nm  .Nm
 is interrupted.  is interrupted.
 .It Ic \&::  .It Ic \&::
 If no sources are specified, the target is always re-created.  If no prerequisites are specified, the target is always re-created.
 Otherwise, a target is considered out-of-date if any of its sources has  Otherwise, a target is considered out-of-date if any of its prerequisites has
 been modified more recently than the target.  been modified more recently than the target.
 Sources for a target do not accumulate over dependency lines when this  Prerequisites for a target do not accumulate over dependency lines when this
 operator is used.  operator is used.
 The target will not be removed if  The target will not be removed if
 .Nm  .Nm
Line 325 
Line 327 
 .Ic !\&  .Ic !\&
 operator is a BSD extension.  operator is a BSD extension.
 .Pp  .Pp
 As an extension, targets and sources may contain the shell wildcard  As an extension, targets and prerequisites may contain the shell wildcard
 expressions  expressions
 .Ql \&? ,  .Ql \&? ,
 .Ql * ,  .Ql * ,
Line 338 
Line 340 
 and  and
 .Ql []  .Ql []
 may only be used as part of the final  may only be used as part of the final
 component of the target or source, and must be used to describe existing  component of the target or prerequisite, and must be used to describe existing
 files.  files.
 The expression  The expression
 .Ql {}  .Ql {}
Line 350 
Line 352 
 .Sh SHELL COMMANDS  .Sh SHELL COMMANDS
 Each target may have associated with it a series of shell commands, normally  Each target may have associated with it a series of shell commands, normally
 used to create the target.  used to create the target.
 Each of the commands in this script  While several dependency lines may name the same target, only one of
   these dependency lines should be followed by shell commands, and thus
   define a complete target rule (unless the
   .Sq Ic ::
   operator is used).
   Each of the shell commands in the target rule
 .Em must  .Em must
 be preceded by a tab.  be preceded by a tab.
 While any target may appear on a dependency line, only one of these  
 dependencies may be followed by a creation script, unless the  
 .Sq Ic ::  
 operator is used.  
 .Pp  .Pp
 If a command line begins with a combination of the characters,  If a command line begins with a combination of the characters,
 .Sq Ic @ ,  .Sq Ic @ ,
Line 376 
Line 379 
 (This can be useful to debug recursive Makefiles.)  (This can be useful to debug recursive Makefiles.)
 .El  .El
 .Pp  .Pp
 The command is always executed using  Commands are always executed using
 .Pa /bin/sh  .Pa /bin/sh
 in  in
 .Qq set -e  .Qq set -e
 mode.  mode.
   .Pp
   As an optimization,
   .Nm
   may execute very simple commands without going through an extra shell
   process, as long as this does not change observable behavior.
 .Sh VARIABLE ASSIGNMENTS  .Sh VARIABLE ASSIGNMENTS
 Variables in  Variables in
 .Nm  .Nm
Line 459 
Line 467 
 .It Va \&?  .It Va \&?
 The list of prerequisites for this target that were deemed out-of-date.  The list of prerequisites for this target that were deemed out-of-date.
 .It Va \&<  .It Va \&<
 The name of the source from which this target is to be built, if a valid  The name of the prerequisite from which this target is to be built, if a valid
 implied rule (suffix rule) is in scope.  implied rule (suffix rule) is in scope.
 .It Va *  .It Va *
 The file prefix of the file, containing only the file portion,  The file prefix of the file, containing only the file portion,
Line 505 
Line 513 
 supports the following local variables:  supports the following local variables:
 .Bl -tag -width ".ARCHIVE"  .Bl -tag -width ".ARCHIVE"
 .It Va \&>  .It Va \&>
 The list of all sources for this target.  The list of all prerequisites for this target.
 .It Va .ALLSRC  .It Va .ALLSRC
 Synonym for  Synonym for
 .Sq Va \&> .  .Sq Va \&> .
Line 648 
Line 656 
 List of targets  List of targets
 .Nm  .Nm
 is currently building.  is currently building.
 .It Va .INCLUDES  
 See  
 .Ic .INCLUDES  
 special target.  
 .It Va .LIBS  
 See  
 .Ic .LIBS  
 special target.  
 .It Va MACHINE  .It Va MACHINE
 Name of the machine architecture  Name of the machine architecture
 .Nm  .Nm
Line 1124 
Line 1124 
 .Pq Ql \&#  .Pq Ql \&#
 character, anywhere but in a shell  character, anywhere but in a shell
 command line, and continue to the end of the line.  command line, and continue to the end of the line.
 .Sh SPECIAL SOURCES  .Sh SPECIAL PREREQUISITES
 .Bl -tag -width ".PRECIOUS"  .Bl -tag -width ".PRECIOUS"
 .It Ic .IGNORE  .It Ic .IGNORE
 Ignore any errors from the commands associated with this target, exactly  Ignore any errors from the commands associated with this target, exactly
 as if they all were preceded by a dash  as if they all were preceded by a dash
 .Pq Ql \- .  .Pq Ql \- .
 .It Ic .MADE  
 Mark all sources of this target as being up-to-date.  
 .It Ic .MAKE  
 Execute the commands associated with this target even if the  
 .Fl n  
 or  
 .Fl t  
 options were specified.  
 Can be used to mark recursive  
 .Nm make Ns 's ,  
 prefer standard  
 .Sq Ic + Ns Ar cmd .  
 .It Ic .NOTMAIN  .It Ic .NOTMAIN
 Normally  Normally
 .Nm  .Nm
 selects the first target it encounters as the default target to be built  selects the first target it encounters as the default target to be built
 if no target was specified.  if no target was specified.
 This source prevents this target from being selected.  This prerequisite prevents this target from being selected.
 .It Ic .OPTIONAL  .It Ic .OPTIONAL
 If a target is marked with this attribute and  If a target is marked with this attribute and
 .Nm  .Nm
Line 1157 
Line 1145 
 When  When
 .Nm  .Nm
 is interrupted, it removes any partially made targets.  is interrupted, it removes any partially made targets.
 This source prevents the target from being removed.  This prerequisite prevents the target from being removed.
 .It Ic .SILENT  .It Ic .SILENT
 Do not echo any of the commands associated with this target, exactly  Do not echo any of the commands associated with this target, exactly
 as if they all were preceded by an at sign  as if they all were preceded by an at sign
Line 1166 
Line 1154 
 Turn the target into  Turn the target into
 .Nm make Ns 's  .Nm make Ns 's
 version of a macro.  version of a macro.
 When the target is used as a source for another target, the other target  When the target is used as a prerequisite for another target, the other target
 acquires the commands, sources, and attributes (except for  acquires the commands, prerequisite, and attributes (except for
 .Ic .USE )  .Ic .USE )
 of the  of the
 source.  prerequisite.
 If the target already has commands, the  If the target already has commands, the
 .Ic .USE  .Ic .USE
 target's commands are appended  target's commands are appended
Line 1178 
Line 1166 
 .It Ic .WAIT  .It Ic .WAIT
 If  If
 .Ic .WAIT  .Ic .WAIT
 appears in a dependency line, the sources that precede it are  appears in a dependency line, the prerequisites that precede it are
 made before the sources that succeed it in the line.  made before the prerequisites that follow it in the line.
 Loops are not  Loops are not
 detected and targets that form loops will be silently ignored.  detected and targets that form loops will be silently ignored.
 .El  .El
Line 1199 
Line 1187 
 .It Ic .DEFAULT  .It Ic .DEFAULT
 This is sort of a  This is sort of a
 .Ic .USE  .Ic .USE
 rule for any target (that was used only as a source) that  rule for any target (that was used only as a prerequisite) that
 .Nm  .Nm
 can't figure out any other way to create.  can't figure out any other way to create.
 Uses only the commands.  Uses only the commands.
Line 1215 
Line 1203 
 .It Ic .EXPENSIVE  .It Ic .EXPENSIVE
 In parallel mode, don't scan the commands for  In parallel mode, don't scan the commands for
 .Nm ,  .Nm ,
 assume target is recursive and don't start other jobs until  assume the whole target invokes recursive commands and don't start
 it is finished.  commands for other targets until that target is finished building.
 .It Ic .IGNORE  .It Ic .IGNORE
 Mark each of the sources with the  Mark each of the prerequisites with the
 .Ic .IGNORE  .Ic .IGNORE
 attribute.  attribute.
 If no sources are specified, this is the equivalent of specifying the  If no prerequisites are specified, this is the equivalent of specifying the
 .Fl i  .Fl i
 option.  option.
 .It Ic .INCLUDES  .It Ic .MADE
 A list of suffixes that indicate files that can be included in a source  Mark all prerequisites as being up-to-date.
 file.  .It Ic .MAKE
 The suffix must have already been declared with  Execute the commands associated with this target even if the
 .Ic .SUFFIXES ,  .Fl n
 any suffix so declared will have the directories in its search path (see  or
 .Ic .PATH )  .Fl t
 placed in the  options were specified.
 .Va .INCLUDES  Can be used to mark recursive
 special variable, each preceded by a  .Nm make Ns 's ,
 .Fl I  prefer standard
 flag.  .Sq Ic + Ns Ar cmd .
 .It Ic .INTERRUPT  
 If  
 .Nm  
 is interrupted, the commands for this target will be executed.  
 .It Ic .LIBS  
 This does for libraries what  
 .Ic .INCLUDES  
 does for include files, except that the flag used is  
 .Fl L .  
 .It Ic .MAIN  .It Ic .MAIN
 If no target is specified when  If no target is specified when
 .Nm  .Nm
Line 1277 
Line 1256 
 .\" The named targets are executed in parallel mode. If no targets are  .\" The named targets are executed in parallel mode. If no targets are
 .\" specified, then all targets are executed in parallel mode.  .\" specified, then all targets are executed in parallel mode.
 .It Ic .PATH  .It Ic .PATH
 The sources are directories which are to be searched for files not  The prerequisites are directories which are to be searched for files not
 found in the current directory.  found in the current directory.
 If no sources are specified, any previously specified directories are  If no prerequisites are specified, any previously specified directories are
 deleted.  deleted.
 .It Ic .PATH\fIsuffix\fR  .It Ic .PATH\fIsuffix\fR
 The sources are directories which are to be searched for suffixed files  The prerequisites are directories which are to be searched for suffixed files
 not found in the current directory.  not found in the current directory.
 .Nm  .Nm
 first searches the suffixed search path, before reverting to the default  first searches the suffixed search path, before reverting to the default
Line 1290 
Line 1269 
 .It Ic .PHONY  .It Ic .PHONY
 Apply the  Apply the
 .Ic .PHONY  .Ic .PHONY
 attribute to any specified sources.  attribute to any specified prerequisites.
 Targets with this attribute are always  Targets with this attribute are always
 considered to be out of date.  considered to be out of date.
 .It Ic .PRECIOUS  .It Ic .PRECIOUS
 Apply the  Apply the
 .Ic .PRECIOUS  .Ic .PRECIOUS
 attribute to any specified sources.  attribute to any specified prerequisites.
 If no sources are specified, the  If no prerequisites are specified, the
 .Ic .PRECIOUS  .Ic .PRECIOUS
 attribute is applied to every  attribute is applied to every
 target in the file.  target in the file.
 .It Ic .SILENT  .It Ic .SILENT
 Apply the  Apply the
 .Ic .SILENT  .Ic .SILENT
 attribute to any specified sources.  attribute to any specified prerequisites.
 If no sources are specified, the  If no prerequisites are specified, the
 .Ic .SILENT  .Ic .SILENT
 attribute is applied to every  attribute is applied to every
 command in the file.  command in the file.
 .It Ic .SUFFIXES  .It Ic .SUFFIXES
 Each source specifies a suffix to  Each prerequisites specifies a suffix to
 .Nm make .  .Nm make .
 If no sources are specified, any previously specified suffixes are deleted.  If no prerequisites are specified, any previously specified suffixes
   are deleted.
 .El  .El
 .Sh ENVIRONMENT  .Sh ENVIRONMENT
 .Nm  .Nm
Line 1380 
Line 1360 
 .Sh STANDARDS  .Sh STANDARDS
 The  The
 .Nm  .Nm
 utility is compliant with the  utility is mostly compliant with the
 .St -p1003.1-2008  .St -p1003.1-2008
 specification,  specification.
 though its presence is optional.  
 .Pp  .Pp
 The flags  The flags
 .Op Fl BDdIjmPV  .Op Fl BDdIjmV
 are extensions to that specification.  are extensions to that specification.
 .Pp  .Pp
 Older versions of  Older versions of
Line 1410 
Line 1389 
 .Nm  .Nm
 command appeared in  command appeared in
 .At v7 .  .At v7 .
   .Pp
   This implementation is a distant derivative of
   .Nm pmake ,
   originally written by Adam de Boor.
 .Sh BUGS  .Sh BUGS
 The determination of  The determination of
 .Va .OBJDIR  .Va .OBJDIR
Line 1491 
Line 1474 
 will evaluate to a b c d after the loop, not z b c d.  will evaluate to a b c d after the loop, not z b c d.
 .Pp  .Pp
 .Ic ORDER  .Ic ORDER
 is only used in parallel mode, so  is currently only used in parallel mode, so
 keep dependency ordered for sequential mode!  keep prerequisites ordered for sequential mode!
 .Pp  .Pp
 Distinct target names are treated separately, even though they might  Distinct target names are treated separately, even though they might
 correspond to the same file in the file system.  correspond to the same file in the file system.
Line 1505 
Line 1488 
 .Pp  .Pp
 In parallel mode,  In parallel mode,
 .Fl j Ar n  .Fl j Ar n
 only limits the number of concurrent makes it knows about.  only limits the number of direct children of
 During recursive invocations, each level will multiply the number  .Nm .
   During recursive invocations, each level may multiply the total number
 of processes by  of processes by
 .Ar n .  .Ar n .
   However,
   .Nm
   includes some heuristics to try to prevent catastrophic behavior:
   if a command is marked as expensive, or preceded by
   .Sq + ,
   or seems to
   invoke a program that looks sufficiently like
   .Sq make ,
   .Nm
   will assume recursive invocation, and not start any new process until
   said command has finished running.
   Thus the number of processes run directly or indirectly by
   .Nm
   will increase linearly with each level of recursion instead of exponentially.
 .Pp  .Pp
 The  The
 .Va MAKEFILE  .Va MAKEFILE
Legend:
Removed from v.1.94  
changed lines
  Added in v.1.95