Error handling: Better reporting of nest-related errors

[subdirmk.git] / README

diff --git a/README b/README
index 5e78187942da813ac76be9ff07b9c9cada4cd232..20658ae2adc3087e1f24db87cababc19aaa154b9 100644 (file)
--- a/README
+++ b/README
@@ -93,8 +93,8 @@ zonk' in lib will fail.  If you want to make a target exist
 everywhere, += it with nothing in Prefix.sd.mk or Suffix.sd.mk (see
 below).
 
 everywhere, += it with nothing in Prefix.sd.mk or Suffix.sd.mk (see
 below).
 

-Prefix.sd.mk, Suffix.sd.mk, inclusion
--------------------------------------
+Prefix.sd.mk, Suffix.sd.mk, Final.sd.mk, inclusion
+--------------------------------------------------

 
 The files Prefix.sd.mk and Suffix.sd.mk in the toplevel of the source
 are automatically processed before and after each individual
 
 The files Prefix.sd.mk and Suffix.sd.mk in the toplevel of the source
 are automatically processed before and after each individual


@@ -112,6 +112,9 @@ autogenerated `main.mk' which merely has some basic settings and
 includes.  So if you want to get in early and set global variables,
 put them near the top of Subdir.sd.mk.
 
 includes.  So if you want to get in early and set global variables,
 put them near the top of Subdir.sd.mk.
 

+The file Final.sd.mk in the toplevel directory is processed and
+included after all the other files.
+

 subdirmk's filter script itself sets (only) these variables:
   top_srcdir
   abs_top_srcdir
 subdirmk's filter script itself sets (only) these variables:
   top_srcdir
   abs_top_srcdir


@@ -149,7 +152,7 @@ There are two kinds of template files.
  How to include           `&:include foo.sd.mk'   `include foo.mk'
                          in all relevant .sd.mk  in only one
                           (but not needed for     Subdir.sd.mk
  How to include           `&:include foo.sd.mk'   `include foo.mk'
                          in all relevant .sd.mk  in only one
                           (but not needed for     Subdir.sd.mk

-                           Prefix, Suffix)
+                           Prefix, Suffix, Final)

 
 If you `include subdirmk/regen.mk', dependency management and
 automatic regeneration for all of this template substitution, and for
 
 If you `include subdirmk/regen.mk', dependency management and
 automatic regeneration for all of this template substitution, and for


@@ -251,7 +254,7 @@ So pathname syntax is a subset of:
 &&             =>      &&              for convenience in shell runes
 
 &\&            =>      &               general escaping mechanism
 &&             =>      &&              for convenience in shell runes
 
 &\&            =>      &               general escaping mechanism

-&\$            =>      $
+&\$            =>      $               provided for $-doubling regimes

 &\NEWLINE                              eats the newline and vanishes
 
 &$VARIABLE     =>      $(sub_dir_VARIABLE)     or $(TOP_VARIABLE)
 &\NEWLINE                              eats the newline and vanishes
 
 &$VARIABLE     =>      $(sub_dir_VARIABLE)     or $(TOP_VARIABLE)


@@ -320,6 +323,47 @@ So pathname syntax is a subset of:
        `all' is extra special: every directory has an `all'
        target, which corresponds to &TARGETS.
 
        `all' is extra special: every directory has an `all'
        target, which corresponds to &TARGETS.
 

+
+Dollar doubling and macro assistance
+------------------------------------
+
+&$+            Starts dollar-doubling
+&$-            Stops dollar-doubling
+       Both are idempotent and local to the file or context.
+
+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.
+
+&:macro NAME   =>      define NAME
+STUFF $ THINGS ..      STUFF $$ THINGS
+&:endm         ..      endef
+       NAME is processed for &
+
+&${..$..} =>   ${eval ${call ..$$..}}
+       (matches { } pairs to find the end)
+       content is $-doubled (unless it contains $- to turn that off)
+
+       Together &:macro and &${...} provide a more reasonable macro
+       facility than raw make.  They solve the problem that make
+       expansions cannot directly generate multiple rules, variable,
+       etc.; instead, `$(eval )' must be used, but that re-expands
+       the argument, meaning that all the literal text must be
+       $-doubled.  This applies to the macro text and to the
+       arguments.  Also `$(eval $(call ...))' is an unfortunate syntax.
+       Hence &:macro and &${...}.
+
+While dollar-doubling:
+- - - - - - - - - - -
+
+$      =>      $$      including $'s produced by other
+                        &-expansions not mentioned here
+
+&\$    =>      $
+&$NN   =>      $(NN)   where N are digits
+&$(    =>      $(
+
+

 Subdirectory and variable naming
 --------------------------------
 
 Subdirectory and variable naming
 --------------------------------