INSTALL - compiling and installing GNU LilyPond

Table of Contents

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.

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-arm   - Any GNU/Linux distribution, arm
     linux-ppc   - Any GNU/Linux distribution, powerpc
     linux-x86   - Any GNU/Linux distribution, x86
     mingw       - Windows x86

Compiling from source

Downloading source code

Download source

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

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.

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

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 out=www web-install

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 negociation 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

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

Building documentation without compiling LilyPond

The documentation can be built locally without compiling lilypond from scratch.

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
     % change the lilypond directory as appropriate

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 unstable Lily will fail to build the docs.

You may build the manual ( Documentation/user/ ) without building all the input/* stuff.

Known issues and warnings

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

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

On OSX, I use this:

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

In order to force make to build a complete manual (this does not rebuild all examples, only things which are changed), I recommend writing a script like this:

### run from Documentation/user/
#  possibly required on OSX and/or old texinfo
# ulimit -n 4096
if [ -e out-www/lilypond.texi ]; then rm out-www/lilypond.* ; fi;
if [ -e out-www/lilypond-program.texi ]; then rm
out-www/lilypond-program.* ; fi;
if [ -e out-www/lilypond-learning.texi ]; then rm
out-www/lilypond-learning.* ; fi;
nice make LILYPOND_EXTERNAL_BINARY=~/usr/bin/lilypond web

To rebuild the complete HTML docs, run the above script from the Documentation/user/ directory, then run the final line (the nice make) from the top source dir.

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

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

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 

This page is for LilyPond-2.11.40 (development-branch).

Report errors to http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs.

Your suggestions for the documentation are welcome.