diff options
Diffstat (limited to 'man-pages-posix-2003/man1p/make.1p')
| -rw-r--r-- | man-pages-posix-2003/man1p/make.1p | 1758 |
1 files changed, 1758 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man1p/make.1p b/man-pages-posix-2003/man1p/make.1p new file mode 100644 index 0000000..42554ee --- /dev/null +++ b/man-pages-posix-2003/man1p/make.1p @@ -0,0 +1,1758 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MAKE" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" make +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.SH NAME +make \- maintain, update, and regenerate groups of programs (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +\fBmake\fP \fB[\fP\fB-einpqrst\fP\fB][\fP\fB-f\fP \fImakefile\fP\fB]\fP\fB...\fP\fB[\fP +\fB-k| -S\fP\fB][\fP\fImacro\fP\fB=\fP\fIvalue\fP\fB]\fP\fB... +.br +\ \ \ \ \ \ \fP \fB[\fP\fItarget_name\fP\fB...\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fImake\fP utility shall update files that are derived from other +files. A typical case is one where object files are +derived from the corresponding source files. The \fImake\fP utility +examines time relationships and shall update those derived +files (called targets) that have modified times earlier than the modified +times of the files (called prerequisites) from which they +are derived. A description file (makefile) contains a description +of the relationships between files, and the commands that need to +be executed to update the targets to reflect changes in their prerequisites. +Each specification, or rule, shall consist of a +target, optional prerequisites, and optional commands to be executed +when a prerequisite is newer than the target. There are two +types of rule: +.IP " 1." 4 +\fIInference rules\fP, which have one target name with at least one +period ( \fB'.'\fP ) and no slash ( \fB'/'\fP ) +.LP +.IP " 2." 4 +\fITarget rules\fP, which can have more than one target name +.LP +.LP +In addition, \fImake\fP shall have a collection of built-in macros +and inference rules that infer prerequisite relationships to +simplify maintenance of programs. +.LP +To receive exactly the behavior described in this section, the user +shall ensure that a portable makefile shall: +.IP " *" 3 +Include the special target \fB.POSIX\fP +.LP +.IP " *" 3 +Omit any special target reserved for implementations (a leading period +followed by uppercase letters) that has not been +specified by this section +.LP +.LP +The behavior of \fImake\fP is unspecified if either or both of these +conditions are not met. +.SH OPTIONS +.LP +The \fImake\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-e\fP +Cause environment variables, including those with null values, to +override macro assignments within makefiles. +.TP 7 +\fB-f\ \fP \fImakefile\fP +Specify a different makefile. The argument \fImakefile\fP is a pathname +of a description file, which is also referred to as +the \fImakefile\fP. A pathname of \fB'-'\fP shall denote the standard +input. There can be multiple instances of this option, +and they shall be processed in the order specified. The effect of +specifying the same option-argument more than once is +unspecified. +.TP 7 +\fB-i\fP +Ignore error codes returned by invoked commands. This mode is the +same as if the special target \fB.IGNORE\fP were specified +without prerequisites. +.TP 7 +\fB-k\fP +Continue to update other targets that do not depend on the current +target if a non-ignored error occurs while executing the +commands to bring a target up-to-date. +.TP 7 +\fB-n\fP +Write commands that would be executed on standard output, but do not +execute them. However, lines with a plus sign ( +\fB'+'\fP ) prefix shall be executed. In this mode, lines with an +at sign ( \fB'@'\fP ) character prefix shall be written to +standard output. +.TP 7 +\fB-p\fP +Write to standard output the complete set of macro definitions and +target descriptions. The output format is unspecified. +.TP 7 +\fB-q\fP +Return a zero exit value if the target file is up-to-date; otherwise, +return an exit value of 1. Targets shall not be updated +if this option is specified. However, a makefile command line (associated +with the targets) with a plus sign ( \fB'+'\fP ) +prefix shall be executed. +.TP 7 +\fB-r\fP +Clear the suffix list and do not use the built-in rules. +.TP 7 +\fB-S\fP +Terminate \fImake\fP if an error occurs while executing the commands +to bring a target up-to-date. This shall be the default +and the opposite of \fB-k\fP. +.TP 7 +\fB-s\fP +Do not write makefile command lines or touch messages (see \fB-t\fP) +to standard output before executing. This mode shall be +the same as if the special target \fB.SILENT\fP were specified without +prerequisites. +.TP 7 +\fB-t\fP +Update the modification time of each target as though a \fItouch\fP +\fItarget\fP had +been executed. Targets that have prerequisites but no commands (see +Target Rules ), or that are +already up-to-date, shall not be touched in this manner. Write messages +to standard output for each target file indicating the name +of the file and that it was touched. Normally, the \fImakefile\fP +command lines associated with each target are not executed. +However, a command line with a plus sign ( \fB'+'\fP ) prefix shall +be executed. +.sp +.LP +Any options specified in the \fIMAKEFLAGS\fP environment variable +shall be evaluated before any options specified on the +\fImake\fP utility command line. If the \fB-k\fP and \fB-S\fP options +are both specified on the \fImake\fP utility command line +or by the \fIMAKEFLAGS\fP environment variable, the last option specified +shall take precedence. If the \fB-f\fP or \fB-p\fP +options appear in the \fIMAKEFLAGS\fP environment variable, the result +is undefined. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fItarget_name\fP +Target names, as defined in the EXTENDED DESCRIPTION section. If no +target is specified, while \fImake\fP is processing the +makefiles, the first target that \fImake\fP encounters that is not +a special target or an inference rule shall be used. +.TP 7 +\fImacro\fP=\fIvalue\fP +Macro definitions, as defined in Macros . +.sp +.LP +If the \fItarget_name\fP and \fImacro\fP= \fIvalue\fP operands are +intermixed on the \fImake\fP utility command line, the +results are unspecified. +.SH STDIN +.LP +The standard input shall be used only if the \fImakefile\fP option-argument +is \fB'-'\fP . See the INPUT FILES section. +.SH INPUT FILES +.LP +The input file, otherwise known as the makefile, is a text file containing +rules, macro definitions, and comments. See the +EXTENDED DESCRIPTION section. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fImake\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fIMAKEFLAGS\fP +.sp +This variable shall be interpreted as a character string representing +a series of option characters to be used as the default +options. The implementation shall accept both of the following formats +(but need not accept them when intermixed): +.RS +.IP " *" 3 +The characters are option letters without the leading hyphens or <blank> +separation used on a \fImake\fP utility command +line. +.LP +.IP " *" 3 +The characters are formatted in a manner similar to a portion of the +\fImake\fP utility command line: options are preceded by +hyphens and <blank>-separated as described in the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +The \fImacro\fP= \fIvalue\fP macro +definition operands can also be included. The difference between the +contents of \fIMAKEFLAGS\fP and the \fImake\fP utility +command line is that the contents of the variable shall not be subjected +to the word expansions (see \fIWord Expansions\fP ) associated with +parsing the command line values. +.LP +.RE +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.TP 7 +\fIPROJECTDIR\fP +.sp +Provide a directory to be used to search for SCCS files not found +in the current directory. In all of the following cases, the +search for SCCS files is made in the directory \fBSCCS\fP in the identified +directory. If the value of \fIPROJECTDIR\fP begins +with a slash, it shall be considered an absolute pathname; otherwise, +the value of \fIPROJECTDIR\fP is treated as a user name and +that user's initial working directory shall be examined for a subdirectory +\fBsrc\fP or \fBsource\fP. If such a directory is +found, it shall be used. Otherwise, the value is used as a relative +pathname. +.LP +If \fIPROJECTDIR\fP is not set or has a null value, the search for +SCCS files shall be made in the directory \fBSCCS\fP in the +current directory. +.LP +The setting of \fIPROJECTDIR\fP affects all files listed in the remainder +of this utility description for files with a +component named \fBSCCS\fP. +.sp +.LP +The value of the \fISHELL\fP environment variable shall not be used +as a macro and shall not be modified by defining the +\fBSHELL\fP macro in a makefile or on the command line. All other +environment variables, including those with null values, shall +be used as macros, as defined in Macros . +.SH ASYNCHRONOUS EVENTS +.LP +If not already ignored, \fImake\fP shall trap SIGHUP, SIGTERM, SIGINT, +and SIGQUIT and remove the current target unless the +target is a directory or the target is a prerequisite of the special +target \fB.PRECIOUS\fP or unless one of the \fB-n\fP, +\fB-p\fP, or \fB-q\fP options was specified. Any targets removed in +this manner shall be reported in diagnostic messages of +unspecified format, written to standard error. After this cleanup +process, if any, \fImake\fP shall take the standard action for +all other signals. +.SH STDOUT +.LP +The \fImake\fP utility shall write all commands to be executed to +standard output unless the \fB-s\fP option was specified, +the command is prefixed with an at sign, or the special target \fB.SILENT\fP +has either the current target as a prerequisite or +has no prerequisites. If \fImake\fP is invoked without any work needing +to be done, it shall write a message to standard output +indicating that no action was taken. If the \fB-t\fP option is present +and a file is touched, \fImake\fP shall write to standard +output a message of unspecified format indicating that the file was +touched, including the filename of the file. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +Files can be created when the \fB-t\fP option is present. Additional +files can also be created by the utilities invoked by +\fImake\fP. +.SH EXTENDED DESCRIPTION +.LP +The \fImake\fP utility attempts to perform the actions required to +ensure that the specified targets are up-to-date. A target +is considered out-of-date if it is older than any of its prerequisites +or if it does not exist. The \fImake\fP utility shall treat +all prerequisites as targets themselves and recursively ensure that +they are up-to-date, processing them in the order in which they +appear in the rule. The \fImake\fP utility shall use the modification +times of files to determine whether the corresponding +targets are out-of-date. +.LP +After \fImake\fP has ensured that all of the prerequisites of a target +are up-to-date and if the target is out-of-date, the +commands associated with the target entry shall be executed. If there +are no commands listed for the target, the target shall be +treated as up-to-date. +.SS Makefile Syntax +.LP +A makefile can contain rules, macro definitions (see Macros ), and +comments. There are two kinds +of rules: \fIinference rules\fP and \fItarget rules\fP. The \fImake\fP +utility shall contain a set of built-in inference rules. +If the \fB-r\fP option is present, the built-in rules shall not be +used and the suffix list shall be cleared. Additional rules of +both types can be specified in a makefile. If a rule is defined more +than once, the value of the rule shall be that of the last one +specified. Macros can also be defined more than once, and the value +of the macro is specified in Macros . Comments start with a number +sign ( \fB'#'\fP ) and continue until an unescaped <newline> +is reached. +.LP +By default, the following files shall be tried in sequence: \fB./makefile\fP +and \fB./Makefile\fP. If neither +\fB\&./makefile\fP or \fB./Makefile\fP are found, other implementation-defined +files may also be tried. On +XSI-conformant systems, the additional files \fB./s.makefile\fP, \fBSCCS/s.makefile\fP, +\fB\&./s.Makefile\fP, and +\fBSCCS/s.Makefile\fP shall also be tried. +.LP +The \fB-f\fP option shall direct \fImake\fP to ignore any of these +default files and use the specified argument as a makefile +instead. If the \fB'-'\fP argument is specified, standard input shall +be used. +.LP +The term \fImakefile\fP is used to refer to any rules provided by +the user, whether in \fB./makefile\fP or its variants, or +specified by the \fB-f\fP option. +.LP +The rules in makefiles shall consist of the following types of lines: +target rules, including special targets (see Target Rules ), inference +rules (see Inference Rules ), macro definitions +(see Macros ), empty lines, and comments. +.LP +When an escaped <newline> (one preceded by a backslash) is found anywhere +in the makefile except in a command line, it +shall be replaced, along with any leading white space on the following +line, with a single <space>. When an escaped +<newline> is found in a command line in a makefile, the command line +shall contain the backslash, the <newline>, and +the next line, except that the first character of the next line shall +not be included if it is a <tab>. +.SS Makefile Execution +.LP +Makefile command lines shall be processed one at a time by writing +the makefile command line to the standard output (unless one +of the conditions listed under \fB'@'\fP suppresses the writing) and +executing the command(s) in the line. A <tab> may +precede the command to standard output. Command execution shall be +as if the makefile command line were the argument to the \fIsystem\fP() +function. The environment for the command being executed shall contain +all of +the variables in the environment of \fImake\fP. +.LP +By default, when \fImake\fP receives a non-zero status from the execution +of a command, it shall terminate with an error +message to standard error. +.LP +Makefile command lines can have one or more of the following prefixes: +a hyphen ( \fB'-'\fP ), an at sign ( \fB'@'\fP ), +or a plus sign ( \fB'+'\fP ). These shall modify the way in which +\fImake\fP processes the command. When a command is written +to standard output, the prefix shall not be included in the output. +.TP 7 +\fB-\fP +If the command prefix contains a hyphen, or the \fB-i\fP option is +present, or the special target \fB.IGNORE\fP has either +the current target as a prerequisite or has no prerequisites, any +error found while executing the command shall be ignored. +.TP 7 +\fB@\fP +If the command prefix contains an at sign and the \fImake\fP utility +command line \fB-n\fP option is not specified, or the +\fB-s\fP option is present, or the special target \fB.SILENT\fP has +either the current target as a prerequisite or has no +prerequisites, the command shall not be written to standard output +before it is executed. +.TP 7 +\fB+\fP +If the command prefix contains a plus sign, this indicates a makefile +command line that shall be executed even if \fB-n\fP, +\fB-q\fP, or \fB-t\fP is specified. +.sp +.SS Target Rules +.LP +Target rules are formatted as follows: +.sp +.RS +.nf + +\fItarget\fP \fB[\fP\fItarget\fP\fB...\fP\fB]\fP\fB:\fP \fB[\fP\fIprerequisite\fP\fB...\fP\fB][;\fP\fIcommand\fP\fB] +[\fP\fB<tab>\fP\fIcommand\fP\fB<tab>\fP\fIcommand\fP\fB...\fP\fB]\fP\fB +.br + +\fP\fIline that does not begin with\fP \fB<tab> +\fP +.fi +.RE +.LP +Target entries are specified by a <blank>-separated, non-null list +of targets, then a colon, then a +<blank>-separated, possibly empty list of prerequisites. Text following +a semicolon, if any, and all following lines that +begin with a <tab>, are makefile command lines to be executed to update +the target. The first non-empty line that does not +begin with a <tab> or \fB'#'\fP shall begin a new entry. An empty +or blank line, or a line beginning with \fB'#'\fP, +may begin a new entry. +.LP +Applications shall select target names from the set of characters +consisting solely of periods, underscores, digits, and +alphabetics from the portable character set (see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character +Set). Implementations may allow other characters in +target names as extensions. The interpretation of targets containing +the characters \fB'%'\fP and \fB''\fP is +implementation-defined. +.LP +A target that has prerequisites, but does not have any commands, can +be used to add to the prerequisite list for that target. +Only one target rule for any given target can contain commands. +.LP +Lines that begin with one of the following are called \fIspecial targets\fP +and control the operation of \fImake\fP: +.TP 7 +\fB\&.DEFAULT\fP +If the makefile uses this special target, the application shall ensure +that it is specified with commands, but without +prerequisites. The commands shall be used by \fImake\fP if there are +no other rules available to build a target. +.TP 7 +\fB\&.IGNORE\fP +Prerequisites of this special target are targets themselves; this +shall cause errors from commands associated with them to be +ignored in the same manner as specified by the \fB-i\fP option. Subsequent +occurrences of \fB.IGNORE\fP shall add to the list of +targets ignoring command errors. If no prerequisites are specified, +\fImake\fP shall behave as if the \fB-i\fP option had been +specified and errors from all commands associated with all targets +shall be ignored. +.TP 7 +\fB\&.POSIX\fP +The application shall ensure that this special target is specified +without prerequisites or commands. If it appears as the +first non-comment line in the makefile, \fImake\fP shall process the +makefile as specified by this section; otherwise, the +behavior of \fImake\fP is unspecified. +.TP 7 +\fB\&.PRECIOUS\fP +Prerequisites of this special target shall not be removed if \fImake\fP +receives one of the asynchronous events explicitly +described in the ASYNCHRONOUS EVENTS section. Subsequent occurrences +of \fB.PRECIOUS\fP shall add to the list of precious files. +If no prerequisites are specified, all targets in the makefile shall +be treated as if specified with \fB.PRECIOUS\fP. +.TP 7 +\fB\&.SCCS_GET\fP +The application shall ensure that this special target is specified +without prerequisites. If this special target is included in a +makefile, the commands specified with this target shall replace the +default commands associated with this special target (see Default +Rules ). The commands specified with this target are used to get all +SCCS files that are not +found in the current directory. +.LP +When source files are named in a dependency list, \fImake\fP shall +treat them just like any other target. Because the source +file is presumed to be present in the directory, there is no need +to add an entry for it to the makefile. When a target has no +dependencies, but is present in the directory, \fImake\fP shall assume +that that file is up-to-date. If, however, an SCCS file +named \fBSCCS/s.\fP \fIsource_file\fP is found for a target \fIsource_file\fP, +\fImake\fP compares the timestamp of the target +file with that of the \fBSCCS/s.source_file\fP to ensure the target +is up-to-date. If the target is missing, or if the SCCS file +is newer, \fImake\fP shall automatically issue the commands specified +for the \fB.SCCS_GET\fP special target to retrieve the most +recent version. However, if the target is writable by anyone, \fImake\fP +shall not retrieve a new version. +.TP 7 +\fB\&.SILENT\fP +Prerequisites of this special target are targets themselves; this +shall cause commands associated with them not to be written +to the standard output before they are executed. Subsequent occurrences +of \fB.SILENT\fP shall add to the list of targets with +silent commands. If no prerequisites are specified, \fImake\fP shall +behave as if the \fB-s\fP option had been specified and no +commands or touch messages associated with any target shall be written +to standard output. +.TP 7 +\fB\&.SUFFIXES\fP +Prerequisites of \fB.SUFFIXES\fP shall be appended to the list of +known suffixes and are used in conjunction with the +inference rules (see Inference Rules ). If \fB.SUFFIXES\fP does not +have any prerequisites, the +list of known suffixes shall be cleared. +.sp +.LP +The special targets \fB.IGNORE\fP, \fB.POSIX\fP, \fB.PRECIOUS\fP, +\fB\&.SILENT\fP, and \fB.SUFFIXES\fP shall be specified +without commands. +.LP +Targets with names consisting of a leading period followed by the +uppercase letters \fB"POSIX"\fP and then any other +characters are reserved for future standardization. Targets with names +consisting of a leading period followed by one or more +uppercase letters are reserved for implementation extensions. +.SS Macros +.LP +Macro definitions are in the form: +.sp +.RS +.nf + +\fIstring1\fP \fB=\fP \fB[\fP\fIstring2\fP\fB]\fP +.fi +.RE +.LP +The macro named \fIstring1\fP is defined as having the value of \fIstring2\fP, +where \fIstring2\fP is defined as all +characters, if any, after the equal sign, up to a comment character +( \fB'#'\fP ) or an unescaped <newline>. Any +<blank>s immediately before or after the equal sign shall be ignored. +.LP +Applications shall select macro names from the set of characters consisting +solely of periods, underscores, digits, and +alphabetics from the portable character set (see the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character +Set). A macro name shall not contain an equals sign. +Implementations may allow other characters in macro names as extensions. +.LP +Macros can appear anywhere in the makefile. Macro expansions using +the forms $( \fIstring1\fP) or ${ \fIstring1\fP} shall be +replaced by \fIstring2\fP, as follows: +.IP " *" 3 +Macros in target lines shall be evaluated when the target line is +read. +.LP +.IP " *" 3 +Macros in makefile command lines shall be evaluated when the command +is executed. +.LP +.IP " *" 3 +Macros in the string before the equals sign in a macro definition +shall be evaluated when the macro assignment is made. +.LP +.IP " *" 3 +Macros after the equals sign in a macro definition shall not be evaluated +until the defined macro is used in a rule or command, +or before the equals sign in a macro definition. +.LP +.LP +The parentheses or braces are optional if \fIstring1\fP is a single +character. The macro $$ shall be replaced by the single +character \fB'$'\fP . If \fIstring1\fP in a macro expansion contains +a macro expansion, the results are unspecified. +.LP +Macro expansions using the forms $( \fIstring1\fP \fB[:\fP \fIsubst1\fP +\fB=[\fP \fIsubst2\fP \fB]]\fP) or ${ +\fIstring1\fP \fB[:\fP \fIsubst1\fP \fB=[\fP \fIsubst2\fP \fB]]\fP} +can be used to replace all occurrences of \fIsubst1\fP +with \fIsubst2\fP when the macro substitution is performed. The \fIsubst1\fP +to be replaced shall be recognized when it is a +suffix at the end of a word in \fIstring1\fP (where a \fIword\fP, +in this context, is defined to be a string delimited by the +beginning of the line, a <blank>, or a <newline>). If \fIstring1\fP +in a macro expansion contains a macro expansion, +the results are unspecified. +.LP +Macro expansions in \fIstring1\fP of macro definition lines shall +be evaluated when read. Macro expansions in \fIstring2\fP of +macro definition lines shall be performed when the macro identified +by \fIstring1\fP is expanded in a rule or command. +.LP +Macro definitions shall be taken from the following sources, in the +following logical order, before the makefile(s) are +read. +.IP " 1." 4 +Macros specified on the \fImake\fP utility command line, in the order +specified on the command line. It is unspecified whether +the internal macros defined in Internal Macros are accepted from this +source. +.LP +.IP " 2." 4 +Macros defined by the \fIMAKEFLAGS\fP environment variable, in the +order specified in the environment variable. It is +unspecified whether the internal macros defined in Internal Macros +are accepted from this +source. +.LP +.IP " 3." 4 +The contents of the environment, excluding the \fIMAKEFLAGS\fP and +\fISHELL\fP variables and including the variables with null +values. +.LP +.IP " 4." 4 +Macros defined in the inference rules built into \fImake\fP. +.LP +.LP +Macro definitions from these sources shall not override macro definitions +from a lower-numbered source. Macro definitions from a +single source (for example, the \fImake\fP utility command line, the +\fIMAKEFLAGS\fP environment variable, or the other +environment variables) shall override previous macro definitions from +the same source. +.LP +Macros defined in the makefile(s) shall override macro definitions +that occur before them in the makefile(s) and macro +definitions from source 4. If the \fB-e\fP option is not specified, +macros defined in the makefile(s) shall override macro +definitions from source 3. Macros defined in the makefile(s) shall +not override macro definitions from source 1 or source 2. +.LP +Before the makefile(s) are read, all of the \fImake\fP utility command +line options (except \fB-f\fP and \fB-p\fP) and +\fImake\fP utility command line macro definitions (except any for +the \fIMAKEFLAGS\fP macro), not already included in the +\fIMAKEFLAGS\fP macro, shall be added to the \fIMAKEFLAGS\fP macro, +quoted in an implementation-defined manner such that when +\fIMAKEFLAGS\fP is read by another instance of the \fImake\fP command, +the original macro's value is recovered. Other +implementation-defined options and macros may also be added to the +\fIMAKEFLAGS\fP macro. If this modifies the value of the +\fIMAKEFLAGS\fP macro, or, if the \fIMAKEFLAGS\fP macro is modified +at any subsequent time, the \fIMAKEFLAGS\fP environment +variable shall be modified to match the new value of the \fIMAKEFLAGS\fP +macro. The result of setting \fIMAKEFLAGS\fP in the +Makefile is unspecified. +.LP +Before the makefile(s) are read, all of the \fImake\fP utility command +line macro definitions (except the \fIMAKEFLAGS\fP +macro or the \fISHELL\fP macro) shall be added to the environment +of \fImake\fP. Other implementation-defined variables may also +be added to the environment of \fImake\fP. +.LP +The \fBSHELL\fP macro shall be treated specially. It shall be provided +by \fImake\fP and set to the pathname of the shell +command language interpreter (see \fIsh\fP ). The \fISHELL\fP environment +variable shall not affect the +value of the \fBSHELL\fP macro. If \fBSHELL\fP is defined in the makefile +or is specified on the command line, it shall replace +the original value of the \fBSHELL\fP macro, but shall not affect +the \fISHELL\fP environment variable. Other effects of defining +\fBSHELL\fP in the makefile or on the command line are implementation-defined. +.SS Inference Rules +.LP +Inference rules are formatted as follows: +.sp +.RS +.nf + +\fItarget\fP\fB: +<tab>\fP\fIcommand +\fP\fB[\fP\fB<tab>\fP\fIcommand\fP\fB]\fP\fB... +.sp + +\fP\fIline that does not begin with\fP \fB<tab>\fP \fIor\fP \fB# +\fP +.fi +.RE +.LP +The application shall ensure that the \fItarget\fP portion is a valid +target name (see Target +Rules ) of the form \fB.s2\fP or \fB.s1.s2\fP (where \fB.s1\fP and +\fB\&.s2\fP are suffixes that have been given as +prerequisites of the \fB.SUFFIXES\fP special target and \fIs1\fP and +\fIs2\fP do not contain any slashes or periods.) If there +is only one period in the target, it is a single-suffix inference +rule. Targets with two periods are double-suffix inference rules. +Inference rules can have only one target before the colon. +.LP +The application shall ensure that the makefile does not specify prerequisites +for inference rules; no characters other than +white space shall follow the colon in the first line, except when +creating the \fIempty rule,\fP described below. Prerequisites +are inferred, as described below. +.LP +Inference rules can be redefined. A target that matches an existing +inference rule shall overwrite the old inference rule. An +empty rule can be created with a command consisting of simply a semicolon +(that is, the rule still exists and is found during +inference rule search, but since it is empty, execution has no effect). +The empty rule can also be formatted as follows: +.sp +.RS +.nf + +\fIrule\fP\fB: ; +\fP +.fi +.RE +.LP +where zero or more <blank>s separate the colon and semicolon. +.LP +The \fImake\fP utility uses the suffixes of targets and their prerequisites +to infer how a target can be made up-to-date. A +list of inference rules defines the commands to be executed. By default, +\fImake\fP contains a built-in set of inference rules. +Additional rules can be specified in the makefile. +.LP +The special target \fB.SUFFIXES\fP contains as its prerequisites a +list of suffixes that shall be used by the inference rules. +The order in which the suffixes are specified defines the order in +which the inference rules for the suffixes are used. New +suffixes shall be appended to the current list by specifying a \fB.SUFFIXES\fP +special target in the makefile. A \fB.SUFFIXES\fP +target with no prerequisites shall clear the list of suffixes. An +empty \fB.SUFFIXES\fP target followed by a new \fB.SUFFIXES\fP +list is required to change the order of the suffixes. +.LP +Normally, the user would provide an inference rule for each suffix. +The inference rule to update a target with a suffix +\fB\&.s1\fP from a prerequisite with a suffix \fB.s2\fP is specified +as a target \fB.s2.s1\fP. The internal macros provide the +means to specify general inference rules (see Internal Macros ). +.LP +When no target rule is found to update a target, the inference rules +shall be checked. The suffix of the target ( \fB.s1\fP) to +be built is compared to the list of suffixes specified by the \fB.SUFFIXES\fP +special targets. If the \fB.s1\fP suffix is found +in \fB.SUFFIXES\fP, the inference rules shall be searched in the order +defined for the first \fB.s2.s1\fP rule whose prerequisite +file ( \fB$*.s2\fP) exists. If the target is out-of-date with respect +to this prerequisite, the commands for that inference rule +shall be executed. +.LP +If the target to be built does not contain a suffix and there is no +rule for the target, the single suffix inference rules shall +be checked. The single-suffix inference rules define how to build +a target if a file is found with a name that matches the target +name with one of the single suffixes appended. A rule with one suffix +\fB\&.s2\fP is the definition of how to build \fItarget\fP +from \fBtarget.s2\fP. The other suffix ( \fB.s1\fP) is treated as +null. +.LP +A +tilde ( \fB'~'\fP ) in the above rules refers to an SCCS file in the +current directory. Thus, the rule \fB.c~.o\fP +would transform an SCCS C-language source file into an object file +( \fB.o\fP). Because the \fBs.\fP of the SCCS files is a +prefix, it is incompatible with \fImake\fP's suffix point of view. +Hence, the \fB'~'\fP is a way of changing any file +reference into an SCCS file reference. +.SS Libraries +.LP +If a target or prerequisite contains parentheses, it shall be treated +as a member of an archive library. For the \fIlib\fP( +\fImember\fP \fB.o\fP) expression \fIlib\fP refers to the name of +the archive library and \fImember\fP \fB.o\fP to the member +name. The application shall ensure that the member is an object file +with the \fB.o\fP suffix. The modification time of the +expression is the modification time for the member as kept in the +archive library; see \fIar\fP . The +\fB\&.a\fP suffix shall refer to an archive library. The \fB.s2.a\fP +rule shall be used to update a member in the library from a +file with a suffix \fB.s2\fP. +.SS Internal Macros +.LP +The \fImake\fP utility shall maintain five internal macros that can +be used in target and inference rules. In order to clearly +define the meaning of these macros, some clarification of the terms +\fItarget rule\fP, \fIinference rule\fP, \fItarget\fP, and +\fIprerequisite\fP is necessary. +.LP +Target rules are specified by the user in a makefile for a particular +target. Inference rules are user-specified or +\fImake\fP-specified rules for a particular class of target name. +Explicit prerequisites are those prerequisites specified in a +makefile on target lines. Implicit prerequisites are those prerequisites +that are generated when inference rules are used. +Inference rules are applied to implicit prerequisites or to explicit +prerequisites that do not have target rules defined for them +in the makefile. Target rules are applied to targets specified in +the makefile. +.LP +Before any target in the makefile is updated, each of its prerequisites +(both explicit and implicit) shall be updated. This +shall be accomplished by recursively processing each prerequisite. +Upon recursion, each prerequisite shall become a target itself. +Its prerequisites in turn shall be processed recursively until a target +is found that has no prerequisites, at which point the +recursion stops. The recursion shall then back up, updating each target +as it goes. +.LP +In the definitions that follow, the word \fItarget\fP refers to one +of: +.IP " *" 3 +A target specified in the makefile +.LP +.IP " *" 3 +An explicit prerequisite specified in the makefile that becomes the +target when \fImake\fP processes it during recursion +.LP +.IP " *" 3 +An implicit prerequisite that becomes a target when \fImake\fP processes +it during recursion +.LP +.LP +In the definitions that follow, the word \fIprerequisite\fP refers +to one of the following: +.IP " *" 3 +An explicit prerequisite specified in the makefile for a particular +target +.LP +.IP " *" 3 +An implicit prerequisite generated as a result of locating an appropriate +inference rule and corresponding file that matches the +suffix of the target +.LP +.LP +The five internal macros are: +.TP 7 +$@ +The $@ shall evaluate to the full target name of the current target, +or the archive filename part of a library archive target. +It shall be evaluated for both target and inference rules. +.LP +For example, in the \fB.c.a\fP inference rule, $@ represents the out-of-date +\fB\&.a\fP file to be built. Similarly, in a +makefile target rule to build \fBlib.a\fP from \fBfile.c\fP, $@ represents +the out-of-date \fBlib.a\fP. +.TP 7 +$% +The $% macro shall be evaluated only when the current target is an +archive library member of the form \fIlibname\fP( +\fImember\fP \fB.o\fP). In these cases, $@ shall evaluate to \fIlibname\fP +and $% shall evaluate to \fImember\fP \fB.o\fP. The +$% macro shall be evaluated for both target and inference rules. +.LP +For example, in a makefile target rule to build \fBlib.a\fP( \fBfile.o\fP), +$% represents \fBfile.o\fP, as opposed to $@, +which represents \fBlib.a\fP. +.TP 7 +$? +The $? macro shall evaluate to the list of prerequisites that are +newer than the current target. It shall be evaluated for both +target and inference rules. +.LP +For example, in a makefile target rule to build \fIprog\fP from \fBfile1.o\fP, +\fBfile2.o\fP, and \fBfile3.o\fP, and where +\fIprog\fP is not out-of-date with respect to \fBfile1.o\fP, but is +out-of-date with respect to \fBfile2.o\fP and +\fBfile3.o\fP, $? represents \fBfile2.o\fP and \fBfile3.o\fP. +.TP 7 +$< +In an inference rule, the $< macro shall evaluate to the filename +whose existence allowed the inference rule to be chosen +for the target. In the \fB.DEFAULT\fP rule, the $< macro shall evaluate +to the current target name. The meaning of the $< +macro shall be otherwise unspecified. +.LP +For example, in the \fB.c.a\fP inference rule, $< represents the prerequisite +\fB\&.c\fP file. +.TP 7 +$* +The $* macro shall evaluate to the current target name with its suffix +deleted. It shall be evaluated at least for inference +rules. +.LP +For example, in the \fB.c.a\fP inference rule, $*.o represents the +out-of-date \fB.o\fP file that corresponds to the +prerequisite \fB.c\fP file. +.sp +.LP +Each of the internal macros has an alternative form. When an uppercase +\fB'D'\fP or \fB'F'\fP is appended to any of the +macros, the meaning shall be changed to the \fIdirectory part\fP for +\fB'D'\fP and \fIfilename part\fP for \fB'F'\fP . The +directory part is the path prefix of the file without a trailing slash; +for the current directory, the directory part is +\fB'.'\fP . When the $? macro contains more than one prerequisite +filename, the $(?D) and $(?F) (or ${?D} and ${?F}) macros +expand to a list of directory name parts and filename parts respectively. +.LP +For the target \fIlib\fP( \fImember\fP \fB.o\fP) and the \fBs2.a\fP +rule, the internal macros shall be defined as: +.TP 7 +$< +\fImember\fP \fB.s2\fP +.TP 7 +$* +\fImember\fP +.TP 7 +$@ +\fIlib\fP +.TP 7 +$? +\fImember\fP \fB.s2\fP +.TP 7 +$% +\fImember\fP \fB.o\fP +.sp +.SS Default Rules +.LP +The default rules for \fImake\fP shall achieve results that are the +same as if the following were used. Implementations that do +not support the C-Language Development Utilities option may omit \fBCC\fP, +\fBCFLAGS\fP, \fBYACC\fP, \fBYFLAGS\fP, \fBLEX\fP, +\fBLFLAGS\fP, \fBLDFLAGS\fP, and the \fB.c\fP, \fB.y\fP, and \fB.l\fP +inference rules. Implementations that do not support +FORTRAN may omit \fBFC\fP, \fBFFLAGS\fP, and the \fB.f\fP inference +rules. Implementations may provide additional macros and +rules. +.sp +.RS +.nf + +\fISPECIAL TARGETS\fP\fB +.br + + +\&.SCCS_GET: sccs $(SCCSFLAGS) get $(SCCSGETFLAGS) $@ + +.sp + + +\&.SUFFIXES: .o .c .y .l .a .sh .f .c~ .y~ .l~ .sh~ .f~ +.sp + +\fP\fIMACROS\fP\fB +.br + +MAKE=make +AR=ar +ARFLAGS=-rv +YACC=yacc +YFLAGS= +LEX=lex +LFLAGS= +LDFLAGS= +CC=c99 +CFLAGS=-O +FC=fort77 +FFLAGS=-O 1 + +GET=get +GFLAGS= +SCCSFLAGS= +SCCSGETFLAGS=-s + +.sp + +\fP\fISINGLE SUFFIX RULES\fP\fB +.br + +\&.c: + $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $< +.sp + +\&.f: + $(FC) $(FFLAGS) $(LDFLAGS) -o $@ $< +.sp + +\&.sh: + cp $< $@ + chmod a+x $@ +.sp + + +\&.c~: + $(GET) $(GFLAGS) -p $< > $*.c + $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $*.c +.sp + +\&.f~: + $(GET) $(GFLAGS) -p $< > $*.f + $(FC) $(FFLAGS) $(LDFLAGS) -o $@ $*.f +.sp + +\&.sh~: + $(GET) $(GFLAGS) -p $< > $*.sh + cp $*.sh $@ + chmod a+x $@ + +.sp + +\fP\fIDOUBLE SUFFIX RULES\fP\fB +.br + +\&.c.o: + $(CC) $(CFLAGS) -c $< +.sp + +\&.f.o: + $(FC) $(FFLAGS) -c $< +.sp + +\&.y.o: + $(YACC) $(YFLAGS) $< + $(CC) $(CFLAGS) -c y.tab.c + rm -f y.tab.c + mv y.tab.o $@ +.sp + +\&.l.o: + $(LEX) $(LFLAGS) $< + $(CC) $(CFLAGS) -c lex.yy.c + rm -f lex.yy.c + mv lex.yy.o $@ +.sp + +\&.y.c: + $(YACC) $(YFLAGS) $< + mv y.tab.c $@ +.sp + +\&.l.c: + $(LEX) $(LFLAGS) $< + mv lex.yy.c $@ +.sp + + +\&.c~.o: + $(GET) $(GFLAGS) -p $< > $*.c + $(CC) $(CFLAGS) -c $*.c +.sp + +\&.f~.o: + $(GET) $(GFLAGS) -p $< > $*.f + $(FC) $(FFLAGS) -c $*.f +.sp + +\&.y~.o: + $(GET) $(GFLAGS) -p $< > $*.y + $(YACC) $(YFLAGS) $*.y + $(CC) $(CFLAGS) -c y.tab.c + rm -f y.tab.c + mv y.tab.o $@ +.sp + +\&.l~.o: + $(GET) $(GFLAGS) -p $< > $*.l + $(LEX) $(LFLAGS) $*.l + $(CC) $(CFLAGS) -c lex.yy.c + rm -f lex.yy.c + mv lex.yy.o $@ +.sp + +\&.y~.c: + $(GET) $(GFLAGS) -p $< > $*.y + $(YACC) $(YFLAGS) $*.y + mv y.tab.c $@ +.sp + +\&.l~.c: + $(GET) $(GFLAGS) -p $< > $*.l + $(LEX) $(LFLAGS) $*.l + mv lex.yy.c $@ + +.sp + +\&.c.a: + $(CC) -c $(CFLAGS) $< + $(AR) $(ARFLAGS) $@ $*.o + rm -f $*.o +.sp + +\&.f.a: + $(FC) -c $(FFLAGS) $< + $(AR) $(ARFLAGS) $@ $*.o + rm -f $*.o +\fP +.fi +.RE +.SH EXIT STATUS +.LP +When the \fB-q\fP option is specified, the \fImake\fP utility shall +exit with one of the following values: +.TP 7 +\ 0 +Successful completion. +.TP 7 +\ 1 +The target was not up-to-date. +.TP 7 +>1 +An error occurred. +.sp +.LP +When the \fB-q\fP option is not specified, the \fImake\fP utility +shall exit with one of the following values: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +If there is a source file (such as \fB./source.c\fP) and there are +two SCCS files corresponding to it ( \fB./s.source.c\fP and +\fB\&./SCCS/s.source.c\fP), on XSI-conformant systems \fImake\fP uses +the SCCS file in the current directory. However, users are +advised to use the underlying SCCS utilities ( \fIadmin\fP, \fIdelta\fP, +\fIget\fP, and so on) or the \fIsccs\fP utility for all source files +in a given directory. If both forms are used for a given +source file, future developers are very likely to be confused. +.LP +It is incumbent upon portable makefiles to specify the \fB.POSIX\fP +special target in order to guarantee that they are not +affected by local extensions. +.LP +The \fB-k\fP and \fB-S\fP options are both present so that the relationship +between the command line, the \fIMAKEFLAGS\fP +variable, and the makefile can be controlled precisely. If the \fBk\fP +flag is passed in \fIMAKEFLAGS\fP and a command is of the +form: +.sp +.RS +.nf + +\fB$(MAKE) -S foo +\fP +.fi +.RE +.LP +then the default behavior is restored for the child \fImake\fP. +.LP +When the \fB-n\fP option is specified, it is always added to \fIMAKEFLAGS +\&.\fP This allows a recursive \fImake\fP \fB-n\fP +\fItarget\fP to be used to see all of the action that would be taken +to update \fItarget\fP. +.LP +Because of widespread historical practice, interpreting a \fB'#'\fP +number sign inside a variable as the start of a comment +has the unfortunate side effect of making it impossible to place a +number sign in a variable, thus forbidding something like: +.sp +.RS +.nf + +\fBCFLAGS = "-D COMMENT_CHAR='#'" +\fP +.fi +.RE +.LP +Many historical \fImake\fP utilities stop chaining together inference +rules when an intermediate target is nonexistent. For +example, it might be possible for a \fImake\fP to determine that both +\fB\&.y.c\fP and \fB.c.o\fP could be used to convert a +\fB\&.y\fP to a \fB.o\fP. Instead, in this case, \fImake\fP requires +the use of a \fB.y.o\fP rule. +.LP +The best way to provide portable makefiles is to include all of the +rules needed in the makefile itself. The rules provided use +only features provided by other parts of this volume of IEEE\ Std\ 1003.1-2001. +The default rules include rules for +optional commands in this volume of IEEE\ Std\ 1003.1-2001. Only rules +pertaining to commands that are provided are needed +in an implementation's default set. +.LP +Macros used within other macros are evaluated when the new macro is +used rather than when the new macro is defined. +Therefore: +.sp +.RS +.nf + +\fBMACRO =\fP \fIvalue1\fP\fBNEW = $(MACRO) +MACRO =\fP \fIvalue2\fP\fB +.br + +target: + echo $(NEW) +\fP +.fi +.RE +.LP +would produce \fIvalue2\fP and not \fIvalue1\fP since \fBNEW\fP was +not expanded until it was needed in the \fIecho\fP command line. +.LP +Some historical applications have been known to intermix \fItarget_name\fP +and \fImacro=name\fP operands on the command line, +expecting that all of the macros are processed before any of the targets +are dealt with. Conforming applications do not do this, +although some backwards-compatibility support may be included in some +implementations. +.LP +The following characters in filenames may give trouble: \fB'='\fP, +\fB':'\fP, \fB'`'\fP, \fB'"\fP, and +\fB'@'\fP . For inference rules, the description of $< and $? seem +similar. However, an example shows the minor difference. +In a makefile containing: +.sp +.RS +.nf + +\fBfoo.o: foo.h +\fP +.fi +.RE +.LP +if \fBfoo.h\fP is newer than \fBfoo.o\fP, yet \fBfoo.c\fP is older +than \fBfoo.o\fP, the built-in rule to make \fBfoo.o\fP +from \fBfoo.c\fP is used, with $< equal to \fBfoo.c\fP and $? equal +to \fBfoo.h\fP. If \fBfoo.c\fP is also newer than +\fBfoo.o\fP, $< is equal to \fBfoo.c\fP and $? is equal to \fBfoo.h +foo.c\fP. +.SH EXAMPLES +.IP " 1." 4 +The following command: +.sp +.RS +.nf + +\fBmake +\fP +.fi +.RE +.LP +makes the first target found in the makefile. +.LP +.IP " 2." 4 +The following command: +.sp +.RS +.nf + +\fBmake junk +\fP +.fi +.RE +.LP +makes the target \fBjunk\fP. +.LP +.IP " 3." 4 +The following makefile says that \fBpgm\fP depends on two files, \fBa.o\fP +and \fBb.o\fP, and that they in turn depend on +their corresponding source files ( \fBa.c\fP and \fBb.c\fP), and a +common file \fBincl.h\fP: +.sp +.RS +.nf + +\fBpgm: a.o b.o + c99 a.o b.o -o pgm +a.o: incl.h a.c + c99 -c a.c +b.o: incl.h b.c + c99 -c b.c +\fP +.fi +.RE +.LP +.IP " 4." 4 +An example for making optimized \fB.o\fP files from \fB.c\fP files +is: +.sp +.RS +.nf + +\fB\&.c.o: + c99 -c -O $*.c +\fP +.fi +.RE +.LP +or: +.sp +.RS +.nf + +\fB\&.c.o: + c99 -c -O $< +\fP +.fi +.RE +.LP +.IP " 5." 4 +The most common use of the archive interface follows. Here, it is +assumed that the source files are all C-language source: +.sp +.RS +.nf + +\fBlib: lib(file1.o) lib(file2.o) lib(file3.o) + @echo lib is now up-to-date +\fP +.fi +.RE +.LP +The \fB.c.a\fP rule is used to make \fBfile1.o\fP, \fBfile2.o\fP, +and \fBfile3.o\fP and insert them into \fBlib\fP. +.LP +The treatment of escaped <newline>s throughout the makefile is historical +practice. For example, the inference rule: +.sp +.RS +.nf + +\fB\&.c.o\\ +: +\fP +.fi +.RE +.LP +works, and the macro: +.sp +.RS +.nf + +\fBf= bar baz\\ + biz +a: + echo ==$f== +\fP +.fi +.RE +.LP +echoes \fB"==bar\ baz\ biz=="\fP . +.LP +If $? were: +.sp +.RS +.nf + +\fB/usr/include/stdio.h /usr/include/unistd.h foo.h +\fP +.fi +.RE +.LP +then $(?D) would be: +.sp +.RS +.nf + +\fB/usr/include /usr/include . +\fP +.fi +.RE +.LP +and $(?F) would be: +.sp +.RS +.nf + +\fBstdio.h unistd.h foo.h +\fP +.fi +.RE +.LP +.IP " 6." 4 +The contents of the built-in rules can be viewed by running: +.sp +.RS +.nf + +\fBmake -p -f /dev/null 2>/dev/null +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The \fImake\fP utility described in this volume of IEEE\ Std\ 1003.1-2001 +is intended to provide the means for changing +portable source code into executables that can be run on an IEEE\ Std\ 1003.1-2001-conforming +system. It reflects the most +common features present in System V and BSD \fImake\fPs. +.LP +Historically, the \fImake\fP utility has been an especially fertile +ground for vendor and research organization-specific syntax +modifications and extensions. Examples include: +.IP " *" 3 +Syntax supporting parallel execution (such as from various multi-processor +vendors, GNU, and others) +.LP +.IP " *" 3 +Additional "operators" separating targets and their prerequisites +(System V, BSD, and others) +.LP +.IP " *" 3 +Specifying that command lines containing the strings \fB"${MAKE}"\fP +and \fB"$(MAKE)"\fP are executed when the \fB-n\fP +option is specified (GNU and System V) +.LP +.IP " *" 3 +Modifications of the meaning of internal macros when referencing libraries +(BSD and others) +.LP +.IP " *" 3 +Using a single instance of the shell for all of the command lines +of the target (BSD and others) +.LP +.IP " *" 3 +Allowing spaces as well as tabs to delimit command lines (BSD) +.LP +.IP " *" 3 +Adding C preprocessor-style "include" and "ifdef" constructs (System +V, GNU, BSD, and others) +.LP +.IP " *" 3 +Remote execution of command lines (Sprite and others) +.LP +.IP " *" 3 +Specifying additional special targets (BSD, System V, and most others) +.LP +.LP +Additionally, many vendors and research organizations have rethought +the basic concepts of \fImake\fP, creating vastly +extended, as well as completely new, syntaxes. Each of these versions +of \fImake\fP fulfills the needs of a different community of +users; it is unreasonable for this volume of IEEE\ Std\ 1003.1-2001 +to require behavior that would be incompatible (and +probably inferior) to historical practice for such a community. +.LP +In similar circumstances, when the industry has enough sufficiently +incompatible formats as to make them irreconcilable, this +volume of IEEE\ Std\ 1003.1-2001 has followed one or both of two courses +of action. Commands have been renamed ( \fIcksum\fP, \fIecho\fP, and +\fIpax\fP) and/or command line options have been provided to select +the desired behavior ( \fIgrep\fP, \fIod\fP, and \fIpax\fP). +.LP +Because the syntax specified for the \fImake\fP utility is, by and +large, a subset of the syntaxes accepted by almost all +versions of \fImake\fP, it was decided that it would be counter-productive +to change the name. And since the makefile itself is a +basic unit of portability, it would not be completely effective to +reserve a new option letter, such as \fImake\fP \fB-P\fP, to +achieve the portable behavior. Therefore, the special target \fB.POSIX\fP +was added to the makefile, allowing users to specify +"standard" behavior. This special target does not preclude extensions +in the \fImake\fP utility, nor does it preclude such +extensions being used by the makefile specifying the target; it does, +however, preclude any extensions from being applied that +could alter the behavior of previously valid syntax; such extensions +must be controlled via command line options or new special +targets. It is incumbent upon portable makefiles to specify the \fB.POSIX\fP +special target in order to guarantee that they are +not affected by local extensions. +.LP +The portable version of \fImake\fP described in this reference page +is not intended to be the state-of-the-art software +generation tool and, as such, some newer and more leading-edge features +have not been included. An attempt has been made to +describe the portable makefile in a manner that does not preclude +such extensions as long as they do not disturb the portable +behavior described here. +.LP +When the \fB-n\fP option is specified, it is always added to \fIMAKEFLAGS +\&.\fP This allows a recursive \fImake\fP \fB-n\fP +\fItarget\fP to be used to see all of the action that would be taken +to update \fItarget\fP. +.LP +The definition of \fIMAKEFLAGS\fP allows both the System V letter +string and the BSD command line formats. The two formats are +sufficiently different to allow implementations to support both without +ambiguity. +.LP +Early proposals stated that an "unquoted" number sign was treated +as the start of a comment. The \fImake\fP utility does not +pay any attention to quotes. A number sign starts a comment regardless +of its surroundings. +.LP +The text about "other implementation-defined pathnames may also be +tried" in addition to \fB./makefile\fP and +\fB\&./Makefile\fP is to allow such extensions as \fBSCCS/s.Makefile\fP +and other variations. It was made an implementation-defined +requirement (as opposed to unspecified behavior) to highlight surprising +implementations that might select something unexpected +like \fB/etc/Makefile\fP. XSI-conformant systems also try \fB./s.makefile\fP, +\fBSCCS/s.makefile\fP, \fB./s.Makefile\fP, and +\fBSCCS/s.Makefile\fP. +.LP +Early proposals contained the macro \fBNPROC\fP as a means of specifying +that \fImake\fP should use \fIn\fP processes to do +the work required. While this feature is a valuable extension for +many systems, it is not common usage and could require other +non-trivial extensions to makefile syntax. This extension is not required +by this volume of IEEE\ Std\ 1003.1-2001, but +could be provided as a compatible extension. The macro \fBPARALLEL\fP +is used by some historical systems with essentially the same +meaning (but without using a name that is a common system limit value). +It is suggested that implementors recognize the existing +use of \fBNPROC\fP and/or \fBPARALLEL\fP as extensions to \fImake\fP. +.LP +The default rules are based on System V. The default \fBCC=\fP value +is \fIc99\fP instead +of \fIcc\fP because this volume of IEEE\ Std\ 1003.1-2001 does not +standardize the utility named \fIcc\fP. Thus, every +conforming application would be required to define \fBCC=\fP \fIc99\fP +to expect to run. +There is no advantage conferred by the hope that the makefile might +hit the "preferred" compiler because this cannot be +guaranteed to work. Also, since the portable makescript can only use +the \fIc99\fP options, no +advantage is conferred in terms of what the script can do. It is a +quality-of-implementation issue as to whether \fIc99\fP is as valuable +as \fIcc\fP. +.LP +The \fB-d\fP option to \fImake\fP is frequently used to produce debugging +information, but is too implementation-defined to +add to this volume of IEEE\ Std\ 1003.1-2001. +.LP +The \fB-p\fP option is not passed in \fIMAKEFLAGS\fP on most historical +implementations and to change this would cause many +implementations to break without sufficiently increased portability. +.LP +Commands that begin with a plus sign ( \fB'+'\fP ) are executed even +if the \fB-n\fP option is present. Based on the GNU +version of \fImake\fP, the behavior of \fB-n\fP when the plus-sign +prefix is encountered has been extended to apply to \fB-q\fP +and \fB-t\fP as well. However, the System V convention of forcing +command execution with \fB-n\fP when the command line of a +target contains either of the strings \fB"$(MAKE)"\fP or \fB"${MAKE}"\fP +has not been adopted. This functionality appeared in +early proposals, but the danger of this approach was pointed out with +the following example of a portion of a makefile: +.sp +.RS +.nf + +\fBsubdir: + cd subdir; rm all_the_files; $(MAKE) +\fP +.fi +.RE +.LP +The loss of the System V behavior in this case is well-balanced by +the safety afforded to other makefiles that were not aware of +this situation. In any event, the command line plus-sign prefix can +provide the desired functionality. +.LP +The double colon in the target rule format is supported in BSD systems +to allow more than one target line containing the same +target name to have commands associated with it. Since this is not +functionality described in the SVID or XPG3 it has been allowed +as an extension, but not mandated. +.LP +The default rules are provided with text specifying that the built-in +rules shall be the same as if the listed set were used. +The intent is that implementations should be able to use the rules +without change, but will be allowed to alter them in ways that +do not affect the primary behavior. +.LP +The best way to provide portable makefiles is to include all of the +rules needed in the makefile itself. The rules provided use +only features provided by other portions of this volume of IEEE\ Std\ 1003.1-2001. +The default rules include rules for +optional commands in this volume of IEEE\ Std\ 1003.1-2001. Only rules +pertaining to commands that are provided are needed +in the default set of an implementation. +.LP +One point of discussion was whether to drop the default rules list +from this volume of IEEE\ Std\ 1003.1-2001. They +provide convenience, but do not enhance portability of applications. +The prime benefit is in portability of users who wish to type +\fImake\fP \fIcommand\fP and have the command build from a \fBcommand.c\fP +file. +.LP +The historical \fIMAKESHELL\fP feature was omitted. In some implementations +it is used to let a user override the shell to be +used to run \fImake\fP commands. This was confusing; for a portable +\fImake\fP, the shell should be chosen by the makefile writer +or specified on the \fImake\fP command line and not by a user running +\fImake\fP. +.LP +The \fImake\fP utilities in most historical implementations process +the prerequisites of a target in left-to-right order, and +the makefile format requires this. It supports the standard idiom +used in many makefiles that produce \fIyacc\fP programs; for example: +.sp +.RS +.nf + +\fBfoo: y.tab.o lex.o main.o + $(CC) $(CFLAGS) -o $\fP@ \fBt.tab.o lex.o main.o +\fP +.fi +.RE +.LP +In this example, if \fImake\fP chose any arbitrary order, the \fBlex.o\fP +might not be made with the correct \fBy.tab.h\fP. +Although there may be better ways to express this relationship, it +is widely used historically. Implementations that desire to +update prerequisites in parallel should require an explicit extension +to \fImake\fP or the makefile format to accomplish it, as +described previously. +.LP +The algorithm for determining a new entry for target rules is partially +unspecified. Some historical \fImake\fPs allow blank, +empty, or comment lines within the collection of commands marked by +leading <tab>s. A conforming makefile must ensure that +each command starts with a <tab>, but implementations are free to +ignore blank, empty, and comment lines without triggering +the start of a new entry. +.LP +The ASYNCHRONOUS EVENTS section includes having SIGTERM and SIGHUP, +along with the more traditional SIGINT and SIGQUIT, remove +the current target unless directed not to do so. SIGTERM and SIGHUP +were added to parallel other utilities that have historically +cleaned up their work as a result of these signals. When \fImake\fP +receives any signal other than SIGQUIT, it is required to +resend itself the signal it received so that it exits with a status +that reflects the signal. The results from SIGQUIT are +partially unspecified because, on systems that create \fBcore\fP files +upon receipt of SIGQUIT, the \fBcore\fP from \fImake\fP +would conflict with a \fBcore\fP file from the command that was running +when the SIGQUIT arrived. The main concern was to prevent +damaged files from appearing up-to-date when \fImake\fP is rerun. +.LP +The \fB.PRECIOUS\fP special target was extended to affect all targets +globally (by specifying no prerequisites). The +\fB\&.IGNORE\fP and \fB.SILENT\fP special targets were extended to allow +prerequisites; it was judged to be more useful in some +cases to be able to turn off errors or echoing for a list of targets +than for the entire makefile. These extensions to \fImake\fP +in System V were made to match historical practice from the BSD \fImake\fP. +.LP +Macros are not exported to the environment of commands to be run. +This was never the case in any historical \fImake\fP and +would have serious consequences. The environment is the same as the +environment to \fImake\fP except that \fIMAKEFLAGS\fP and +macros defined on the \fImake\fP command line are added. +.LP +Some implementations do not use \fIsystem\fP() for all command lines, +as required by the +portable makefile format; as a performance enhancement, they select +lines without shell metacharacters for direct execution by \fIexecve\fP(). +There is no requirement that \fIsystem\fP() be used specifically, +but merely that the same results be achieved. The +metacharacters typically used to bypass the direct \fIexecve\fP() +execution have been any +of: +.sp +.RS +.nf + +\fB= | ^ ( ) ; & < > * ? [ ] : $ ` ' " \\ \\n +\fP +.fi +.RE +.LP +The default in some advanced versions of \fImake\fP is to group all +the command lines for a target and execute them using a +single shell invocation; the System V method is to pass each line +individually to a separate shell. The single-shell method has the +advantages in performance and the lack of a requirement for many continued +lines. However, converting to this newer method has +caused portability problems with many historical makefiles, so the +behavior with the POSIX makefile is specified to be the same as +that of System V. It is suggested that the special target \fB.ONESHELL\fP +be used as an implementation extension to achieve the +single-shell grouping for a target or group of targets. +.LP +Novice users of \fImake\fP have had difficulty with the historical +need to start commands with a <tab>. Since it is often +difficult to discern differences between <tab>s and <space>s on terminals +or printed listings, confusing bugs can +arise. In early proposals, an attempt was made to correct this problem +by allowing leading <blank>s instead of <tab>s. +However, implementors reported many makefiles that failed in subtle +ways following this change, and it is difficult to implement a +\fImake\fP that unambiguously can differentiate between macro and +command lines. There is extensive historical practice of +allowing leading spaces before macro definitions. Forcing macro lines +into column 1 would be a significant backwards-compatibility +problem for some makefiles. Therefore, historical practice was restored. +.LP +The System V INCLUDE feature was considered, but not included. This +would treat a line that began in the first column and +contained INCLUDE <\fIfilename\fP> as an indication to read <\fIfilename\fP> +at that point in the makefile. This is +difficult to use in a portable way, and it raises concerns about nesting +levels and diagnostics. System V, BSD, GNU, and others +have used different methods for including files. +.LP +The System V dynamic dependency feature was not included. It would +support: +.sp +.RS +.nf + +\fBcat: $$@.c +\fP +.fi +.RE +.LP +that would expand to; +.sp +.RS +.nf + +\fBcat: cat.c +\fP +.fi +.RE +.LP +This feature exists only in the new version of System V \fImake\fP +and, while useful, is not in wide usage. This means that +macros are expanded twice for prerequisites: once at makefile parse +time and once at target update time. +.LP +Consideration was given to adding metarules to the POSIX \fImake\fP. +This would make \fB%.o:\ %.c\fP the same as +\fB\&.c.o:\fP. This is quite useful and available from some vendors, +but it would cause too many changes to this \fImake\fP to +support. It would have introduced rule chaining and new substitution +rules. However, the rules for target names have been set to +reserve the \fB'%'\fP and \fB''\fP characters. These are traditionally +used to implement metarules and quoting of target +names, respectively. Implementors are strongly encouraged to use these +characters only for these purposes. +.LP +A request was made to extend the suffix delimiter character from a +period to any character. The metarules feature in newer +\fImake\fPs solves this problem in a more general way. This volume +of IEEE\ Std\ 1003.1-2001 is staying with the more +conservative historical definition. +.LP +The standard output format for the \fB-p\fP option is not described +because it is primarily a debugging option and because the +format is not generally useful to programs. In historical implementations +the output is not suitable for use in generating +makefiles. The \fB-p\fP format has been variable across historical +implementations. Therefore, the definition of \fB-p\fP was +only to provide a consistently named option for obtaining \fImake\fP +script debugging information. +.LP +Some historical implementations have not cleared the suffix list with +\fB-r\fP. +.LP +Implementations should be aware that some historical applications +have intermixed \fItarget_name\fP and \fImacro\fP= +\fIvalue\fP operands on the command line, expecting that all of the +macros are processed before any of the targets are dealt with. +Conforming applications do not do this, but some backwards-compatibility +support may be warranted. +.LP +Empty inference rules are specified with a semicolon command rather +than omitting all commands, as described in an early +proposal. The latter case has no traditional meaning and is reserved +for implementation extensions, such as in GNU \fImake\fP. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIShell Command Language\fP, \fIar\fP, \fIc99\fP, \fIget\fP, +\fIlex\fP, \fIsccs\fP, \fIsh\fP, \fIyacc\fP, the System Interfaces +volume +of IEEE\ Std\ 1003.1-2001, \fIexec\fP, \fIsystem\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |