LilyPond Contributor's Guide: 11.5 Notes on builds with GUB

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

    https://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.

The website (which is served on `lilypond.org`) is updated by executing a manual pipeline on Gitlab. See Uploading website for more details.

So - to update the front page of the website, it’s necessary to update `VERSION` and `news-headlines.itexi` in master, run the manual pipeline, and then wait for the cron jobs to run.

#### LilyPond — Contributor’s Guide v2.22.2 (stable-branch).