X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?p=subdirmk.git;a=blobdiff_plain;f=README;h=c9e4c0f9234f2fe42bac8187dd98c88784bb417a;hp=f481157e315c3c3c09babbccfec9805edd78e4e1;hb=0a6ac67828982aca4e3c8ac73669420a30c70f34;hpb=6cf829ff0dd68b88bfb56a0b7ff8020023aedf57

diff --git a/README b/README
index f481157..c9e4c0f 100644
--- a/README
+++ b/README
@@ -28,15 +28,17 @@ Basic approach
 The developer is expected to write a makefile fragment, in each
 relevant subdirectory, called `Subdir.sd.mk'.
 
-These fragments may contain ordinary make language.
+These fragments may contain ordinary make language.  Unqualified
+filenames are relative to the build toplevel, and all commands all run
+there.
 
 However, the sigil & is treated specially.  By and large, it refers to
-`the current directory'.  There are a variety of convenient
-constructions.
+`the build directory corresponding to this .sd.mk file', etc.
+There are a variety of convenient constructions.
 
 The result is that to a large extent, the Subdir.sd.mk has an easy way
 to namespace its "local" make variables, and an easy way to refer to
-its "local" filenames.
+its "local" filenames (and filenames in general).
 
 The Subdir.sd.mk's are filtered, fed through autoconf in the usual way
 (for @..@-substitutions) and included by one autogenerated toplevel
@@ -138,6 +140,47 @@ If you `include subdirmk/regen.mk', dependency management and
 automatic regeneration for all of this template substitution, and for
 config.status etc. is done for you.
 
+Tables of file reference syntaxes
+---------------------------------
+
+In a nonrecursive makefile supporting out of tree builds there are
+three separate important distinctions between different file
+locations:
+
+ (i) In the build tree, or in the source tree ?
+
+ (ii) In (or relative to) the subdirectory to which this Subdir.sd.mk
+     relates, or relative to the project's top level ?
+
+ (iii) Absolute or relative pathname ?  Usually relative pathnames
+     suffice.  Where an absolute pathname is needed, it can be built
+     out of &/ and an appropriate make variable such as $(PWD).
+
+Path construction &-expansions are built from the following:
+
+                      Relative paths in...
+                      build     source
+                                                       
+  This directory      &         &,
+  Top level           .         &;
+
+In more detail, with all the various options laid out:
+
+      Recommended     Relative paths in...   Absolute paths in...
+             for      build     source       build         source
+                                                       
+  This       lc       &file     &,file       $(PWD)/&file  $(abs_src)/&file
+  directory  any      &/file    &,/file      $(PWD)&/file  $(abs_src)/&/file
+             several  & f g h   &, f g h     $(addprefix...)
+                                             
+  Top        lc       file      &;file
+  level      any      file      &;/file      $(PWD)/file   $(abs_src)/file
+             .mk.in   file      $(src)/file  $(PWD)/file   $(abs_src)/file
+             several  f g h     &; f g h     $(addprefix...)
+
+(This assumes you have appropriate make variables src, PWD and
+abs_src.)
+
 Substitution syntax
 -------------------
 
@@ -163,22 +206,37 @@ empty string).
 	variables usually uppercase.  Otherwise, use another syntax:
 
 &_		=>	sub_dir_			or TOP_
-&/		=>	sub/dir/			or nothing
 &=_		=>	sub_dir				or TOP
+
+&/		=>	sub/dir/			or nothing
 &=/		=>	sub/dir				or .
-&^		=>	$(top_srcdir)/sub/dir		or $(top_srcdir)
-&~		=>	$(abs_top_srcdir)/sub/dir	or $(abs_top_srcdir)
+
+&,lc		=>	$(top_srcdir)/sub/dir/lc
+&,/		=>	$(top_srcdir)/sub/dir/
+
+&;lc		=>	$(top_srcdir)/lc
+&;/		=>	$(top_srcdir)/
+
+In general:
+    =	return subdir without delimiter (not allowed with `,' `;')
+    ,   pathname of this subdirectory in source tree
+    ;   pathname of top level of source tree
+    /	terminates the escape (needed if next is not lwsp or space)
+  lwsp  starts multi-word processing (see below)
+
+So pathname syntax is a subset of:
+    '&' [ ',' | ';' ] [ lc | '/' ]
 
 &&		=>	&&		for convenience in shell runes
 \&		=>	&		general escaping mechanism
 
 & thing thing... &
-& ^ thing thing... &
-& ~ thing thing... &
+&, thing thing... &
+&; thing thing... &
 	Convenience syntax for prefixing multiple filenames.
-	Introduced by & followed by lwsp (space or tab).
-	Each lwsp-separated non-ws word is prefixed by &/ &^/ &~/
-	respectively.  No other & escapes are recognised.
+	Introduced by & followed by lwsp where lc could go.
+	Each lwsp-separated non-ws word is prefixed by &/ etc.
+        etc. respectively.  No other & escapes are recognised.
 	This processing continues until & preceded by lwsp,
 	or until EOL (the end of the line), or \ then EOL.
 
@@ -282,7 +340,10 @@ You can convert your project incrementally.  Start with the top-level
 Makefile.in and rename it to Subdir.sd.mk, and add the appropriate
 stuff to configure.ac, and fix everything up.  Leave the existing
 $(MAKE) -C for your existing subdirectories alone.  Then you can
-convert individual subdirectories, or classes of subdirectories.
+convert individual subdirectories, or classes of subdirectories, at
+your leisure.  (You must be /sure/ that each subdirectory will be
+entered only once at a time, but your existing recursive make descent
+system should already do that or you already have concurrency bugs.)
 
 Aside from this, be very wary of any invocation of $(MAKE) anywhere.
 This is a frequent source of concurrency bugs in recursive make build