INSTALL - compiling and installing GNU LilyPond
***********************************************

Table of Contents
*****************

INSTALL - compiling and installing GNU LilyPond
  Precompiled binaries
    Downloading
  Compiling from source
    Downloading source code
    Requirements
      Compilation
      Running requirements
      Requirements for building documentation
    Building LilyPond
      Compiling
      Compiling for multiple platforms
      Compiling outside the source tree
      Useful `make' variables
    Building documentation
      Commands for building documentation
      Building documentation without compiling LilyPond
    Testing LilyPond
    Problems
      Bison 1.875
      Solaris
      FreeBSD
      International fonts


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-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 *note Setup for MacOS X:
(lilypond-program)Setup for MacOS X.

Compiling from source
=====================

Downloading source code
-----------------------

Download source

   * tarballs from `http://lilypond.org/download/' by HTTP.

   * tarballs from `http://download.linuxaudio.org/lilypond/' by HTTP.

   * GIT from git.sv.gnu.org
     (http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary)

          git clone git://git.sv.gnu.org/lilypond.git

     The repository does not contain generated files.  To create
     `configure', run
          ./autogen.sh

   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.

   * FontForge (http://fontforge.sf.net/) 20060125 or newer.

   * MetaFont (http://metafont.tutorial.free.fr/) (mf-nowin, mf, mfw or
     mfont binaries) and MetaPost
     (http://cm.bell-labs.com/who/hobby/MetaPost.html) (mpost binary),
     usually packaged with a LaTeX distribution like tetex or texlive.

   * t1utils (http://www.lcdf.org/~eddietwo/type/#t1utils) (version
     1.33 or newer recommended).

   * New Century Schoolbook fonts, as PFB files.  These are shipped with
     X11 and Ghostscript, and are named `c059033l.pfb' `c059036l.pfb',
     `c059013l.pfb' and `c059016l.pfb'.

   * GUILE (http://www.gnu.org/software/guile/guile.html) (version
     1.8.2 or newer).  If you are installing binary packages, you may
     need to install guile-devel or guile-dev or libguile-dev too.

   * Texinfo (ftp://ftp.gnu.org/gnu/texinfo/) (version 4.11 or newer).

   * The GNU c++ compiler (http://gcc.gnu.org/) (version 3.4 or newer.
     4.x is strongly recommended).

   * Python (http://www.python.org) (version 2.4 or newer)

   * GNU Make (ftp://ftp.gnu.org/gnu/make/) (version 3.78 or newer).

   * gettext (http://www.gnu.org/software/gettext/gettext.html)
     (version 0.17 or newer).

   * Flex (http://www.gnu.org/software/flex/).

   * Perl (http://www.perl.org/).

   * GNU Bison (http://www.gnu.org/software/flex/).

   * All packages required for running, including development packages
     with header files and libraries.


Running requirements
....................

Running LilyPond requires proper installation of the following software

   * Freetype (http://www.freetype.org/) (version 2.1.10 or newer).

   * FontConfig (http://fontconfig.org/) (version 2.2 or newer).

   * Pango (http://www.pango.org/) (version 1.12 or newer).

   * GUILE (http://www.gnu.org/software/guile/guile.html) (version
     1.8.2 or newer), or patch 1.8.1 with
     `http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch'.

   * Python (http://www.python.org) (version 2.4 or newer).

   * Ghostscript (http://www.ghostscript.com) (version 8.15 or newer.
     8.60 recommended)

   * Dejaview.  (This is normally installed by default)

   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:

   * The netpbm utilities (http://netpbm.sourceforge.net/)

   * ImageMagick

   * International fonts (see input/regression/utf-8.ly for hints about
     which font packages are necessary for your platform)

   * Ghostscript 8.60 or newer, or 8.50 with the patch from
     `http://bugs.ghostscript.com/show_bug.cgi?id=688154' and the patch
     from `http://bugs.ghostscript.com/show_bug.cgi?id=688017'.

   * Texi2HTML (http://www.nongnu.org/texi2html/) 1.79 or newer is
     strongly recommended to build documentation in HTML; support for
     building HTML documentation using `makeinfo' from GNU Texinfo is
     deprecated.

   * rsync

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.

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 "$@"

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

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
(http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
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

