X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?p=subdirmk.git;a=blobdiff_plain;f=README;h=518dd087d853308b13e07aab805349714288d26e;hp=5897e308644050ec8006fe42e830816ed03f0fb2;hb=eefd9e096adc7360a0dd7c994cb8b5c09468c12e;hpb=9280923e03ea7603e19fabed95d600bcc928a1cf

diff --git a/README b/README
index 5897e30..518dd08 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
@@ -103,6 +105,19 @@ is already provided in subdirmk, for you to reference like this:
   &:include subdirmk/clean.sd.mk
 For example you could put that in Perdir.sd.mk.
 
+The top-level Subdir.sd.mk is the first makefile included after the
+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.
+
+subdirmk's filter script itself sets (only) these variables:
+  top_srcdir
+  abs_top_srcdir
+  SUBDIRMK_MAKEFILES
+  MAKEFILE_TEMPLATES
+You are likely to want to define $(PWD), and shorter names for
+top_srdir and abs_top_srcdir (we suggest $(src) and $(abs_src)).
+
 Global definitions
 ------------------
 
@@ -138,18 +153,46 @@ 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.
 
-Summary of directory reference syntaxes
----------------------------------------
+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 source tree             In build tree
-                  Relative     Absolute      Relative  Absolute
+In more detail, with all the various options laid out:
 
-                                             &file     $(abs)/&file
- This directory   &^/file      &~/file       &/file    $(abs)/&/file
-                  & ^ f g h    & ~ f g h     & f g h
+      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...)
 
- Top level        $(ts)/file   $(ats)/file   file      $(abs)/file
-                                             f g h
+(This assumes you have appropriate make variables src, PWD and
+abs_src.)
 
 Substitution syntax
 -------------------
@@ -176,22 +219,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.