syntax: Support &: literal (for make `grouped' multiple targets)

[subdirmk.git] / README

diff --git a/README b/README
index a44fb492b47301ea3bbbef8c102c645c5e4c9f8c..bea3c1b5ed053caaeb8078f821361add0778a0da 100644 (file)
--- a/README
+++ b/README
@@ -88,13 +88,13 @@ empty string).
 
 &=             =>      sub_dir                         or TOP
 
-&^lc           =>      $(top_srcdir)/sub/dir/lc
-&^/            =>      $(top_srcdir)/sub/dir/
-&^.            =>      $(top_srcdir)/sub/dir
+&^lc           =>      ${top_srcdir}/sub/dir/lc
+&^/            =>      ${top_srcdir}/sub/dir/
+&^.            =>      ${top_srcdir}/sub/dir
 
-&~lc           =>      $(top_srcdir)/lc
-&~/            =>      $(top_srcdir)/
-&~.            =>      $(top_srcdir)
+&~lc           =>      ${top_srcdir}/lc
+&~/            =>      ${top_srcdir}/
+&~.            =>      ${top_srcdir}
 
 In general:
     ^   pathname of this subdirectory in source tree
@@ -114,7 +114,7 @@ So pathname syntax is a subset of:
 &\$            =>      $               provided for $-doubling regimes
 &\NEWLINE                              eats the newline and vanishes
 
-&$VARIABLE     =>      $(sub_dir_VARIABLE)     or $(TOP_VARIABLE)
+&$VARIABLE     =>      ${sub_dir_VARIABLE}     or ${TOP_VARIABLE}
        VARIABLE is ASCII starting with a letter and matching \w+
 
 & thing thing... &
@@ -130,6 +130,10 @@ So pathname syntax is a subset of:
 &:<directive> <args>....
        recognised at start of line only (possibly after lwsp)
 
+&:             =>      &:
+       for make multiple targets syntax
+       recognised anywhere *except* start of line
+
 &:include filename             filename should usually be [&]foo.sd.mk
 &:-include filename            tolerate nonexistent file
        RHS is &-expanded but filenames are relative to the top
@@ -166,6 +170,9 @@ So pathname syntax is a subset of:
        `all' is extra special: every directory has an `all'
        target, which corresponds to &TARGETS.
 
+Directives
+- - - - -
+
 &:warn [!]WARNTAG ...
        Suppress (with !) or re-enable (without !) warnings tagged
        WARNTAG (see section `Warnings', below).  The suppression list
@@ -174,10 +181,11 @@ So pathname syntax is a subset of:
        by the final warning state after processing all the toplevel
        input files (including Final.sd.mk).
 
-&:local+global [&]VARIABLE ...
-       Suppresses the warning about seeing both VARIABLE and
-       &VARIABLE.  Any & specified in the RHS is redundant: this
-       always affects both versions identically.
+&:local+global [!][&]VARIABLE ...
+       Suppresses any warnings relating to forthcoming mentions
+       to VARIABLE or &VARIABLE, as applicable.  Scope ends at
+       the end of the current directory's Suffix.sd.mk.
+       Prefixing with ! removes [&]VARIABLE from the suppresion list.
 
 &:changequote NEWQUOTE
        changes the escape sequence from & to literally NEWQUOTE
@@ -205,6 +213,10 @@ Dollar doubling and macro assistance
 &$-            Stops dollar-doubling
        Both are idempotent and local to the file or context.
 
+This is useful both for make macrology involving $(eval ...), and
+possibly for helping write complicated recipes involving shell
+variables, inline Perl code, etc.
+
 Sometimes we will show $'s being doubled inside another construct.
 This means the content of the construct is $-doubled: $-doubling is
 locally enabled, and restored afterwards.
@@ -214,9 +226,10 @@ STUFF $ THINGS     ..      STUFF $$ THINGS
 &:endm         ..      endef
        NAME is processed for &
 
-&${..$..} =>   ${eval ${call ..$$..}}
+&{..$..}       =>      ${eval ${call ..$$..}}
        (matches { } pairs to find the end)
        content is $-doubled (unless it contains &$- to turn that off)
+       cf &(...), see "Convenience syntax for eval", below.
 
 Together &:macro and &${...} provide a more reasonable macro facility
 than raw make.  They solve the problem that make expansions cannot
@@ -233,13 +246,25 @@ $ =>      $$      including $'s produced by other
                         &-expansions not mentioned here
 
 &\$    =>      $
-&$NN   =>      $(NN)   where N are digits
 &$(    =>      $(
+&$NN   =>      ${NN}   where N are digits
 
 A few contexts do not support $-doubling, such as directive arguments
 or places where this might imply $-quadrupling.  (There is no way to
 get $-quadrupling.)
 
+Convenience syntax for eval
+- - - - - - - - - - - - - -
+
+&(thing                =>      $(call thing
+&( thing       =>      $(call thing
+       and specially:
+&(&lc          =>      $(call sub_dir_lc       or $(call TOP_lc
+&( &lc         =>      $(call sub_dir_lc       or $(call TOP_lc
+       even though lc would normally be thought a filename
+
+Unlike &{...}, this does not involve any dollar-doubling.
+
 
 Invocation, "recursive" per-directory targets
 ---------------------------------------------
@@ -334,7 +359,12 @@ suppressed with the &:warn directive.  The warning tags are:
        interpret this as $(F)BAR.  It's normally better to write
        it this way, at least if the variable expansion is followed
        by more letters.  Note that &$FOO works differently to
-       raw make: it expands to $(sub_dir_FOO).
+       raw make: it expands to ${sub_dir_FOO}.
+
+    broken-var-ref
+        An attempt at variable expansion looking like $&...
+       You probably expected this to mean $(TOP_F)BAR but it
+       expands to $TOP_FBAR which make thinks means $(T)OP_FBAR.
 
     unknown-warning
        &:warn was used to try to enable a warning that this version
@@ -402,7 +432,7 @@ far enough to regenerate a working set of makefiles.  If this happens
 just rerun ./config.status by hand.
 
 If you go back and forth between different versions of your code you
-can sometimes find that `make' complains that one of your Subdir.sd.mk
+can sometimes find that `make' complains that one of your Dir.sd.mk
 files is missing: typically, if iot was used and therefore a
 dependency in some other version of your code.  If you run `make
 clean' (or `make realclean') these dependencies are suppressed, which