[src/trunk]: src/usr.bin/make Add some notes on compatibility with other make...

[dholland <dholland%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/254dd6bfdfaf
branches:  trunk
changeset: 332289:254dd6bfdfaf
user:      dholland <dholland%NetBSD.org@localhost>
date:      Sun Sep 14 04:32:07 2014 +0000

description:
Add some notes on compatibility with other make dialects.

I was originally intending to preserve some of Jarmo Jaakkola's notes
on POSIX make from the PR 49085 changes... but really there's no point
wandering into details about $? and such when the big picture is
"almost everything in this manual works only in BSD make".

Maybe the exact details can be stuffed into a chapter of the mythical
make reference manual if that ever gets (re)written.

diffstat:

 usr.bin/make/make.1 |  82 ++++++++++++++++++++++++++++++++++++++++++++++++----
 1 files changed, 75 insertions(+), 7 deletions(-)

diffs (103 lines):

diff -r 443cd76ae44c -r 254dd6bfdfaf usr.bin/make/make.1
--- a/usr.bin/make/make.1       Sun Sep 14 03:50:28 2014 +0000
+++ b/usr.bin/make/make.1       Sun Sep 14 04:32:07 2014 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: make.1,v 1.240 2014/09/14 03:50:28 dholland Exp $
+.\"    $NetBSD: make.1,v 1.241 2014/09/14 04:32:07 dholland Exp $
 .\"
 .\" Copyright (c) 1990, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -2149,19 +2149,87 @@
 system makefile directory
 .El
 .Sh COMPATIBILITY
-The basic make syntax is compatible between different versions of make,
+The basic make syntax is compatible between different versions of make;
 however the special variables, variable modifiers and conditionals are not.
-.Pp
-The way that parallel makes are scheduled changed in
-.Nx 4.0
-so that .ORDER and .WAIT apply recursively to the dependent nodes.
-The algorithms used may change again in the future.
+.Ss Older versions
+An incomplete list of changes in older versions of
+.Nm :
 .Pp
 The way that .for loop variables are substituted changed after
 .Nx 5.0
 so that they still appear to be variable expansions.
 In particular this stops them being treated as syntax, and removes some
 obscure problems using them in .if statements.
+.Pp
+The way that parallel makes are scheduled changed in
+.Nx 4.0
+so that .ORDER and .WAIT apply recursively to the dependent nodes.
+The algorithms used may change again in the future.
+.Ss Other make dialects
+Other make dialects (GNU make, SVR4 make, POSIX make, etc.) do not
+support most of the features of
+.Nm
+as described in this manual.
+Most notably:
+.Bl -bullet -offset indent
+.It
+The
+.Ic .WAIT
+and
+.Ic .ORDER
+declarations and most functionality pertaining to parallelization.
+(GNU make supports parallelization but lacks these features needed to
+control it effectively.)
+.It
+Directives, including for loops and conditionals and most of the
+forms of include files.
+(GNU make has its own incompatible and less powerful syntax for
+conditionals.)
+.It
+All built-in variables that begin with a dot.
+.It
+Most of the special sources and targets that begin with a dot,
+with the notable exception of
+.Ic .PHONY ,
+.Ic .PRECIOUS ,
+and
+.SUFFIXES .
+.It
+Variable modifiers, except for the
+.Dl :old=new
+string substitution, which does not portably support globbing with
+.Ql %
+and historically only works on declared suffixes.
+.It
+The
+.Ic $>
+variable even in its short form; most makes support this functionality
+but its name varies.
+.El
+.Pp
+Some features are somewhat more portable, such as assignment with
+.Ic += ,
+.Ic ?= ,
+and
+.Ic != .
+The
+.Ic .PATH
+functionality is based on an older feature
+.Ic VPATH
+found in GNU make and many versions of SVR4 make; however,
+historically its behavior is too ill-defined (and too buggy) to rely
+upon.
+.Pp
+The
+.Ic $@
+and
+.Ic $<
+variables are more or less universally portable, as is the
+.Ic $(MAKE)
+variable.
+Basic use of suffix rules (for files only in the current directory,
+not trying to chain transformations together, etc.) is also reasonably
+portable.
 .Sh SEE ALSO
 .Xr mkdep 1
 .Sh HISTORY