From: Ian Jackson Date: Wed, 13 Nov 2019 14:48:15 +0000 (+0000) Subject: wip docs X-Git-Tag: subdirmk/0.1~78 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ian/git?p=subdirmk.git;a=commitdiff_plain;h=414a69f29fd9bf0d573388daae36b17aa2b093a2;hp=f319c240efe81120440881b0fc53adc006eec535 wip docs --- diff --git a/subdirmk/README b/subdirmk/README index 5da0c3d..8a9f837 100644 --- a/subdirmk/README +++ b/subdirmk/README @@ -1,3 +1,48 @@ +subdirmk - assistance for non-recursive use of make +=================================================== + +Introduction +------------ + +Peter Miller's 1997 essay _Recursive Make Considered Harmful_ +persuasively argues that it is better to arrannge to have a single +make invocation with the project's complete dependency tree, rather +than the currently conventional `$(MAKE) -C subdirectory' approach. + +However, actually writing a project's build system in a non-recursive +style is not very ergonomic. The main difficulties are: + - constantly having to write out long file and directory names + - the lack of a per-directory make variable namespace means + long make variables (or namespace clashes) + - it is difficult to arrange that one can cd to a subdirectory + and say `make all' and have something reasonable happen + (to wit, build an appropriate subset) + +`subdirmk' is an attempt to solve these problems (and it also slightly +alleviates some of the boilerplate needed to support out-of-tree +builds well). + +Basic approach +-------------- + +The developer is expected to write a makefile fragment in each +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 + + + + + + https://web.archive.org/web/20150330111905/http://miller.emu.id.au/pmiller/books/rmch/ + + + + &CAPS => subdir_CAPS or TOP_CAPS &lc => subdir/lc or lc