docs: Summarise directory reference syntaxes

[subdirmk.git] / README

diff --git a/README b/README
index cc309f6ae1ec796febb92b7b4fad8083f2d9669d..5897e308644050ec8006fe42e830816ed03f0fb2 100644 (file)
--- a/README
+++ b/README
@@ -83,7 +83,7 @@ individual targets (as specified according to their dependencies).
 
 You can define other per-directory recursive targets too: simply
 mention (usually, by setting) the variable &TARGETS_zonk, or whatever.
 
 You can define other per-directory recursive targets too: simply
 mention (usually, by setting) the variable &TARGETS_zonk, or whatever.

-This will create a src/zonk target.
+This will create a src/zonk target (for appropriate value of src/).

 Unlike `all', these other targets only exist in areas of the project
 where at least something mentions them.  So for example, if
 &TARGETS_zonk is mentioned in src but not lib, `make zonk' in
 Unlike `all', these other targets only exist in areas of the project
 where at least something mentions them.  So for example, if
 &TARGETS_zonk is mentioned in src but not lib, `make zonk' in


@@ -93,7 +93,7 @@ mention its name in Perdir.sd.mk (see below).
 Perdir.sd.mk, inclusion
 -----------------------
 
 Perdir.sd.mk, inclusion
 -----------------------
 

-The file Perdir.sd.mk in the toplevel of fthe source is automatically
+The file Perdir.sd.mk in the toplevel of the source is automatically

 processed after each individual directory's Subdir.sd.mk, and the
 &-substituted contents therefore appear once for each subdirectory.
 
 processed after each individual directory's Subdir.sd.mk, and the
 &-substituted contents therefore appear once for each subdirectory.
 


@@ -138,6 +138,19 @@ 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.
 
 automatic regeneration for all of this template substitution, and for
 config.status etc. is done for you.
 

+Summary of directory reference syntaxes
+---------------------------------------
+
+                  In source tree             In build tree
+                  Relative     Absolute      Relative  Absolute
+
+                                             &file     $(abs)/&file
+ This directory   &^/file      &~/file       &/file    $(abs)/&/file
+                  & ^ f g h    & ~ f g h     & f g h
+
+ Top level        $(ts)/file   $(ats)/file   file      $(abs)/file
+                                             f g h
+

 Substitution syntax
 -------------------
 
 Substitution syntax
 -------------------
 


@@ -193,7 +206,7 @@ empty string).
 &!<lwsp>       disables & until EOL (and then disappears)
 
 &#     delete everything to end of line
 &!<lwsp>       disables & until EOL (and then disappears)
 
 &#     delete everything to end of line

-       (useful if the RHS contains unrecognise & constructions)
+       (useful if the RHS contains unrecognised & constructions)

 
 &!STUFF
        changes the escape sequence from & to literally STUFF
 
 &!STUFF
        changes the escape sequence from & to literally STUFF


@@ -275,6 +288,31 @@ have:
   &:include subdirmk/cdeps.sd.mk
   &:include subdirmk/clean.sd.mk
 
   &:include subdirmk/cdeps.sd.mk
   &:include subdirmk/clean.sd.mk
 

+Hints
+-----
+
+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, 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
+systems.  When combined with nonrecursive make it's all in the same
+directory and there is nothing stopping the different invocations
+ending up trying to make the same targets at the same time. That
+causes hideous racy lossage.  There are ways to get this to work
+reliably but it is advanced stuff.
+
+If you make syntax errors, or certain kinds of other errors, in your
+makefiles, you may find that just `make' is broken now and cannot get
+far enough to regenerate a working set of makefiles.  If this happens
+just rerun ./config.status by hand.
+

 
 Legal information
 -----------------
 
 Legal information
 -----------------