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.1.3 Font problems
  1.2 Requirements
    1.2.1 Compilation
    1.2.2 Running requirements
    1.2.3 Building documentation
  1.3 Building LilyPond
    1.3.1 Configuring for multiple platforms
  1.4 Emacs mode
  1.5 Vim mode
  1.6 Problems
    1.6.1 Bison 1.875
    1.6.2 Linking to kpathsea
    Gcc-3.0.4
    Flex-2.5.4a and gcc-3.x
    OpenBSD
    NetBSD
    Solaris


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

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

Even numbered minor versions are `stable' (2.2, 2.4 etc), while odd
version are development releases (2.3, 2.5, etc).  Building LilyPond is
an involved process.  If possible, from download a precompiled binary
(http://lilypond.org/download) for your platform.

1.1.1 Source code
-----------------

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

        * `ftp://sca.uwaterloo.ca/pub/' by FTP (Canadian mirror).

   * CVS from savannah.gnu.org
     (http://savannah.gnu.org/cvs/?group=lilypond)
               CVS_RSH=ssh cvs -d:ext:anoncvs@savannah.gnu.org:/cvsroot/lilypond co lilypond
          The CVS 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/download' for up to date information on
binary packages for your platform.

1.1.3 Font problems
-------------------

If you are upgrading from a previous version of LilyPond, be sure to
remove all old font files.  These include `.pk' and `.tfm' files that
may be located in `/var/lib/texmf', `/var/spool/texmf',
`/var/tmp/texmf' or `PREFIX/share/lilypond/fonts/'.  A script
automating this has been included, see `buildscripts/out/clean-fonts'.

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/) 20041211 or newer.

   * mftrace (http://www.xs4all.nl/~hanwen/mftrace/) (1.1.0 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.6.5 or newer).  If you are installing binary packages, you may
     need to install guile-devel or guile-dev or libguile-dev too.

   * Flex (http://www.gnu.org/software/flex/) (version 2.5.4a or newer).

     WARNING: plain Flex 2.5.4(a) generates invalid C++ code.  GCC 3.x
     chokes on this.  If you wish to use GCC 3.x, make sure that your
     distribution supports g++ 3.x and flex.  For workarounds, see
     lexer-gcc-3.1.sh in the source directory.

   * TeX.

     TeX is used as an optional output backend.

     Also, TeX's libkpathsea is used to find the fonts (`.mf', `.afm',
     `.tfm').  Make sure you have tetex 1.0 or newer (1.0.6 is known to
     work).  If you are installing binary packages, you may need to
     install tetex-devel, tetex-dev or libkpathsea-dev too.

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

   *  The GNU c++ compiler (http://gcc.gnu.org/) (version 3.1 or
     newer).  EGCS and 2.x are known to cause crashes.

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

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

   * gettext (http://www.gnu.org/software/gettext/gettext.html).

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

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

   * GUILE (http://www.gnu.org/software/guile/guile.html) (version
     1.6.5 or newer).

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

   * TeX.

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

   You have to help TeX and MetaFont find LilyPond support files.
After compiling, scripts to do this can be found in
`buildscripts/out/lilypond-profile' and
`buildscripts/out/lilypond-login'.

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

   * ec-fonts-mftraced (http://lilypond.org/download/fonts)

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

   * ImageMagick

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

          make out=www web-install

1.3 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
          sh buildscripts/clean-fonts.sh

   The most time-consuming part of compiling LilyPond is tracing the
Type1 fonts. You can shortcut this operation by issuing one of the
following commands

          make -C mf get-pfa                # requires rpm2cpio
          make -C mf get-debian-pfa         # may not be up to date

   If you are doing an upgrade, you should remove all `feta' `.pk' and
`.tfm' files.  A script has been provided to do the work for you, see
`buildscripts/out/clean-fonts'.

   If you are not root, you should choose a `--prefix' argument that
points into your home directory, e.g.

          ./configure --prefix=$HOME/usr

   In this case, you have to insert the contents of
`buildscripts/out/lilypond-login' or
`buildscripts/out/lilypond-profile' into your start up scripts by hand.

1.3.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.4 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.5 Vim mode
============

A Vim mode for entering music and running LilyPond is contained in the
source archive in `$VIM' directory.  For version 6.2 and newer,
Vim-mode works directly after installing LilyPond.  Otherwise, complete
the following two steps.

   For earlier versions (and if `$VIM' environment variable does not
fall-back to `/usr/local/share/vim', see `:version' in vim), the
LilyPond file type is detected if your 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
If Vim has been (pre-)installed to `/usr/...' (or any other place)
instead of `/usr/local/...', then `/usr/local/share/vim' may not be
specified in your `$VIMRUNTIME' environment variable and you have to
include this path explicitly by appending the following line to your
`~/.vimrc'

          set runtimepath+=/usr/local/share/vim/

1.6 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.6.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, either
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

1.6.2 Linking to kpathsea
-------------------------

If kpathsea and the corresponding header files are installed in some
directory where GCC does not search by default, for example in
`/usr/local/lib/' and `/usr/local/include/' respectively, you have to
explicitly tell configure where to find it.  To do this

   * `rm config.cache'

   * `export LDFLAGS=-L/usr/share/texmf/lib'

   * `export CPPFLAGS=-I/usr/share/texmf/include'

   * `./configure'
   Once configure has found them, the paths are stored in `config.make'
and will be used even if you don't have the environment variables set
during make.

Gcc-3.0.4
---------

Gcc 3.0.4 is flaky; upgrade GCC.

Flex-2.5.4a and gcc-3.x
-----------------------

Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code.  To compile
LilyPond with gcc-3.1.1 or higher you may do

          CONF=gcc-3.1 ./lexer-gcc-3.1.sh
          CPPFLAGS=-I$(pwd)/lily/out-gcc-3.1 CC=gcc-3.1 CXX=g++-3.1 \
          ./configure --enable-config=gcc-3.1
          CONF=gcc-3.1 ./lexer-gcc-3.1.sh
          make conf=gcc-3.1

OpenBSD
-------

   * Refer to the section "Linking to kpathsea": GCC on OpenBSD doesn't
     set include paths for kpathsea.

NetBSD
------

   * The flex precompiled in NetBSD-1.4.2 is broken.  Upgrade to
     flex-2.5.4a.

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


