chiark / gitweb /
wip docs, before rename .mk.in
authorIan Jackson <ijackson@chiark.greenend.org.uk>
Wed, 13 Nov 2019 15:20:56 +0000 (15:20 +0000)
committerIan Jackson <ijackson@chiark.greenend.org.uk>
Wed, 13 Nov 2019 15:20:56 +0000 (15:20 +0000)
subdirmk/README

index 16a33e3..bebbf81 100644 (file)
@@ -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
+