CG guide to building GUB (issue 6199045)

[PhilEHolmes]

Reviewers: Graham Percival, J_lowe,

Message:
Please review

Description:
Some notes on how to set up a GUB build environment.

Please review this at http://codereview.appspot.com/6199045/

Affected files:
  M Documentation/contributor/build-notes.itexi


Index: Documentation/contributor/build-notes.itexi
diff --git a/Documentation/contributor/build-notes.itexi  
b/Documentation/contributor/build-notes.itexi
index  
a1e258cc91a369eb8b65d06c70a8e2efe411f3d6..b2c4416eacbbc75b4bb70ea54833db2622ae9927  
100644
--- a/Documentation/contributor/build-notes.itexi
+++ b/Documentation/contributor/build-notes.itexi
@@ -15,6 +15,7 @@ chapter.}
 * Doc build::
 * Website build::
 * Building an Ubuntu distro::
+* Building GUB::
 @end menu


@@ -1501,3 +1502,68 @@ Test iso by installing in VM and repeating steps  
above for
 getting source files and building lp and docs.

 @end enumerate
+
address@hidden Building GUB
address@hidden Building GUB
+
+GUB - the Grand Unified Builder - is used to build the release
+versions of LilyPond.  For background information, see
address@hidden Unified Builder (GUB)}.  The simplest way to set up a
+GUB build environment is to use a virtual machine with LilyDev
+(@ref{LilyDev}).  Follow the instructions on that page to set this
+up.  Make sure that your virtual machine has enough disk space -
+a GUB installation takes over 30 GBytes of disk space, and if you
+allocate too little, it will fail during the setting up stage and
+you will have to start again.  64 GBytes should be sufficient.
+
+While GUB is being built, any interruptions are likely to make it
+impossible to restart.  If at all possible, leave the build to
+continue uniterrupted.
+
+Download GUB and start the set up:
+
address@hidden
+git clone git://github.com/janneke/gub.git
+cd gub
+make bootstrap
address@hidden example
+
+This downloads and installs a number of packages.  You may find
+some fail during download and you will need to download them
+manually.  For example, the perl archive.  If this happens,
+download it from
address@hidden://www.cpan.org/src/5.0/perl-5.10.0.tar.gz}, saving the
+archive to @file{gub/downloads/perl/}.  Continue the set up with:
+
address@hidden
+make bootstrap
address@hidden example
+
+Once this has completed successfully, you can build the LilyPond
+release package.  However, this uses an archived version of the
+regression tests, so it is better to download this first.
+Download the test output from lilypond.org:
+
address@hidden
address@hidden://lilypond.org/download/binaries/test-output/lilypond-2.15.33-1.test-output.tar.bz2}
address@hidden smallexample
+
+Copy the tarball into @file{gub/regtests/}, and tell the build
+system that you have done this:
+
address@hidden
+touch regtests/ignore
address@hidden example
+
+Now start the GUB build:
+
address@hidden
+make lilypond
address@hidden example
+
+That's it.  This will build LilyPond from current master.  To build
+the current unstable release, run:
+
address@hidden
+make LILYPOND_BRANCH=release/unstable lilypond
address@hidden example