11.5 Notes on builds with GUB

Building GUB

GUB - the Grand Unified Builder - is used to build the release
versions of LilyPond. For background information, see
Grand Unified Builder (GUB). The simplest way to set up a
GUB build environment is to use a virtual machine with LilyDev
(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
almost impossible to restart. If at all possible, leave the build
to continue uninterrupted.

Download GUB and start the set up:

git clone git://github.com/gperciva/gub.git
cd gub
make bootstrap

This will take a very long time, even on a very fast computer.
You will need to be patient. It’s also liable to fail - it
downloads a number of tools, and some will have moved and others
won’t respond to the network. For example, the perl archive.
If this happens, download it from
http://www.cpan.org/src/5.0/perl-5.10.0.tar.gz, saving the
archive to ‘gub/downloads/perl/’. Continue the set up with:

make bootstrap

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 (you will need to
replace 2.15.33-1 with the latest build):

Output files

GUB builds the files it needs into the directory
gub/target/. As a general rule, these don’t need to be
touched unless there is a problem building GUB (see below).
The files to be uploaded are in gub/uploads/. Once the
build has completed successfully, there should be 8
installation files and 3 archives, totalling about 600MB.
There are also 4 directories:

gub/signatures
gub/localdoc
gub/webdoc
gub/webtest

signatures contains files that are used to track whether
some of the archives have already been built. Don’t touch
these.

localdoc probably contains local copies of the
documentation.

webdoc contains the documentation to be uploaded.

webtest contains the regtest comparison, which should
be checked before upload, and is also uploaded for subsequent
checking.

The total upload is about 700 MB in total, and on an ADSL
connection will take about 4 hours to upload.

Subsequent builds

In principle, building the next release of LilyPond requires
no action other then following the instructions in
Minor release checklist. Because much of the
infrastructure has already been built, it will take much less
time - about an hour on a fast computer.

Continuing to build LilyPond without any other
archiving/deletion of previous builds is likely to be successful,
but will take up a fair amount of disk space (around 2GB per
build) which may be a problem with a Virtual Machine. It’s
therefore recommended to move (not copy) gub/uploads to
another machine/disk after each build, if space is at a premium.

However, if a significant change has been made to the LilyPond
source (e.g. added source files) the build may fail if tried on
top of a previous build. If this happens, be sure to
move/delete gub/uploads and all mentions of LilyPond
in gub/target. The latter can be achieved with this
command:

rm -rf target/*/*/*lilypond*

Be very careful with this command. Typing it wrongly
could wipe your disk completely.

Updating the web site

The make lilypond-upload command updates the documentation
on the LilyPond web site. However, it does not update
any part of the site that is not part of the documentation - for
example, the front page (index.html). The website is
updated by 2 cron jobs running on the web server. One of these
pulls git master to the web server, and the other makes the
website with the standard make website command. They run
hourly, 30 minutes apart. So - to update the front page of the
website, it’s necessary to update VERSION and
news-front.itexi in master and then wait for the cron
jobs to run. (N.B. - this is done by pushing the changes to
staging and letting patchy do its checks before it pushes to
master).