subdirmk/README

   1 subdirmk - assistance for non-recursive use of make
   2 ===================================================
   3
   4 Introduction
   5 ------------
   6
   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.
  11
  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)
  20
  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
  23 builds well).
  24
  25 Basic approach
  26 --------------
  27
  28 The developer is expected to write a makefile fragment in each
  29 relevant subdirectory called `Subdir.mk.in'.
  30
  31 These fragments may contain ordinary make language.
  32
  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
  36
  37
  38
  39
  40
  41   https://web.archive.org/web/20150330111905/http://miller.emu.id.au/pmiller/books/rmch/
  42
  43
  44
  45
  46 &CAPS           =>      subdir_CAPS                     or TOP_CAPS
  47 &lc             =>      subdir/lc                       or lc
  48
  49 &_              =>      subdir_                         or TOP_
  50 &/              =>      subdir/                         or nothing
  51 &=_             =>      subdir                          or TOP
  52 &=/             =>      subdir                          or .
  53 &^              =>      $(top_srcdir)/subdir            or $(top_srcdir)
  54 &~              =>      $(abs_top_srcdir)/subdir        or $(abs_top_srcdir)
  55
  56 &&              =>      &&
  57 \&              =>      &
  58
  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
  63
  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
  68 &:-include filename
  69
  70 CAPS is [A-Z][0-9_A-Z]*(?!\w)
  71 lc is [a-z][-+,0-9_a-z]*(?!\w)
  72
  73 &!<spaces or tabs>      disables & *until* EOL (and disappears)
  74
  75 &!STUFF<lwsp>           STUFF is recognised instead of &
  76                         the terminating lwsp is discarded too
  77                         may also occur at eol
  78
  79 eg notably
  80  STUFF!&        now & is recognised instead (ie back to normal)
  81  STUFFSTUFF     STUFF
  82
  83 eg
  84  &!@@@          @@@ is recognised instead of &
  85  @@@!&          go back to &
  86
  87 &TARGETS[_things]               is handled specially
  88                                 must be spelled precisely this way
  89                                 if no _things, means _all
  90
  91 Also, `all' is weird in that it is present even if not specified