wip docs, before rename .mk.in

[subdirmk.git] / subdirmk / README

diff --git a/subdirmk/README b/subdirmk/README
index 16a33e373d937567550c611ae4184cb662b90710..bebbf81709c844aa20d9198d84ac58dcdd02d796 100644 (file)
--- a/subdirmk/README
+++ b/subdirmk/README
@@ -53,8 +53,15 @@ for something suitable to happen.
 Where there are dependencies between subdirectories, each Subdir.mk.in
 can simply refer to files in other subdirectories directly.
 
 Where there are dependencies between subdirectories, each Subdir.mk.in
 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
 
 Each subdirectory has its own `all' target.  For example a
 subdirectory `src' has a target `src/all'.  The rules for these are


@@ -72,7 +79,42 @@ 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.mk.in (see below).
+
+Perdir.mk.in, 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
+&-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
+
+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.
+
+Global definitions
+------------------
+
+If want to set global variables, such as CC
+
+
+
+  subdirmk/cdeps.mk.in
+  subdirmk/cdeps.mk.in
+