docs: New plan for directory references, further

[subdirmk.git] / README

diff --git a/README b/README
index cc309f6ae1ec796febb92b7b4fad8083f2d9669d..3059d9a105cfb57a9071a4da0f50e9cc19783a62 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,33 @@ 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 recommended directory reference syntaxes
+---------------------------------------------------
+
+Path construction &-expansions, meanings summary:
+
+                      In build tree            In source tree
+  This directory      just &                   &,
+  Top level           &.  implies absolute     &;
+
+Adding `@' means "absolute path".  This is not needed with &. because
+there is never any need to use &. since it would expand to nothing.
+`/' terminates the escape (needed if the next thing is not a lowercase
+character, or space).  `=' means "just the value, no /".  Space starts
+multi-word processing.
+
+      Recommended     In build tree             In source tree
+             when     Relative  Absolute        Relative     Absolute
+                                          
+  This       lc       &file     &@file          &,file       &@,file
+  directory  any      &/file    &@/file         &,/file      &@,/file
+             several  & f g h   &@ f g h        &, f g h     &@, f g h
+
+  Top        lc                 &.file          &;file       &@;file
+  level      any      file      &./file         &;/file      &@;/file
+             several  f g h     &. f g h        &; f g h     &@; f g h
+             .mk.in   file      $(abs)/file     $(src)/file  $(abs_src)/file
+

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


@@ -169,6 +196,11 @@ empty string).
 &^             =>      $(top_srcdir)/sub/dir           or $(top_srcdir)
 &~             =>      $(abs_top_srcdir)/sub/dir       or $(abs_top_srcdir)
 
 &^             =>      $(top_srcdir)/sub/dir           or $(top_srcdir)
 &~             =>      $(abs_top_srcdir)/sub/dir       or $(abs_top_srcdir)
 

+In general:
+        ^       filenames in source tree rather than build tree
+        ~       filenames are absolute rather than relative
+        @       filenames do not contain subdir (useful with the above)
+

 &&             =>      &&              for convenience in shell runes
 \&             =>      &               general escaping mechanism
 
 &&             =>      &&              for convenience in shell runes
 \&             =>      &               general escaping mechanism
 


@@ -193,7 +225,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 +307,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
 -----------------