CG: begin "build system" chapter.

diff --git a/Documentation/contributor.texi b/Documentation/contributor.texi
index 579000dfc3f4e43b77dcb775764cea95156f7ae8..26b3a26fbbf00ef0416c2bde966bfcfe253ad4f1 100644 (file)
--- a/Documentation/contributor.texi
+++ b/Documentation/contributor.texi
@@ -60,6 +60,7 @@ Copyright @copyright{} 2007--2011 by the authors.
 * Regression tests::
 * Programming work::
 * Release work::
+* Build system notes::
 * Administrative policies::
 
 Appendices
@@ -85,6 +86,7 @@ Appendices
 @include contributor/regressions.itexi
 @include contributor/programming-work.itexi
 @include contributor/release-work.itexi
+@include contributor/build-notes.itexi
 @include contributor/administration.itexi
 
 @include fdl.itexi

diff --git a/Documentation/contributor/build-notes.itexi b/Documentation/contributor/build-notes.itexi
new file mode 100644 (file)
index 0000000..1cd849b
--- /dev/null
+++ b/Documentation/contributor/build-notes.itexi
@@ -0,0 +1,80 @@
+@c -*- coding: utf-8; mode: texinfo; -*-
+
+
+@node Build system notes
+@chapter Build system notes
+
+@warning{This chapter is in high flux, and is being run in a
+@qq{wiki-like} fashion.  Do not trust anything you read in this
+chapter.}
+
+@menu
+* Build system overview::
+* Doc build::
+* Website build::
+@end menu
+
+
+@node Build system overview
+@section Build system overview
+
+Build system is currently GNU make, with an extra "stepmake" layer
+on top.  Look at files in @file{make/} and @file{stepmake/} and
+all @file{GNUmakefile}s.
+
+There is wide-spread dissatisfaction with this system, and we are
+considering changing.  This would be a huge undertaking (estimated
+200+ hours).  This change will probably involve not using GNU make
+any more -- but a discussion about the precise build system will
+have to wait.  Before we reach that point, we need to figure out
+(at least approximately) what the current build system does.
+
+Fundamentally, a build system does two things:
+
+@enumerate
+@item
+Constructs command-line commands, for example:
+
+@example
+lilypond-book \
+  --tons --of --options \
+  pitches.itely
+texi2pdf \
+  --more --imperial --and --metric --tons --of --options \
+  pitches.texi
+@end example
+
+@item
+If there was a previous build, it decides which parts of the
+system need to be rebuilt.
+
+@end enumerate
+
+When I try to do anything in the build system, it helps to remind
+myself of this.  The "end result" is just a series of command-line
+commands.  All the black magick is just an attempt to construct
+those commands.
+
+
+@node Doc build
+@section Doc build
+
+@menu
+* Building a bibliography::
+@end menu
+
+@node Building a bibliography
+@subsection Building a bibliography
+
+
+
+@node Website build
+@section Website build
+
+Start here: @file{make/website.make}
+
+Website build includes @ref{Building a bibliography}.
+
+
+
+