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

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

INSTALL - compiling and installing GNU LilyPond
1 Compiling and installing on Unix
  1.1 Downloading
    1.1.1 Source code
    1.1.2 Precompiled binary packages
  1.2 Requirements
    1.2.1 Compilation
    1.2.2 Running requirements
    1.2.3 Building documentation
  1.3 Testing LilyPond
  1.4 Building LilyPond
    1.4.1 Configuring for multiple platforms
  1.5 Emacs mode
  1.6 Vim mode
  1.7 Problems
    1.7.1 Bison 1.875
    MacOS X
    Solaris
  1.8 International fonts


1 Compiling and installing on Unix
**********************************

1.1 Downloading
===============

Even numbered minor versions are `stable' (2.6, 2.8, etc), while odd
version are development releases (2.7, 2.9, etc).  Building LilyPond is
an involved process.  If possible download a precompiled binary
(http://lilypond.org/install) for your platform.

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

1.1.2 Precompiled binary packages
---------------------------------

Check out `http://lilypond.org/web/install/' for up to date information
on binary packages for your platform.

1.2 Requirements
================

1.2.1 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 will 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.8 or newer).

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

   * Python (http://www.python.org) (version 2.3 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.


1.2.2 Running requirements
--------------------------

Running LilyPond requires proper installation of the following software

   * Freetype (http://www.freetype.org/) (version 2).

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

1.2.3 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

1.3 Testing LilyPond
====================

LilyPond comes with an extensive suite that excercises 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

1.4 Building LilyPond
=====================

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

1.4.1 Configuring 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

1.5 Emacs mode
==============

An Emacs mode for entering music and running LilyPond is contained in
the source archive in the `elisp' directory.  Do `make install' to
install it to ELISPDIR.  The file `lilypond-init.el' should be placed
to LOAD-PATH`/site-start.d/' or appended to your `~/.emacs' or
`~/.emacs.el'.

   As a user, you may want add your source path (e.g. `~/site-lisp/') to
your LOAD-PATH by appending the following line (as modified) to your
`~/.emacs'

          (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))

1.6 Vim mode
============

A Vim mode for entering music and running LilyPond is contained in the
source archive in `$VIM' directory.

   The LilyPond file type is detected if the file `~/.vim/filetype.vim'
has the following content

          if exists("did_load_filetypes")
            finish
          endif
          augroup filetypedetect
            au! BufNewFile,BufRead *.ly           setf lilypond
          augroup END

   Please include this path by appending the following line to your
`~/.vimrc'

          set runtimepath+=/usr/local/share/lilypond/${LILYPOND_VERSION}/vim/

where ${LILYPOND_VERISON} is your lilypond version.  If Lilypond was not
installed in `/usr/local/', then change this path accordingly.

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

1.7.1 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

MacOS X
-------

For Fink, use the following command to compile.


export GUILE=guile-1.6
export GUILE_CONFIG=guile-1.6-config
export PKG_CONFIG_PATH=/sw/lib/freetype219/lib/pkgconfig/:/sw/lib/fontconfig2/lib/pkgconfig/
./configure

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>


1.8 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:
