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
      Building documentation
    Building LilyPond
      Compiling
      Compiling for multiple platforms
    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-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

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

   * 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'

   * mftrace (http://www.xs4all.nl/~hanwen/mftrace/) (1.1.19 or newer);
     you may need to install some additional packages to get mftrace to
     work.

   * 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 4.x or newer).

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

   * 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://www.freetype.org/) (version 2.2).

   * 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.50 recommended)

   * Dejaview.  (This is normally installed by default)

   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.  The documentation is built by issuing

     make web

   Building the website requires 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.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'.

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

     make out=www web-install

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



Local Variables:
coding: utf-8
End:
