make TARGETS make :: rules

[subdirmk.git] / subdirmk / README

diff --git a/subdirmk/README b/subdirmk/README
index 16a33e373d937567550c611ae4184cb662b90710..256fdbc8e7e8ef54b83ecdd9362ebd93225d0c28 100644 (file)
--- a/subdirmk/README
+++ b/subdirmk/README
@@ -26,7 +26,7 @@ Basic approach
 --------------
 
 The developer is expected to write a makefile fragment in each
 --------------
 
 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.
 
 
 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 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.
 
 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.
 
 (for @..@-substitutions) and included by one autogenerated toplevel
 makefile.
 


@@ -50,16 +50,23 @@ Each subdirectory is also provided with an autogenerated `Makefile'
 which exists purely to capture ordinary make invocations and arrange
 for something suitable to happen.
 
 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.
 
 can simply refer to files in other subdirectories directly.
 

-Per-directory targets, "recursion"
-----------------------------------
+Invocation, "recursive" per-directory targets
+---------------------------------------------
+
+Arrangements are made so that when you run `make foo' in a
+subdirectory, it is like running the whole toplevel makefile, from the
+toplevel, as `make subdir/foo'.  If `subdir/foo' is a file that might
+be built, that builds it.
+
+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
 
 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'
 make variable called src_TARGETS.)
 
 The `all' target in a parent directory is taken to imply the `all'


@@ -72,7 +79,61 @@ In a parallel build, the rules for all these various subdirectory
 targets may be in run in parallel: there is only one `make'
 invocation at a time.
 
 targets may be in run in parallel: there is only one `make'
 invocation at a time.
 

-There may also be other 
+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.  (&TARGETS is magic.)
+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.sd.mk (see below).
+
+Perdir.sd.mk, inclusion
+-----------------------
+
+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.sd.mk
+  &:include subdirmk/clean.sd.mk
+(for example in Perdir.sd.mk).
+
+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
+------------------
+
+If want to set global variables, such as CC, that should only be done
+once.  The usual approach is to include 
+
+
+
+  subdirmk/cdeps.mk.in
+  subdirmk/cdeps.mk.in
+