INSTALL - compiling and installing GNU LilyPond

There are two sets of releases for LilyPond: stable releases, and unstable development releases. Stable versions have an even-numbered ‘minor’ version number (i.e. 2.8, 2.10, 2.12, etc). Development versions have an odd-numbered ‘minor’ version number (i.e. 2.7, 2.9, 2.11, etc).

Building LilyPond is a very involved process, so we highly recommend using the precompiled binaries.


1. Precompiled binaries


Downloading

Check out http://lilypond.org/web/install/ for up to date information on binary packages for your platform. If your operating system is not covered on that general page, please see the complete list at http://download.linuxaudio.org/lilypond/binaries/

We currently create binaries for

darwin-ppc  - MacOS X powerpc
darwin-x86  - MacOS X intel
freebsd-64  - FreeBSD 6.x, x86_64
freebsd-x86 - FreeBSD 4.x, x86
linux-64    - Any GNU/Linux distribution, x86_64
linux-ppc   - Any GNU/Linux distribution, powerpc
linux-x86   - Any GNU/Linux distribution, x86
mingw       - Windows x86

Known issues and warnings

If you have MacOS 10.3 or 10.4 and you would like to use Python scripts such as convert-ly and lilypond-book, see Setup for MacOS X.


2. Compiling from source


2.1 Downloading source code

Download source

For information on packaging, see http://lilypond.org/devel.


2.2 Requirements


Compilation

In addition to the packages needed for running LilyPond (see below), you need the following extra packages for building.

When installing a binary package FOO, you may need to install the FOO-devel, libFOO-dev or FOO-dev package too.


Running requirements

Running LilyPond requires proper installation of the following software

International fonts are required to create music with international text or lyrics.


Requirements for building documentation

You can view the documentation online at http://lilypond.org/doc/, but you can also build it locally. This process requires a successful compile of LilyPond, and some additional tools and packages:


2.3 Building LilyPond


Compiling

To install GNU LilyPond, type

gunzip -c lilypond-x.y.z | tar xf -
cd lilypond-x.y.z
./configure		# run with --help for applicable options
make
su -c 'make install'

If you are not root, you should choose a --prefix argument that points into your home directory, e.g.

./configure --prefix=$HOME/usr

Compiling for multiple platforms

If you want to build multiple versions of LilyPond with different configuration settings, you can use the --enable-config=CONF option of configure. You should use make conf=CONF to generate the output in ‘out-CONF’. For example, suppose you want to build with and without profiling, then use the following for the normal build

./configure --prefix=$HOME/usr/ --enable-checking
make
make install

and for the profiling version, specify a different configuration

./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
make conf=prof
make conf=prof install

Compiling outside the source tree

It is possible to compile LilyPond in a build tree different from the source tree, with --srcdir option of configure:

mkdir lily-build && cd lily-build
sourcedir/configure --srcdir=sourcedir


Useful make variables

If a less verbose build output if desired, the variable QUIET_BUILD may be set to 1 on make command line, or in ‘local.make’ at top of the build tree.


2.4 Building documentation

This requires a successful compile of LilyPond, or using an external LilyPond binary.


Commands for building documentation

The documentation is built by issuing

make web

After compilation, the HTML documentation tree is available in ‘out-www/offline-root/’, and can be browsed locally.

The HTML and PDF files can be installed into the standard documentation path by issuing

make web-install

This also installs Info documentation with images if the installation prefix is properly set; otherwise, instructions for manual installation of Info documentation are printed on standard output.

It is also possible to build a documentation tree in ‘out-www/online-root/’, with special processing, so it can be used on a website with content negotiation for automatic language selection; this can be achieved by issuing

make WEB_TARGETS=online web

and both ‘offline’ and ‘online’ targets can be generated by issuing

make WEB_TARGETS="offline online" web

Several targets are available to clean the documentation build and help with maintaining documentation; an overview of these targets is available with

make help

from every directory in the build tree. Most targets for documentation maintenance are available from ‘Documentation/’; for more information, see ‘Documentation/user/README.txt’ and ‘Documentation/TRANSLATION’.

The makefile variable QUIET_BUILD may be set to 1 for a less verbose build output, just like for building the programs.

Known issues and warnings

The most time consuming task for building the documentation is running LilyPond to build images of music, and there cannot be several simultaneously running lilypond-book instances, so -j make option does not significantly speed up the build process. To help speed it up, the makefile variable CPU_COUNT may be set in ‘local.make’ or on the command line to the number of .ly files that LilyPond should process simultaneously, e.g. on a bi-processor or dual core machine

make -j3 CPU_COUNT=3 web

The recommended value of CPU_COUNT is one plus the number of cores or processors, but it is advisable to set it to a smaller value if your system has not enough RAM to run that many simultaneous LilyPond instances.

If source files have changed since last documentation build, output files that need to be rebuilt are normally rebuilt, even if you do not run make web-clean first. However, building dependencies in the documentation are so complex that rebuilding of some targets may not be triggered as they should be; a workaround is to force rebuilding by touching appropriate files, e.g.

touch Documentation/user/*.itely
touch input/lsr/*.ly

Building documentation without compiling LilyPond

The documentation can be built locally without compiling LilyPond binary, if LilyPond is already installed on your system.

From a fresh Git checkout, do

./autogen.sh   # ignore any warning messages
cp GNUmakefile.in GNUmakefile
make -C python
nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web

Please note that this may break sometimes – for example, if a new feature is added with a test file in input/regression, even the latest development release of LilyPond will fail to build the docs.

You may build the manual without building all the ‘input/*’ stuff: change directory, for example to ‘Documentation/user’, issue make web, which will build documentation in a subdirectory ‘out-www’ from the source files in current directory. In this case, if you also want to browse the documentation in its post-processed form, change back to top directory and issue

make out=www WWW-post

Known issues and warnings

You may also need to create a script for pngtopnm and pnmtopng. On GNU/Linux, I use this:

export LD_LIBRARY_PATH=/usr/lib
exec /usr/bin/pngtopnm "$@"

On MacOS X, I use this:

export DYLD_LIBRARY_PATH=/sw/lib
exec /sw/bin/pngtopnm "$@"

2.5 Testing LilyPond

LilyPond comes with an extensive suite that exercises the entire program. This suite can be used to automatically check the impact of a change. This is done as follows

make test-baseline
## apply your changes, compile
make check

This will leave an HTML page ‘out/test-results/index.html’. This page shows all the important differences that your change introduced, whether in the layout, MIDI, performance or error reporting.

To rerun tests, use

make test-redo           ## redo files differing from baseline
make test-clean          ## remove all test results

and then run make check again.

For tracking memory usage as part of this test, you will need GUILE CVS; especially the following patch: http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch.

For checking the coverage of the test suite, do the following

./scripts/auxiliar/build-coverage.sh
# uncovered files, least covered first
./scripts/auxiliar/coverage.py  --summary out-cov/*.cc
# consecutive uncovered lines, longest first
./scripts/auxiliar/coverage.py  --uncovered out-cov/*.cc

2.6 Problems

For help and questions use lilypond-user@gnu.org. Send bug reports to bug-lilypond@gnu.org.

Bugs that are not fault of LilyPond are documented here.


Bison 1.875

There is a bug in bison-1.875: compilation fails with "parse error before ‘goto’" in line 4922 due to a bug in bison. To fix, please recompile bison 1.875 with the following fix

$ cd lily; make out/parser.cc
$ vi +4919 out/parser.cc
# append a semicolon to the line containing "__attribute__ ((__unused__))
# save
$ make

Solaris

Solaris7, ./configure

./configure’ needs a POSIX compliant shell. On Solaris7, ‘/bin/sh’ is not yet POSIX compliant, but ‘/bin/ksh’ or bash is. Run configure like

CONFIG_SHELL=/bin/ksh ksh -c ./configure

or

CONFIG_SHELL=/bin/bash bash -c ./configure

FreeBSD

To use system fonts, dejaview must be installed. With the default port, the fonts are installed in ‘usr/X11R6/lib/X11/fonts/dejavu’.

Open the file ‘$LILYPONDBASE/usr/etc/fonts/local.conf’ and add the following line just after the <fontconfig> line. (Adjust as necessary for your hierarchy.)

<dir>/usr/X11R6/lib/X11/fonts</dir>

International fonts

On MacOS X, all fonts are installed by default. However, finding all system fonts requires a bit of configuration; see this post on the lilypond-user mailing list.

On Linux, international fonts are installed by different means on every distribution. We cannot list the exact commands or packages that are necessary, as each distribution is different, and the exact package names within each distribution changes. Here are some hints, though:

Red Hat Fedora

    taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
         ttfonts-zh_CN fonts-ja fonts-hebrew

Debian GNU/Linux

   apt-get install emacs-intl-fonts xfonts-intl-.* \
        ttf-kochi-gothic ttf-kochi-mincho \
        xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi

Table of Contents


About This Document

This document was generated by Han-Wen Nienhuys on January 20, 2009 using texi2html 1.79.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[]
[ << ] FastBack Beginning of this chapter or previous chapter 1
[]
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  
[]
[ >> ] FastForward Next chapter 2
[]
[]
[ < ] Back Previous section in reading order 1.2.2
[]
[ Up ] Up Up section 1.2
[]
[ > ] Forward Next section in reading order 1.2.4

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


INSTALL - compiling and installing GNU LilyPond