summaryrefslogtreecommitdiff
path: root/usr.bin/make/make.1
diff options
context:
space:
mode:
authorchristos <christos@NetBSD.org>2014-08-23 14:50:24 +0000
committerchristos <christos@NetBSD.org>2014-08-23 14:50:24 +0000
commit429f047bae8aafd587708a7ae349656e30e0e018 (patch)
tree4242510985d80a15bfece318980bd75fc7b4ac50 /usr.bin/make/make.1
parent3acd9378e9313f3674e9e0106323e59ed24a5d27 (diff)
PR/49085: Jarmo Jaakkola: fix several parsing errors
Don't exit from var.c:Var_Parse() before possible modifiers are handled on D and F modified versions of local variables. Properly expand $(?D) and $(?F) too. Make line continuations in rule's commands POSIX compliant. Fix the syntax error caused by lib(member) as the last target before a dependency operator. Document the line continuation change in the manual page. Also talk more about the POSIX style local variables and their modifiers. Add tests covering the fixed problems into d_posix.mk. The test is a known failure at the moment because of PR 49086 and PR 49092. [XXX: unconverted tests]
Diffstat (limited to 'usr.bin/make/make.1')
-rw-r--r--usr.bin/make/make.1157
1 files changed, 125 insertions, 32 deletions
diff --git a/usr.bin/make/make.1 b/usr.bin/make/make.1
index ccc48325113..c6641706286 100644
--- a/usr.bin/make/make.1
+++ b/usr.bin/make/make.1
@@ -1,4 +1,4 @@
-.\" $NetBSD: make.1,v 1.230 2014/02/15 18:55:30 sjg Exp $
+.\" $NetBSD: make.1,v 1.231 2014/08/23 14:50:24 christos Exp $
.\"
.\" Copyright (c) 1990, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -382,8 +382,11 @@ conditional directives, for loops, and comments.
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.
+For any line that is not a shell command line (i.e. it does not begin
+with a tab), the backslash, the following newline character, and initial
+whitespace on the following line are compressed into a single space.
+On command lines the backslash and the newline are left intact and
+if the following line begins with tab(s), the first one is removed.
.Sh FILE DEPENDENCY SPECIFICATIONS
Dependency lines consist of one or more targets, an operator, and zero
or more sources.
@@ -500,20 +503,52 @@ operation does not change their behavior.
For example, any command which needs to use
.Dq cd
or
-.Dq chdir ,
-without side-effect should be put in parenthesis:
+.Dq chdir
+without side-effects should be put in parenthesis so they are executed
+in a subshell:
.Bd -literal -offset indent
avoid-chdir-side-effects:
@echo Building $@ in `pwd`
- @(cd ${.CURDIR} && ${.MAKE} $@)
+ @(cd ${.CURDIR} && ${MAKE} $@)
@echo Back in `pwd`
ensure-one-shell-regardless-of-mode:
@echo Building $@ in `pwd`; \\
- (cd ${.CURDIR} && ${.MAKE} $@); \\
+ (cd ${.CURDIR} && ${MAKE} $@); \\
echo Back in `pwd`
.Ed
+.Pp
+The backslash and the following newline are retained in the input to
+the shell, but if the next line starts with tab(s), the first one of
+those is removed.
+This allows you to align the commands in the rule without introducing
+unwanted whitespace into the command line itself.
+What happens to the backslash-newline pair is up to the shell.
+The standard shell,
+.Xr sh 1 ,
+removes them both elsewhere than in single quotes, effectively catenating
+the two lines.
+The following examples demonstrate escaped newlines in command lines.
+.Bl -column -offset indent " echo \*qfoo" "| cd dir \\"
+.It "echo-foobar:" Ta "| syntax-error:"
+.It " echo \*qfoo\\" Ta "| for i in a b\\"
+.It " bar\*q" Ta "| do\\"
+.It Ta "| echo $i\\"
+.It Ta "| done"
+.El
+.Pp
+The first one is an unnecessarily contrived way of doing
+.Bd -compact -offset indent
+.Ic "echo \*qfoobar\*q"
+.Ed
+The second one demonstrates why the semicolon is required in many places
+where in a similar looking regular shell script it wouldn't be.
+After the shell has removed the backslash newline pairs, the result
+would be the syntactically incorrect command
+.Bd -compact -offset indent
+.Ic "for i in a bdo echo $idone"
+.Ed
.Sh VARIABLE ASSIGNMENTS
Variables in make are much like variables in the shell, and, by tradition,
consist of all upper-case letters.
@@ -623,14 +658,18 @@ Variables defined in the makefile or in included makefiles.
.It Command line variables
Variables defined as part of the command line.
.It Local variables
-Variables that are defined specific to a certain target.
-The seven local variables are as follows:
+There are seven variables that are defined specific to a certain target.
+Five of these are defined in POSIX but only in their short form.
+The variables are as follows:
.Bl -tag -width ".ARCHIVE"
.It Va .ALLSRC
The list of all sources for this target; also known as
.Ql Va \&\*[Gt] .
+This variable is a non-POSIX extension.
.It Va .ARCHIVE
-The name of the archive file.
+The name of the archive file; also known as
+.Ql Va \&! .
+This variable is a non-POSIX extension.
.It Va .IMPSRC
In suffix-transformation rules, the name/path of the source from which the
target is to be transformed (the
@@ -639,7 +678,8 @@ source); also known as
.Ql Va \&\*[Lt] .
It is not defined in explicit rules.
.It Va .MEMBER
-The name of the archive member.
+The name of the archive member; also known as
+.Ql Va % .
.It Va .OODATE
The list of sources for this target that were deemed out-of-date; also
known as
@@ -648,31 +688,47 @@ known as
The file prefix of the target, containing only the file portion, no suffix
or preceding directory components; also known as
.Ql Va * .
+.Pp
+POSIX only requires this variable to be availabe for suffix transformation
+rules, but this implementation makes it available for all targets.
+If the target does not have a known suffix (see
+.Ic .SUFFIXES ) ,
+it is equivalent to
+.Ql Va .TARGET .
.It Va .TARGET
The name of the target; also known as
.Ql Va @ .
.El
.Pp
-The shorter forms
-.Ql Va @ ,
+To increase readability, the shorter forms
+.Ql ( Va @ ,
+.Ql Va \&! ,
+.Ql Va % ,
.Ql Va \&? ,
-.Ql Va \&\*[Lt] ,
-.Ql Va \&\*[Gt] ,
+.Ql Va \*[Lt] ,
+.Ql Va \*[Gt] ,
and
-.Ql Va *
-are permitted for backward
-compatibility with historical makefiles and are not recommended.
-The six variables
-.Ql Va "@F" ,
-.Ql Va "@D" ,
-.Ql Va "\*[Lt]F" ,
-.Ql Va "\*[Lt]D" ,
-.Ql Va "*F" ,
+.Ql Va * )
+should only be used when compatibility with POSIX or other implementations
+is desired.
+For compatibility with POSIX, all of the short forms may also be written
+with an appended uppercase
+.Ql D
+or
+.Ql F ,
+e.g.\&
+.Ql @D
+or
+.Ql *F .
+These modified versions replace each word in the expansion with their
+.Em directory part ( Ql D )
+or
+.Em filename part ( Ql F ) ,
+and are exactly equivalent to the
+.Cm \&:H
and
-.Ql Va "*D"
-are permitted for compatibility with
-.At V
-makefiles and are not recommended.
+.Cm \&:T
+variable modifiers, respectively.
.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.
@@ -1052,12 +1108,26 @@ If any of the modifiers in the modifier_variable contain a dollar sign
.Pq Ql $ ,
these must be doubled to avoid early expansion.
.Pp
+Variable modifiers are not POSIX compatible except for
+.Ql Cm :old_string=new_string ,
+.Ql Cm \&:H
+and
+.Ql Cm \&:T .
+Even these have notable caveats, see their individual descriptions.
+.Pp
The supported modifiers are:
.Bl -tag -width EEE
.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.
+Replaces each word in the variable with everything but the last component
+.Ql ( "head only" ) .
+In POSIX compatible makefiles this modification is only available for local
+variables and with different syntax.
+It is achieved by writing the variable with an appended
+.Ql D ,
+e.g.\&
+.Ql Va @D .
.It Cm \&:M Ns Ar pattern
Select only those words that match
.Ar pattern .
@@ -1260,7 +1330,14 @@ and
are subjected to variable expansion before being parsed as
regular expressions.
.It Cm \&:T
-Replaces each word in the variable with its last component.
+Replaces each word in the variable with its last component
+.Ql ( "tail only" ) .
+In POSIX compatible makefiles this modification is only available for local
+variables and with different syntax.
+It is achieved by writing the variable with an appended
+.Ql F ,
+e.g.\&
+.Ql Va @F .
.It Cm \&:u
Remove adjacent duplicate words (like
.Xr uniq 1 ) .
@@ -1283,7 +1360,7 @@ to determine is any words match "42" you need to use something like:
.It Ar :old_string=new_string
This is the
.At V
-style variable substitution.
+style variable substitution, later standardized in POSIX.
It must be the last modifier specified.
If
.Ar old_string
@@ -1300,6 +1377,9 @@ is the substring of
.Ar old_string
to be replaced in
.Ar new_string .
+The special meaning of
+.Ar %
+is not POSIX compatible.
.Pp
Variable expansion occurs in the normal fashion inside both
.Ar old_string
@@ -1749,7 +1829,20 @@ of three.
Comments begin with a hash
.Pq Ql \&#
character, anywhere but in a shell
-command line, and continue to the end of an unescaped new line.
+command line, and continue to the end of an
+.Em unescaped
+new line.
+This can be used to a great effect to comment out continued sections of
+a makefile but it can also lead to very subtle, and possibly difficult
+to spot, errors for that same reason.
+Please observe some actually encountered problems:
+.Bl -column -offset indent "| target: source" "| target: source" \
+ "| target: source"
+.It "#OLD_NAME =\\" Ta "| VAR =\\" Ta "| #VAR2 =\\"
+.It "NEW_NAME =\\" Ta "| foo\\" Ta "| # foo\\"
+.It "foo\\" Ta "| # bar\\" Ta "| # bar\\"
+.It "bar" Ta "| baz" Ta "| target: source"
+.El
.Sh SPECIAL SOURCES (ATTRIBUTES)
.Bl -tag -width .IGNOREx
.It Ic .EXEC