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):

http://lilypond.org/downloads/binaries/test-output/lilypond-2.15.33-1.test-output.tar.bz2

Copy the tarball into ‘regtests/’, and tell the build system that you have done this:

touch regtests/ignore

Now start the GUB build:

make lilypond

That’s it. This will build LilyPond from current master. To build the current unstable release, run:

make LILYPOND_BRANCH=release/unstable lilypond

The first time you do this, it will take a very long time.

Assuming the build has gone well, it can be uploaded using:

make lilypond-upload
  LILYPOND_BRANCH=release/unstable
  LILYPOND_REPO_URL=git://git.sv.gnu.org/lilypond.git

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-headlines.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).

<< Back to Documentation Index

LilyPond — Contributor’s Guide v2.21.0 (development-branch).