Documentation/contributor/build-notes.itexi

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2
   3
   4 @node Build system notes
   5 @chapter Build system notes
   6
   7 @warning{This chapter is in high flux, and is being run in a
   8 @qq{wiki-like} fashion.  Do not trust anything you read in this
   9 chapter.}
  10
  11 @menu
  12 * Build system overview::
  13 * Doc build::
  14 * Website build::
  15 @end menu
  16
  17
  18 @node Build system overview
  19 @section Build system overview
  20
  21 Build system is currently GNU make, with an extra "stepmake" layer
  22 on top.  Look at files in @file{make/} and @file{stepmake/} and
  23 all @file{GNUmakefile}s.
  24
  25 There is wide-spread dissatisfaction with this system, and we are
  26 considering changing.  This would be a huge undertaking (estimated
  27 200+ hours).  This change will probably involve not using GNU make
  28 any more -- but a discussion about the precise build system will
  29 have to wait.  Before we reach that point, we need to figure out
  30 (at least approximately) what the current build system does.
  31
  32 Fundamentally, a build system does two things:
  33
  34 @enumerate
  35 @item
  36 Constructs command-line commands, for example:
  37
  38 @example
  39 lilypond-book \
  40   --tons --of --options \
  41   pitches.itely
  42 texi2pdf \
  43   --more --imperial --and --metric --tons --of --options \
  44   pitches.texi
  45 @end example
  46
  47 @item
  48 If there was a previous build, it decides which parts of the
  49 system need to be rebuilt.
  50
  51 @end enumerate
  52
  53 When I try to do anything in the build system, it helps to remind
  54 myself of this.  The "end result" is just a series of command-line
  55 commands.  All the black magick is just an attempt to construct
  56 those commands.
  57
  58
  59 @node Doc build
  60 @section Doc build
  61
  62 @menu
  63 * Building a bibliography::
  64 @end menu
  65
  66 @node Building a bibliography
  67 @subsection Building a bibliography
  68
  69
  70
  71 @node Website build
  72 @section Website build
  73
  74 Start here: @file{make/website.make}
  75
  76 Website build includes @ref{Building a bibliography}.
  77
  78
  79
  80