From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Wed, 13 Nov 2019 15:05:27 +0000 (+0000)
Subject: wip docs
X-Git-Tag: subdirmk/0.1~75
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?p=subdirmk.git;a=commitdiff_plain;h=37ddf3c292b5dbf0ea56af4185d5a6faefac738d;hp=8617920961da7426d98937e5a9fa055284431f06

wip docs
---

diff --git a/subdirmk/README b/subdirmk/README
index 8a9f837..16a33e3 100644
--- a/subdirmk/README
+++ b/subdirmk/README
@@ -31,8 +31,55 @@ relevant subdirectory called `Subdir.mk.in'.
 These fragments may contain ordinary make language.
 
 However, the sigil & is treated specially.  By and large, it refers to
-`the current directory'.  Variable names and filenames may be prefixed
-by &_ and &/.  Lists of 
+`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
+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
+(for @..@-substitutions) and included by one autogenerated toplevel
+makefile.
+
+So all of the input is combined and passed to one make invocation.  (A
+corollary is that there is no enforcement of the namespacing:
+discipline is required to prefix relevant variable names with &, etc.
+
+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
+can simply refer to files in other subdirectories directly.
+
+Per-directory targets, "recursion"
+----------------------------------
+
+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
+make variable called src_TARGETS.)
+
+The `all' target in a parent directory is taken to imply the `all'
+targets in all of its subdirectories, recursively.  And in the
+autogenerated stub Makefiles, `all' is the default target.  So if you
+just type `make' in the toplevel, you are asking for `&all'
+(<subdir>/all) for every directory in the project.
+
+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.
+
+There may also be other 
+
+
+
+
+
+
+  (None of this prevents