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 * Tips for working on the build system::
  14 * Doc build::
  15 * Website build::
  16 @end menu
  17
  18
  19 @node Build system overview
  20 @section Build system overview
  21
  22 Build system is currently GNU make, with an extra "stepmake" layer
  23 on top.  Look at files in @file{make/} and @file{stepmake/} and
  24 all @file{GNUmakefile}s.
  25
  26 There is wide-spread dissatisfaction with this system, and we are
  27 considering changing.  This would be a huge undertaking (estimated
  28 200+ hours).  This change will probably involve not using GNU make
  29 any more -- but a discussion about the precise build system will
  30 have to wait.  Before we reach that point, we need to figure out
  31 (at least approximately) what the current build system does.
  32
  33 Fundamentally, a build system does two things:
  34
  35 @enumerate
  36 @item
  37 Constructs command-line commands, for example:
  38
  39 @example
  40 lilypond-book \
  41   --tons --of --options \
  42   pitches.itely
  43 texi2pdf \
  44   --more --imperial --and --metric --tons --of --options \
  45   pitches.texi
  46 @end example
  47
  48 @item
  49 If there was a previous build, it decides which parts of the
  50 system need to be rebuilt.
  51
  52 @end enumerate
  53
  54 When I try to do anything in the build system, it helps to remind
  55 myself of this.  The "end result" is just a series of command-line
  56 commands.  All the black magick is just an attempt to construct
  57 those commands.
  58
  59 @node Tips for working on the build system
  60 @section Tips for working on the build system
  61
  62 @itemize
  63 @item
  64 Add:
  65
  66 @example
  67 echo "aaa"
  68
  69 echo "bbb"
  70 @end example
  71
  72 to the build system files in various places.  This will let you
  73 track where the program is, in various points of the build.
  74
  75 @item
  76 First task: understand how @code{make website} works,
  77 @emph{without} the translations.  Looking at the english-only
  78 website is the best introduction to the build system... it only
  79 covers about 5% of the whole thing, but even that will likely take
  80 10 hours or more.
  81
  82 @end itemize
  83
  84
  85
  86 @node Doc build
  87 @section Doc build
  88
  89 @menu
  90 * Building a bibliography::
  91 @end menu
  92
  93 @node Building a bibliography
  94 @subsection Building a bibliography
  95
  96
  97
  98 @node Website build
  99 @section Website build
 100
 101 Start here: @file{make/website.make}
 102
 103 Website build includes @ref{Building a bibliography}.
 104
 105
 106
 107