Date: Fri, 7 Aug 2009 01:46:08 +0000 (UTC) From: Craig Rodrigues <rodrigc@FreeBSD.org> To: src-committers@freebsd.org, svn-src-projects@freebsd.org Subject: svn commit: r196084 - projects/jbuild/usr.bin/jbuild Message-ID: <200908070146.n771k8XL071593@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: rodrigc Date: Fri Aug 7 01:46:08 2009 New Revision: 196084 URL: http://svn.freebsd.org/changeset/base/196084 Log: Add first draft of jbuild(1) man page. Added: projects/jbuild/usr.bin/jbuild/jbuild.1 Added: projects/jbuild/usr.bin/jbuild/jbuild.1 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ projects/jbuild/usr.bin/jbuild/jbuild.1 Fri Aug 7 01:46:08 2009 (r196084) @@ -0,0 +1,1786 @@ +.\" Copyright (c) 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)make.1 8.8 (Berkeley) 6/13/95 +.\" $FreeBSD$ +.\" +.Dd August 6, 2009 +.Dt JBUILD 1 +.Os +.Sh NAME +.Nm jbuild +.Nd maintain program dependencies +.Sh SYNOPSIS +.Nm +.Op Fl ABPSXeiknpqrstv +.Op Fl C Ar directory +.Op Fl D Ar variable +.Op Fl d Ar flags +.Op Fl E Ar variable +.Op Fl f Ar makefile +.Op Fl I Ar directory +.Bk -words +.Op Fl j Ar max_jobs +.Op Fl m Ar directory +.Ek +.Op Fl V Ar variable +.Op Fl x Ar warning_options +.Op Ar variable Ns No = Ns Ar value +.Op Ar target ... +.Sh DESCRIPTION +The +.Nm +utility is a program designed to simplify the maintenance of other programs. +Its input is a list of specifications +describing dependency relationships between the generation of +files and programs. +.Pp +First of all, the initial list of specifications will be read +from the system makefile, +.Pa sys.mk , +unless inhibited with the +.Fl r +option. +The standard +.Pa sys.mk +as shipped with +.Fx +also handles +.Xr make.conf 5 , +the default path to which +can be altered via the +.Nm +variable +.Va __MAKE_CONF . +.Pp +Then the first +.Pa Buildfile , +that can be found in the current directory +or search path (see the +.Fl I +option) +will be read for the main list of dependency specifications. +A different Buildfile or list of them can be supplied via the +.Fl f +option(s). +Finally, if the file +.Pa .depend +can be found in any of the aforesaid locations, it will also be read (see +.Xr mkdep 1 ) . +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl A +Make archive errors non-fatal, causing +.Nm +to just skip the remainder +or all of the archive and continue after printing a message. +.It Fl B +Try to be backwards compatible by executing a single shell per command and +by executing the commands to make the sources of a dependency line in sequence. +This is turned on by default unless +.Fl j +is used. +.It Fl C Ar directory +Change to +.Ar directory +before reading the Buildfiles or doing anything else. +If multiple +.Fl C +options are specified, each is interpreted relative to the previous one: +.Fl C Pa / Fl C Pa etc +is equivalent to +.Fl C Pa /etc . +.It Fl D Ar variable +Define +.Ar variable +to be 1, in the global context. +.It Fl d Ar flags +Turn on debugging, and specify which portions of +.Nm +are to print debugging information. +Argument +.Ar flags +is one or more of the following: +.Bl -tag -width Ds +.It Ar A +Print all possible debugging information; +equivalent to specifying all of the debugging flags. +.It Ar a +Print debugging information about archive searching and caching. +.It Ar c +Print debugging information about conditional evaluation. +.It Ar d +Print debugging information about directory searching and caching. +.It Ar f +Print debugging information about the execution of for loops. +.It Ar "g1" +Print the input graph before making anything. +.It Ar "g2" +Print the input graph after making everything, or before exiting +on error. +.It Ar j +Print debugging information about running multiple shells. +.It Ar l +Print commands in Buildfiles regardless of whether or not they are prefixed +by @ or other "quiet" flags. +Also known as "loud" behavior. +.It Ar m +Print debugging information about making targets, including modification +dates. +.It Ar s +Print debugging information about suffix-transformation rules. +.It Ar t +Print debugging information about target list maintenance. +.It Ar v +Print debugging information about variable assignment. +.El +.It Fl E Ar variable +Specify a variable whose environment value (if any) will override +macro assignments within Buildfiles. +.It Fl e +Specify that environment values override macro assignments within +makefiles for all variables. +.It Fl f Ar Buildfile +Specify a Buildfile to read instead of the default one. +If +.Ar Buildfile +is not an absolute pathname, +.Nm +will search for it as described above. +In case +.Ar Buildfile +is +.Sq Fl , +standard input is read. +Multiple +.Fl f +options can be supplied, +and the makefiles will be read in that order. +Unlike the other command-line options, +.Fl f +is neither stored in +.Va .MAKEFLAGS +nor pushed down to sub-makes via +.Ev MAKEFLAGS . +See below for more details on these variables. +.It Fl I Ar directory +Specify a directory in which to search for Buildfiles and included Buildfiles. +Multiple +.Fl I +options can be specified to form a search path. +The system makefile directory (or directories, see the +.Fl m +option) is automatically appended at the tail of this path. +.It Fl i +Ignore non-zero exit of shell commands in the makefile. +Equivalent to specifying +.Sq Ic \- +before each command line in the makefile. +.It Fl j Ar max_jobs +Specify the maximum number of jobs that +.Nm +may have running at any one time. +Turns compatibility mode off, unless the +.Fl B +flag is also specified. +.It Fl k +Continue processing after errors are encountered, but only on those targets +that do not depend on the target whose creation caused the error. +.It Fl m Ar directory +Specify a directory in which to search for +the system makefile and makefiles included via the <...> style. +Multiple +.Fl m +options can be specified to form a search path. +This path will override the default system include path, +.Pa /usr/share/mk . +The system include path will always be appended to the search path used +for "..."-style inclusions and makefile searches (see the +.Fl I +option). +.It Fl n +Display the commands that would have been executed, but do not actually +execute them. +.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 p +Only print the input graph, not executing any commands. +The output is the same as +.Fl d Ar g1 . +When combined with +.Fl f Pa /dev/null , +only the builtin rules of +.Nm +are displayed. +.It Fl Q +Do not generate metadata files during build. +Do not use this option if you plan to do an update build later. +.It Fl q +Do not execute any commands, but exit 0 if the specified targets are +up-to-date and 1, otherwise. +.It Fl r +Do not process the system makefile. +.It Fl S +Stop processing when an error is encountered. +Default behaviour. +This is needed to negate the +.Fl k +option during recursive builds. +.It Fl s +Echo all commands as they are executed. +This increases the verbosity of the output of +.Nm +which defaults to not echoing commands as they are executed. +.It Fl t +Rather than re-building a target as specified in the makefile, create it +or update its modification time to make it appear up-to-date. +.It Fl V Ar variable +Print +.Nm Ns 's +idea of the value of +.Ar variable , +in the global context. +Do not build any targets. +Multiple instances of this option may be specified; +the variables will be printed one per line, +with a blank line for each null or undefined variable. +.It Fl v +Be extra verbose. +Print any extra information. +.It Fl X +When using the +.Fl V +option to print the values of variables, +do not recursively expand the values. +.It Ar variable Ns No = Ns Ar value +Set the value of the variable +.Ar variable +to +.Ar value . +.It Fl x Ar warning_options +Specify extended warning options. +This option may be specified several times. +A +.Ar warning_option +can be prefixed with +.Dq Li no +in which case the warning is switched off. +The currently available options are: +.Bl -tag -width indent +.It Li dirsyntax +Warn if anything except blanks and comments follows an +.Ic .endif +or +.Ic .else +directive. +.El +.Pp +See also the +.Ic .WARN +special target. +.El +.Pp +There are seven different types of lines in a makefile: file dependency +specifications, shell commands, variable assignments, include statements, +conditional directives, for loops, and comments. +.Pp +In general, lines may be continued from one line to the next by ending +them with a backslash +.Pq Ql \e . +The trailing newline character and initial whitespace on the following +line are compressed into a single space. +.Sh FILE DEPENDENCY SPECIFICATIONS +Dependency lines consist of one or more targets, an operator, and zero +or more sources. +This creates a relationship where the targets +.Dq depend +on the sources +and are usually created from them. +The exact relationship between the target and the source is determined +by the operator that separates them. +The three operators are as follows: +.Bl -tag -width flag +.It Ic \&: +A target is considered out-of-date if its modification time is less than +those of any of its sources. +Sources for a target accumulate over dependency lines when this operator +is used. +The target is removed if +.Nm +is interrupted. +.It Ic \&! +Targets are always re-created, but not until all sources have been +examined and re-created as necessary. +Sources for a target accumulate over dependency lines when this operator +is used. +The target is removed if +.Nm +is interrupted. +.It Ic :: +If no sources are specified, the target is always re-created. +Otherwise, a target is considered out-of-date if any of its sources has +been modified more recently than the target. +Sources for a target do not accumulate over dependency lines when this +operator is used. +The target will not be removed if +.Nm +is interrupted. +.El +.Pp +Targets and sources may contain the shell wildcard expressions +.Ql \&? , +.Ql * , +.Ql [] +and +.Ql {} . +The expressions +.Ql \&? , +.Ql * +and +.Ql [] +may only be used as part of the final +component of the target or source, and must be used to describe existing +files. +The expression +.Ql {} +need not necessarily be used to describe existing files. +Expansion is in directory order, not alphabetically as done in the shell. +.Sh SHELL COMMANDS +Each target may have associated with it a series of shell commands, normally +used to create the target. +Each of the commands in this script +.Em must +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 +If the first characters of the command line are +.Sq Ic @ , +.Sq Ic \- , +and/or +.Sq Ic + , +the command is treated specially. +A +.Sq Ic @ +causes the command not to be echoed before it is executed. +A +.Sq Ic \- +causes any non-zero exit status of the command line to be ignored. +A +.Sq Ic + +causes the command to be executed even if +.Fl n +is specified on the command line. +.Sh VARIABLE ASSIGNMENTS +Variables in +.Nm +are much like variables in the shell, and, by tradition, +consist of all upper-case letters. +The five operators that can be used to assign values to variables are as +follows: +.Bl -tag -width Ds +.It Ic = +Assign the value to the variable. +Any previous value is overridden. +.It Ic += +Append the value to the current value of the variable. +.It Ic ?= +Assign the value to the variable if it is not already defined. +.It Ic := +Assign with expansion, i.e., expand the value before assigning it +to the variable. +Normally, expansion is not done until the variable is referenced. +.It Ic != +Expand the value and pass it to the shell for execution and assign +the result to the variable. +Any newlines in the result are replaced with spaces. +.El +.Pp +Any whitespace before the assigned +.Ar value +is removed; if the value is being appended, a single space is inserted +between the previous contents of the variable and the appended value. +.Pp +Variables are expanded by surrounding the variable name with either +curly braces +.Pq Ql {} +or parentheses +.Pq Ql () +and preceding it with +a dollar sign +.Pq Ql $ . +If the variable name contains only a single letter, the surrounding +braces or parentheses are not required. +This shorter form is not recommended. +.Pp +Variable substitution occurs at two distinct times, depending on where +the variable is being used. +Variables in dependency lines are expanded as the line is read. +Variables in shell commands are expanded when the shell command is +executed. +.Pp +The four different classes of variables (in order of increasing precedence) +are: +.Bl -tag -width Ds +.It Environment variables +Variables defined as part of +.Nm Ns 's +environment. +.It Global variables +Variables defined in the makefile or in included makefiles. +.It Command line variables +Variables defined as part of the command line and variables +obtained from the +.Ev MAKEFLAGS +environment variable or the +.Ic .MAKEFLAGS +target. +.It Local variables +Variables that are defined specific to a certain target. +.El +.Pp +If the name of an environment variable appears in a makefile +on the left-hand side of an assignment, +a global variable with the same name is created, and the latter +shadows the former as per their relative precedences. +The environment is not changed in this case, and the change +is not exported to programs executed by +.Nm . +However, a command-line variable actually replaces +the environment variable of the same name if the latter exists, +which is visible to child programs. +.Pp +There are seven local variables in +.Nm : +.Bl -tag -width ".ARCHIVE" +.It Va .ALLSRC +The list of all sources for this target; also known as +.Sq Va > . +.It Va .ARCHIVE +The name of the archive file; also known as +.Sq Va \&! . +.It Va .IMPSRC +The name/path of the source from which the target is to be transformed +(the +.Dq implied +source); also known as +.Sq Va < . +.It Va .MEMBER +The name of the archive member; also known as +.Sq Va % . +.It Va .OODATE +The list of sources for this target that were deemed out-of-date; also +known as +.Sq Va \&? . +.It Va .PREFIX +The file prefix of the file, containing only the file portion, no suffix +or preceding directory components; also known as +.Sq Va * . +.It Va .TARGET +The name of the target; also known as +.Sq Va @ . +.El +.Pp +The shorter forms +.Sq Va @ , +.Sq Va \&! , +.Sq Va < , +.Sq Va % , +.Sq Va \&? , +.Sq Va > , +and +.Sq Va * +are permitted for backward +compatibility and are not recommended. +The six variables +.Sq Va @F , +.Sq Va @D , +.Sq Va <F , +.Sq Va <D , +.Sq Va *F , +and +.Sq Va *D +are +permitted for compatibility with +.At V +makefiles and are not recommended. +.Pp +Four of the local variables may be used in sources on dependency lines +because they expand to the proper value for each target on the line. +These variables are +.Va .TARGET , +.Va .PREFIX , +.Va .ARCHIVE , +and +.Va .MEMBER . +.Pp +In addition, +.Nm +sets or knows about the following internal variables or environment +variables: +.Bl -tag -width ".Va .MAKEFILE_LIST" +.It Va $ +A single dollar sign +.Ql $ , +i.e.\& +.Ql $$ +expands to a single dollar +sign. +.It Va MAKE +The name that +.Nm +was executed with +.Pq Va argv Ns Op 0 . +.It Va .CURDIR +A path to the directory where +.Nm +was executed. +The +.Nm +utility sets +.Va .CURDIR +to the canonical path given by +.Xr getcwd 3 . +.It Va .OBJDIR +A path to the directory where the targets are built. +At startup, +.Nm +searches for an alternate directory to place target files. +It will attempt to change into this special directory +and will search this directory for makefiles +not found in the current directory. +The following directories are tried in order: +.Pp +.Bl -enum -compact +.It +${MAKEOBJDIRPREFIX}/`pwd` +.It +${MAKEOBJDIR} +.It +obj.${MACHINE} +.It +obj +.It +/usr/obj/`pwd` +.El +.Pp +The first directory that +.Nm +successfully changes into is used. +If either +.Ev MAKEOBJDIRPREFIX +or +.Ev MAKEOBJDIR +is set in the environment but +.Nm +is unable to change into the corresponding directory, +then the current directory is used +without checking the remainder of the list. +If they are undefined and +.Nm +is unable to change into any of the remaining three directories, +then the current directory is used. +Note, that +.Ev MAKEOBJDIRPREFIX +and +.Ev MAKEOBJDIR +must be environment variables and should not be set on +.Nm Ns 's +command line. +.Pp +The +.Nm +utility sets +.Va .OBJDIR +to the canonical path given by +.Xr getcwd 3 . +.It Va .MAKEFILE_LIST +As +.Nm +reads various makefiles, including the default files and any +obtained from the command line and +.Ic .include +and +.Ic .sinclude +directives, their names will be automatically appended to the +.Va .MAKEFILE_LIST +variable. +They are added right before +.Nm +begins to parse them, so that the name of the current makefile is the +last word in this variable. +.It Ev MAKEFLAGS +The environment variable +.Ev MAKEFLAGS +may initially contain anything that +may be specified on +.Nm Ns 's +command line, +including +.Fl f +option(s). +After processing, its contents are stored in the +.Va .MAKEFLAGS +global variable, although any +.Fl f +options are omitted. +Then all options and variable assignments specified on +.Nm Ns 's +command line, except for +.Fl f , +are appended to the +.Va .MAKEFLAGS +variable. +.Pp +Whenever +.Nm +executes a program, it sets +.Ev MAKEFLAGS +in the program's environment to the current value of the +.Va .MAKEFLAGS +global variable. +Thus, if +.Ev MAKEFLAGS +in +.Nm Ns 's +environment contains any +.Fl f +options, they will not be pushed down to child programs automatically. +The +.Nm +utility effectively filters out +.Fl f +options from the environment and command line although it +passes the rest of its options down to sub-makes via +.Ev MAKEFLAGS +by default. +.Pp +When passing macro definitions and flag arguments in the +.Ev MAKEFLAGS +environment variable, +space and tab characters are quoted by preceding them with a backslash. +When reading the +.Ev MAKEFLAGS +variable from the environment, +all sequences of a backslash and one of space or tab +are replaced just with their second character +without causing a word break. +Any other occurrences of a backslash are retained. +Groups of unquoted space, tab and newline characters cause word +breaking. +.It Va .MAKEFLAGS +Initially, this global variable contains +.Nm Ns 's +current run-time options from the environment +and command line as described above, under +.Ev MAKEFLAGS . +By modifying the contents of the +.Va .MAKEFLAGS +global variable, the makefile can alter the contents of the +.Ev MAKEFLAGS +environment variable made available for all programs which +.Nm +executes. +This includes adding +.Fl f +option(s). +The current value of +.Va .MAKEFLAGS +is just copied verbatim to +.Ev MAKEFLAGS +in the environment of child programs. +.Pp +Note that any options entered to +.Va .MAKEFLAGS +neither affect the current instance of +.Nm +nor show up in its own copy of +.Ev MAKEFLAGS +instantly. +However, they do show up in the +.Ev MAKEFLAGS +environment variable of programs executed by +.Nm . +On the other hand, a direct assignment to +.Ev MAKEFLAGS +neither affects the current instance of +.Nm +nor is passed down to +.Nm Ns 's +children. +Compare with the +.Ic .MAKEFLAGS +special target below. +.It Va MFLAGS +This variable is provided for backward compatibility and +contains all the options from the +.Ev MAKEFLAGS +environment variable plus any options specified on +.Nm Ns 's +command line. +.It Va .MAKE.PID +The process-id of +.Nm . +.It Va .MAKE.PPID +The parent process-id of +.Nm . +.It Va .MAKE.JOB.PREFIX +If +.Nm +is run with +.Fl j Fl v +then output for each target is prefixed with a token +.Ql --- target --- +the first part of which can be controlled via +.Va .MAKE.JOB.PREFIX . +.br +For example: +.Li .MAKE.JOB.PREFIX=${.newline}---${MAKE:T}[${.MAKE.PID}] +would produce tokens like +.Ql ---make[1234] target --- +or +.Li .MAKE.JOB.PREFIX=---pid[${.MAKE.PID}],ppid[${.MAKE.PPID}] +would produce tokens like +.Ql ---pid[56789],ppid[1234] target --- +making it easier to track the degree of parallelism being achieved. +.It Va .TARGETS +List of targets +.Nm +is currently building. +.It Va .INCLUDES +See +.Ic .INCLUDES +special target. +.It Va .LIBS +See +.Ic .LIBS +special target. +.It Va MACHINE +Name of the machine architecture +.Nm +is running on, obtained from the +.Ev MACHINE +environment variable, or through +.Xr uname 3 +if not defined. +.It Va MACHINE_ARCH +Name of the machine architecture +.Nm +was compiled for, defined at compilation time. +.It Va VPATH +Makefiles may assign a colon-delimited list of directories to +.Va VPATH . +These directories will be searched for source files by +.Nm +after it has finished parsing all input makefiles. +.El +.Pp +Variable expansion may be modified to select or modify each word of the +variable (where a +.Dq word +is whitespace-delimited sequence of characters). +The general format of a variable expansion is as follows: +.Pp +.Dl {variable[:modifier[:...]]} +.Pp +Each modifier begins with a colon and one of the following +special characters. +The colon may be escaped with a backslash +.Pq Ql \e . +.Bl -tag -width Cm +.Sm off +.It Cm C No / Ar pattern Xo +.No / Ar replacement +.No / Op Cm 1g +.Xc +.Sm on +Modify each word of the value, +substituting every match of the extended regular expression +.Ar pattern +(see +.Xr re_format 7 ) +with the +.Xr ed 1 Ns \-style +.Ar replacement +string. +Normally, the first occurrence of the pattern in +each word of the value is changed. +The +.Ql 1 +modifier causes the substitution to apply to at most one word; the +.Ql g +modifier causes the substitution to apply to as many instances of the +search pattern as occur in the word or words it is found in. +Note that +.Ql 1 +and +.Ql g +are orthogonal; the former specifies whether multiple words are +potentially affected, the latter whether multiple substitutions can +potentially occur within each affected word. +.It Cm E +Replaces each word in the variable with its suffix. +.It Cm H +Replaces each word in the variable with everything but the last component. +.It Cm L +Converts variable to lower-case letters. +.It Cm M Ns Ar pattern +Select only those words that match the rest of the modifier. +The standard shell wildcard characters +.Pf ( Ql * , +.Ql \&? , +and +.Ql [] ) +may +be used. +The wildcard characters may be escaped with a backslash +.Pq Ql \e . +.It Cm N Ns Ar pattern +This is identical to +.Cm M , +but selects all words which do not match +the rest of the modifier. +.It Cm O +Order every word in the variable alphabetically. +.It Cm Q +Quotes every shell meta-character in the variable, so that it can be passed +safely through recursive invocations of +.Nm . +.It Cm R +Replaces each word in the variable with everything but its suffix. +.Sm off +.It Cm S No / Ar old_string Xo +.No / Ar new_string +.No / Op Cm g +.Xc +.Sm on +Modify the first occurrence of +.Ar old_string +in each word of the variable's value, replacing it with +.Ar new_string . +If a +.Ql g +is appended to the last slash of the pattern, all occurrences +in each word are replaced. +If +.Ar old_string +begins with a caret +.Pq Ql ^ , +.Ar old_string +is anchored at the beginning of each word. +If +.Ar old_string +ends with a dollar sign +.Pq Ql $ , +it is anchored at the end of each word. +Inside +.Ar new_string , +an ampersand +.Pq Ql & +is replaced by +.Ar old_string . +Any character may be used as a delimiter for the parts of the modifier +string. +The anchoring, ampersand, and delimiter characters may be escaped with a +backslash +.Pq Ql \e . +.Pp +Variable expansion occurs in the normal fashion inside both +.Ar old_string +and +.Ar new_string +with the single exception that a backslash is used to prevent the expansion +of a dollar sign +.Pq Ql $ , +not a preceding dollar sign as is usual. +.It Ar old_string=new_string +This is the +.At V +style variable substitution. +It must be the last modifier specified. +If +.Ar old_string +or +.Ar new_string +do not contain the pattern matching character +.Ar % +then it is assumed that they are +anchored at the end of each word, so only suffixes or entire +words may be replaced. +Otherwise +.Ar % +is the substring of +.Ar old_string +to be replaced in +.Ar new_string +.It Cm T +Replaces each word in the variable with its last component. +.It Cm U +Converts variable to upper-case letters. +.It Cm u +Remove adjacent duplicate words (like +.Xr uniq 1 ) . +.El +.Sh DIRECTIVES, CONDITIONALS, AND FOR LOOPS +Directives, conditionals, and for loops reminiscent +of the C programming language are provided in +.Nm . +All such structures are identified by a line beginning with a single +dot +.Pq Ql \&. +character. +The following directives are supported: +.Bl -tag -width Ds +.It Ic .include Ar <file> +.It Ic .include Ar \*qfile\*q +Include the specified makefile. +Variables between the angle brackets +or double quotes are expanded to form the file name. +If angle brackets +are used, the included makefile is expected to be in the system +makefile directory. +If double quotes are used, the including +makefile's directory and any directories specified using the +.Fl I +option are searched before the system +makefile directory. +.It Ic .sinclude Ar <file> +.It Ic .sinclude Ar \*qfile\*q +Like +.Ic .include , +but silently ignored if the file cannot be found and opened. +.It Ic .undef Ar variable +Un-define the specified global variable. +Only global variables may be un-defined. +.It Ic .error Ar message +Terminate processing of the makefile immediately. +The filename of the +makefile, the line on which the error was encountered and the specified +message are printed to the standard error output and +.Nm +terminates with exit code 1. +Variables in the message are expanded. *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200908070146.n771k8XL071593>