1 subdirmk - assistance for non-recursive use of make
2 ===================================================
7 Peter Miller's 1997 essay _Recursive Make Considered Harmful_
8 persuasively argues that it is better to arrannge to have a single
9 make invocation with the project's complete dependency tree, rather
10 than the currently conventional `$(MAKE) -C subdirectory' approach.
12 However, actually writing a project's build system in a non-recursive
13 style is not very ergonomic. The main difficulties are:
14 - constantly having to write out long file and directory names
15 - the lack of a per-directory make variable namespace means
16 long make variables (or namespace clashes)
17 - it is difficult to arrange that one can cd to a subdirectory
18 and say `make all' and have something reasonable happen
19 (to wit, build an appropriate subset)
21 `subdirmk' is an attempt to solve these problems (and it also slightly
22 alleviates some of the boilerplate needed to support out-of-tree
28 The developer is expected to write a makefile fragment in each
29 relevant subdirectory called `Subdir.mk.in'.
31 These fragments may contain ordinary make language.
33 However, the sigil & is treated specially. By and large, it refers to
34 `the current directory'. Variable names and filenames may be prefixed
35 by &_ and &/. Lists of
41 https://web.archive.org/web/20150330111905/http://miller.emu.id.au/pmiller/books/rmch/
46 &CAPS => subdir_CAPS or TOP_CAPS
47 &lc => subdir/lc or lc
50 &/ => subdir/ or nothing
53 &^ => $(top_srcdir)/subdir or $(top_srcdir)
54 &~ => $(abs_top_srcdir)/subdir or $(abs_top_srcdir)
59 & thing thing... & => each thing prefixed by &/ &^/ &~/ resp
60 & ^ thing thing... & each thing is any non-ws
61 & ~ thing thing... & & may be omitted before EOL or before \EOL
62 other &'s not recognised
64 start of line (maybe after ws):
65 &:<directive> <args>....
66 args are processed for & first
67 &:include filename filename should usually be foo.mk.in
70 CAPS is [A-Z][0-9_A-Z]*(?!\w)
71 lc is [a-z][-+,0-9_a-z]*(?!\w)
73 &!<spaces or tabs> disables & *until* EOL (and disappears)
75 &!STUFF<lwsp> STUFF is recognised instead of &
76 the terminating lwsp is discarded too
80 STUFF!& now & is recognised instead (ie back to normal)
84 &!@@@ @@@ is recognised instead of &
87 &TARGETS[_things] is handled specially
88 must be spelled precisely this way
89 if no _things, means _all
91 Also, `all' is weird in that it is present even if not specified