1 @c -*- coding: utf-8; mode: texinfo; -*-
4 @node Build system notes
5 @chapter Build system notes
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
12 * Build system overview::
13 * Tips for working on the build system::
19 @node Build system overview
20 @section Build system overview
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.
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.
33 Fundamentally, a build system does two things:
37 Constructs command-line commands, for example:
41 --tons --of --options \
44 --more --imperial --and --metric --tons --of --options \
49 If there was a previous build, it decides which parts of the
50 system need to be rebuilt.
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
59 @node Tips for working on the build system
60 @section Tips for working on the build system
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.
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
90 * Building a bibliography::
93 @node Building a bibliography
94 @subsection Building a bibliography
96 Bibliography files contain a list of citations, like this:
100 author = @{Vinci, Albert C.@},
101 title = @{Fundamentals of Traditional Music Notation@},
102 publisher = @{Kent State University Press@},
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.
116 A typical line of the makefile to translate a single bibliography
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
130 $(outdir)/colorado.itexi:
133 We're making the file @file{colorado.itexi} and so this is the
137 BSTINPUTS=$(src-dir)/essay $(buildscript-dir)/bib2texi \
140 It's in the @file{essay} directory and we want to run the
141 bib2texi.py script against it.
144 -s $(top-src-dir)/Documentation/lily-bib \
147 The style template is @file{lily-bib.bst} and is found in the
148 @file{Documentation} directory.
151 -o $(outdir)/colorado.itexi \
154 The output file in @file{colorado.itexi}.
157 $(src-dir)/essay/colorado.bib
160 The input file is @file{colorado.bib} in the @file{essay}
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:
171 open (tmpfile + '.aux', 'w').write (r'''
174 \bibstyle@{%(style)s@}
175 \bibdata@{%(files)s@}''' % vars ())
178 The key items are the style file (now always lily-bib for us) and
181 The style file is written in its own specialised language,
182 described to some extent at
185 @uref{http://amath.colorado.edu/documentation/LaTeX/reference/faq/bibtex.pdf}
188 The file @file{lily-bib.bst} also has fairly extensive commenting.
191 @section Website build
193 Start here: @file{make/website.make}
195 Website build includes @ref{Building a bibliography}.