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 Bibliography files contain a list of citations, like this:
  97
  98 @example
  99 @@Book@{vinci,
 100   author = @{Vinci, Albert C.@},
 101   title = @{Fundamentals of Traditional Music Notation@},
 102   publisher = @{Kent State University Press@},
 103   year = @{1989@}
 104 @}
 105 @end example
 106
 107 There are a variety of types of citation (e.g. Book (as above),
 108 article, publication).  Each cited publication has a list of
 109 entries that can be used to identify the publication.
 110 Bibliograpies are normally stored as files with a .bib
 111 extension.  One part of the doc-build process is transforming the
 112 bibliography information into @code{texinfo} files.  The commands
 113 to do this are in the @file{GNUmakefile} in the
 114 @file{Documentation} directory.
 115
 116 A typical line of the makefile to translate a single bibliography
 117 is:
 118
 119 @example
 120 $(outdir)/colorado.itexi:
 121         BSTINPUTS=$(src-dir)/essay $(buildscript-dir)/bib2texi \
 122                 -s $(top-src-dir)/Documentation/lily-bib \
 123                 -o $(outdir)/colorado.itexi \
 124                 $(src-dir)/essay/colorado.bib
 125 @end example
 126
 127 Line by line:
 128
 129 @example
 130 $(outdir)/colorado.itexi:
 131 @end example
 132
 133 We're making the file @file{colorado.itexi} and so this is the
 134 make instruction.
 135
 136 @example
 137         BSTINPUTS=$(src-dir)/essay $(buildscript-dir)/bib2texi \
 138 @end example
 139
 140 It's in the @file{essay} directory and we want to run the
 141 bib2texi.py script against it.
 142
 143 @example
 144                 -s $(top-src-dir)/Documentation/lily-bib \
 145 @end example
 146
 147 The style template is @file{lily-bib.bst} and is found in the
 148 @file{Documentation} directory.
 149
 150 @example
 151                 -o $(outdir)/colorado.itexi \
 152 @end example
 153
 154 The output file in @file{colorado.itexi}.
 155
 156 @example
 157                 $(src-dir)/essay/colorado.bib
 158 @end example
 159
 160 The input file is @file{colorado.bib} in the @file{essay}
 161 directory.
 162
 163 The @code{bib2texi} Python script used to be used with a variety
 164 of options, but now is always called using the same options, as
 165 above.  Its job is to create the file containing the options for
 166 @code{bibtex} (the program that actually does the translation),
 167 run bibtex, and then clean up some temporary files.  Its main
 168 "value add" is the creation of the options file, using this code:
 169
 170 @example
 171 open (tmpfile + '.aux', 'w').write (r'''
 172 \relax
 173 \citation@{*@}
 174 \bibstyle@{%(style)s@}
 175 \bibdata@{%(files)s@}''' % vars ())
 176 @end example
 177
 178 The key items are the style file (now always lily-bib for us) and
 179 the input file.
 180
 181 The style file is written in its own specialised language,
 182 described to some extent at
 183
 184 @example
 185 @uref{http://amath.colorado.edu/documentation/LaTeX/reference/faq/bibtex.pdf}
 186 @end example
 187
 188 The file @file{lily-bib.bst} also has fairly extensive commenting.
 189
 190 @node Website build
 191 @section Website build
 192
 193 Start here: @file{make/website.make}
 194
 195 Website build includes @ref{Building a bibliography}.
 196
 197
 198
 199