X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=subdirmk%2FREADME;h=256fdbc8e7e8ef54b83ecdd9362ebd93225d0c28;hb=3ab6a4c8c214d9f050112249359bc4e0f7876a58;hp=28cff6ede159050a46044db7efdcac2abf40c422;hpb=b1f14d76cfc604fedd57499c6d8ce44a91391067;p=subdirmk.git

diff --git a/subdirmk/README b/subdirmk/README
index 28cff6e..256fdbc 100644
--- a/subdirmk/README
+++ b/subdirmk/README
@@ -26,7 +26,7 @@ Basic approach
 --------------
 
 The developer is expected to write a makefile fragment in each
-relevant subdirectory called `Subdir.mk.in'.
+relevant subdirectory called `Subdir.sd.mk'.
 
 These fragments may contain ordinary make language.
 
@@ -34,11 +34,11 @@ However, the sigil & is treated specially.  By and large, it refers to
 `the current directory'.  There are a variety of convenient
 constructions.
 
-The result is that to a large extent, the Subdir.mk.in has an easy way
+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.
 
-The Subdir.mk.in's are filtered, fed through autoconf in the usual way
+The Subdir.sd.mk's are filtered, fed through autoconf in the usual way
 (for @..@-substitutions) and included by one autogenerated toplevel
 makefile.
 
@@ -50,7 +50,7 @@ Each subdirectory is also provided with an autogenerated `Makefile'
 which exists purely to capture ordinary make invocations and arrange
 for something suitable to happen.
 
-Where there are dependencies between subdirectories, each Subdir.mk.in
+Where there are dependencies between subdirectories, each Subdir.sd.mk
 can simply refer to files in other subdirectories directly.
 
 Invocation, "recursive" per-directory targets
@@ -66,7 +66,7 @@ But `foo' can also be a conventional target like `all'.
 Each subdirectory has its own `all' target.  For example a
 subdirectory `src' has a target `src/all'.  The rules for these are
 automatically generated from the settings of the per-directory
-&TARGETS variables.  (In src/Subdir.mk.in, this of course refers to a
+&TARGETS variables.  (In src/Subdir.sd.mk, this of course refers to a
 make variable called src_TARGETS.)
 
 The `all' target in a parent directory is taken to imply the `all'
@@ -86,24 +86,42 @@ 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
 lib will fail.  If you want to make a target exist everywhere,
-mention its name in Perdir.mk.in (see below).
+mention its name in Perdir.sd.mk (see below).
 
-Perdir.mk.in, inclusion
+Perdir.sd.mk, inclusion
 -----------------------
 
-The file Perdir.mk.in in the toplevel of fthe source is automatically
-processed after each individual directory's Subdir.mk.in, and the
+The file Perdir.sd.mk in the toplevel of fthe source is automatically
+processed after each individual directory's Subdir.sd.mk, and the
 &-substituted contents therefore appear once for each subdirectory.
 
 This lets you do per-directory boilerplate.  Some useful boilerplate
 is already provided in subdirmk, for you to reference like this:
-  &:include subdirmk/cdeps.mk.in
-  &:include subdirmk/clean.mk.in
+  &:include subdirmk/cdeps.sd.mk
+  &:include subdirmk/clean.sd.mk
+(for example in Perdir.sd.mk).
 
-Note that you must use &:include, which is an include processed during
-the generation of the per-directory Subdir.mk files.  That ensures
-that the contents of these files is replicated, with appropriate
-per-directory substitutions, for each directory.
+Subdirectory templates `.sd.mk' vs plain autoconf templates `.mk.in'
+--------------------------------------------------------------------
+
+There are two kinds of template files.
+
+ Filename                 .sd.mk                  .mk.in
+
+ Processed by             &-substitution,         autoconf only
+                          then autoconf
+
+ Need to be mentioned     No, but Subdir.sd.mk    All not in subdirmk/
+ in configure.ac          via SUBDIRMK_SUBDIRS    via SUBDIRMK_MAKEFILES
+
+ 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
+                           Subdir and Perdir)
+
+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.
 
 Global definitions
 ------------------