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

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

INSTALL - compiling and installing GNU LilyPond
    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
      Compiling on MacOS X
      Solaris
      FreeBSD
      International fonts


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.

   Below is a full list of packages needed to build LilyPond.  However,
for most common distributions there is an easy way of installing most
all build dependencies in one go

Distribution                         Command
-------------------------------------------------------------------------- 
Debian, Ubuntu                       `sudo apt-get build-dep lilypond'
Fedora, RHEL                         `sudo yum-builddep lilypond'
openSUSE, SLED                       `sudo zypper --build-deps-only
                                     source-install lilypond'

   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/bison/).

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

   * 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

   If you encounter any problems, please see *note Problems::.

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 doc

   After compilation, the HTML documentation tree is available in
`out-www/offline-root/', and can be browsed locally.  Various portions
of the documentation can be found by looking in `out/' and `out-www'
subdirectories in other places in the source tree, but these are only
_portions_ of the docs.  Please do not complain about anything which is
broken in those places; the only complete set of documentation is in
`out-www/offline-root/' from the top of the source tree.

   The HTML, PDF and if available Info files can be installed into the
standard documentation path by issuing

     make install-doc

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

   Compilation of documentation in Info format with images can be done
separately by issuing

     make info

Separate installation of this documentation is done by issuing

     make install-info

Note that to get the images in Info documentation, `install-doc' target
creates symbolic links to HTML and PDF installed documentation tree in
`PREFIX/share/info', in order to save disk space, whereas
`install-info' copies images in `PREFIX/share/info' subdirectories.

   It is 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 doc

and both `offline' and `online' targets can be generated by issuing

     make WEB_TARGETS="offline online" doc

   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 the Contributor's Guide, section _Documentation work_.

   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 doc

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 doc-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/extend.texi
     touch Documentation/*te??
     touch Documentation/snippets/*.te??

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 scripts && make -C python
     nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc

   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
(i.e. mostly regression tests): change directory, for example to
`Documentation/', issue `make doc', 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 with fink, I use this:

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

   On MacOS X with macports, you should use this:

export DYLD_LIBRARY_PATH=/opt/local/lib
exec /opt/local/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

Compiling on MacOS X
....................

Here are special instructions for compiling under MacOS X.  These
instructions assume that dependencies are installed using MacPorts.
(http://www.macports.org/) The instructions have been tested using OS X
10.5 (Leopard).

   First, install the relevant dependencies using MacPorts.

   Next, add the following to your relevant shell initialization files.
This is `~/.profile' by default. You should create this file if it does
not exist.

     export PATH=/opt/local/bin:/opt/local/sbin:$PATH
     export DYLD_LIBRARY_PATH=/System/Library/Frameworks/ApplicationServices.framework/Versions/A/Frameworks/ImageIO.framework/Versions/A/Resources:\
     /opt/local/lib:$DYLD_LIBRARY_PATH

   Now you must edit the generated `config.make' file.  Change

     FLEXLEXER_FILE = /usr/include/FlexLexer.h

to:

     FLEXLEXER_FILE = /opt/local/include/FlexLexer.h

   At this point, you should verify that you have the appropriate fonts
installed with your ghostscript installation. Check `ls
/opt/local/share/ghostscript/fonts' for: 'c0590*' files (.pfb, .pfb and
.afm).  If you don't have them, run the following commands to grab them
from the ghostscript SVN server and install them in the appropriate
location:

     svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
     sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
     rm -rf urw-fonts-1.07pre44

   Now run the `./configure' script. To avoid complications with
automatic font detection, add

     --with-ncsb-dir=/opt/local/share/ghostscript/fonts

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 Mac OS 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

