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


INSTALL - compiling and installing GNU LilyPond
  Downloading
    Source code
    Precompiled binaries
    Upgrading
    Font problems.
  Requirements
    Compilation
    Running requirements
    Building documentation
  Building LilyPond
    Configuring for multiple platforms
  Emacs mode
  Vim mode
  Compiling for distributions
    Red Hat Linux
    LinuxPPC
    SuSE
    Slackware
    Mandrake
    Debian GNU/Linux
    MacOS X
    compiling on MacOS X
  Problems
    Linking to kpathsea
    Gcc-3.0.4
    Flex-2.5.4a and gcc-3.x
    Flex-2.5.4a and gcc-3.1.x
    Linux-2.4.0, Guile-1.4 -with-threads
    OpenBSD
    NetBSD
    Solaris
    AIX


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

This document describes how to build LilyPond on Unix platforms.  It is
also known to run and compile on Windows NT/95/98/ME/XP as well.  More
information on this topic can be found at the LilyPond on Windows page
(http://www.lilypond.org/cygwin/).

Downloading
===========

Even numbered versions are `stable'. The webpages for the stable version
(1.4) reside on the GNU servers (http://www.gnu.org/software/lilypond).
Big enhancements go into the latest odd numbered version (1.5), whose
webpages are on the lilypond site (http://www.lilypond.org/).

   Building LilyPond is an involved process. We advise to use binary
packages if these are available for your platform.

Source code
-----------

If you want to compile LilyPond from source, download here:
   * Download development releases from
     `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/' by FTP and
     `http://ftp.cs.uu.nl/pub/GNU/LilyPond/', by HTTP.

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

   * at `lilypond.org' `ftp://ftp.lilypond.org/pub/LilyPond/' by FTP and
     `http://www.lilypond.org/ftp/' by HTTP.

   For Red Hat Linux and SuSE Linux, `.spec' files are included in the
tarball; see instructions below.

   Of course, if your platform supports LilyPond, such as Debian
GNU/Linux, FreeBSD, OpenBSD or NetBSD, you're encouraged to use the
native build from source drill.

   The latest development version is also available through anonymous
CVS. See `http://savannah.gnu.org/cvs/?group=lilypond'.

   CVS does not contain generated files.  To create `configure', run

          ./autogen.sh

Precompiled binaries
--------------------

If you want to track bleeding edge development, try:

   * Debian GNU/Linux
     (ftp://ftp.debian.org/debian/pool/main/l/lilypond/) usually has
     the latest binaries for the most useful stable and development
     versions, while

   * Mandrake Cooker
     (http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/) also
     provides fairly recent versions.

   Binaries are made available for other popular platforms, but as we
need to compile them ourselves, they are not updated for every version
released.

   * Red Hat i386
     (http://www-ccrma.stanford.edu/planetccrma/software/soundapps.html#lilypond)

   * SuSE (ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE)

   * LinuxPPC (ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/)

   * Windows (http://www.lilypond.org/gnu-windows/)

Upgrading
---------

There are two options for upgrading sources.

   * if you have an unpacked source tree of a previous version, you may
     the patches.

     _If you upgrade by patching do remember to rerun autoconf after
     applying the patch_.

   * if you have the `.tar.gz' file of a previous release, you can use
     xdelta (ftp://ftp.xcf.berkeley.edu/pub/xdelta/).   This is much
     safer than using patches, and is the recommended way.

     The following command produces `lilypond-1.4.3.tar.gz' from
     `lilypond-1.4.2.tar.gz' identical (up to compression dates) to the
     .3 on the FTP site.
            xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz

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

Requirements
============

Compilation
-----------

You need the following packages to compile Lilypond.

   * The GNU c++ compiler (version 2.95.2 or newer).  EGCS 1.1 may
     work, but is no longer supported.  Check out the gcc site
     (ftp://ftp.gnu.org/gnu/gcc/).

     WARNING: if you choose to upgrade to GCC 3.x, enquire if your
     distribution supports g++ 3.x and flex.  At the time of writing
     (Fri Jul 5 2002), *no* distribution that we know of ships a flex
     that generates gcc-3.1.x compliant C++ code.

   * Python (version 2.1 or newer).  Check out the python website
     (http://www.python.org).

   * GUILE (version 1.6 or newer).  Check out the GUILE webpage
     (http://www.gnu.org/software/guile/guile.html).

   * GNU Make.  Check out the GNU make FTP directory
     (ftp://ftp.gnu.org/gnu/make/).

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

     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.0.patch and lexer-gcc-3.1.sh in the source directory.

   * Bison (version 1.25 or newer).  Check out the bison webpage
     (http://www.gnu.org/software/bison/)

   * TeX.

     TeX is used as an 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).  You may need to install a tetex-devel (or tetex-dev or
     libkpathsea-dev) package too.

   * Texinfo (version 4.2 or newer).  The documentation of lily is
     written in texinfo.  Check out the texinfo FTP directory
     (ftp://ftp.gnu.org/gnu/texinfo/).

   * The geometry package for LaTeX is needed to use ly2dvi.  It is
     available at the FTP directory for `geometry'
     (ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry).
     This package is normally included with the TeX distribution.

   * kpathsea, a library for searching (TeX) files.  `kpathsea' is
     usually included with your installation of TeX.  You may need to
     install a tetex-devel or tetex-dev package too. If kpathsea is not
     installed in a directory where the compiler normally looks, read
     the hints for Slackware below.

     In the very unlikely case that kpathsea is not available for your
     platform (ie, you're not running GNU/Linux, Windows, or any recent
     UNIX), you can compile LilyPond without kpathsea support.  In that
     case, you'll probably have to indicate where TeX's tfm files live.
     Invoke configure something like:

               ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols


Running requirements
--------------------

GNU LilyPond does use a lot of resources. For operation you need the
following software

   * TeX.

   * Xdvi and Ghostscript

   * GUILE 1.4, or newer.  Check out the GUILE webpage
     (http://www.gnu.org/software/guile.html)

   For running LilyPond successfully you have to help TeX and MetaFont
find various files.  The recommended way of doing so is adjusting the
environment variables in the start-up scripts of your shell. Appropriate
Csh and bourne sh scripts are left in
`buildscripts/out/lilypond-profile' and
`buildscripts/out/lilypond-login' after compilation.

   LilyPond is a big and slow program.  A fast CPU and plenty of RAM is
recommended for comfortable use.

Building documentation
----------------------

You can view the documentation online at
`http://www.lilypond.org/stable/Documentation/out-www/', but you can
also build it locally. This process requires a successful compile of
lilypond. The documentation is built by issuing

       make web-doc

   Building the website requires some additional tools:

   * The netpbm utilities, see `http://netpbm.sourceforge.net/'

   * mftrace 1.0 or newer, needed for generating PostScript Type1
     fonts. Get it from `http://www.cs.uu.nl/~hanwen/mftrace/'.  You
     will need to install some additional packages to get mftrace to
     work.

Building LilyPond
=================

to install GNU LilyPond, type:
     	gunzip -c lilypond-x.y.z | tar xf -
     	cd lilypond-x.y.z
     	./configure		# run with --help to see appropriate options
     	make
     	make install
             sh buildscripts/clean-fonts.sh

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

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

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

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 I want to build with and without
profiling.  Then I'd use the following for the normal build,

           ./configure --prefix=$HOME/usr/ --enable-checking
           make
           make install

   and for the profiling version, I specify a different configuration.


           ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
           make conf=prof
           make conf=prof install

Emacs mode
==========

An Emacs mode for entering music and running LilyPond is contained in
the source archive as `lilypond-mode.el', `lilypond-indent.el',
`lilypond-font-lock.el' and `lilypond.words'.  You should install these
files to a directory included in your LOAD-PATH. File
`lilypond-init.el' should be placed to LOAD-PATH`/site-start.d/' or
appended to your `~/.emacs' or `~/.emacs.el'. If you have installed a
precompiled LilyPond package, these files can be found in
`/usr/share/doc/lilypond-x.y.z/'.

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

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

   If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode
is automatically loaded, you not even need to modify your `~/.emacs'
file.

Vim mode
========

A Vim mode for entering music and running LilyPond is contained in the
source archive. Append the content of `vimrc' to `~/.vimrc' to get
shortcuts. Install file `lilypond.words' to `~/.vim/' to get
auto-completion. Syntax highlighting you get by installing
`lilypond.vim' to `~/.vim/syntax/' and appending the following to
`~/.vim/filetype.vim':

          " my filetype file
          if exists("did_load_filetypes")
            finish
          endif
          augroup filetypedetect
            au! BufRead,BufNewFile  *.ly          setfiletype lilypond
          augroup

Compiling for distributions
===========================

Red Hat Linux
-------------

Red Hat 7.x i386 RPMS are available from
`ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.  For running on a Red
Hat system you need these packages: guile, tetex, tetex-latex,
tetex-dvips, libstdc++, python, ghostscript.

   You can also compile them yourself.  A spec file is in
`make/out/lilypond.redhat.spec'. This file is distributed along with
the sources.  You can make the rpm by issuing

             cp lilypond-x.y.z.tar.gz /usr/src/redhat/SOURCES/
             tar xfz lilypond-x.y.z.tar.gz
     	rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
     	rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z

   For compilation on a Red Hat system you need these packages, in
addition to the those needed for running: glibc-devel, gcc-c++,
libstdc++-devel, guile-devel, flex, bison, texinfo, groff, mftrace,
netpbm-progs, autotrace, t1utils.

LinuxPPC
--------

Some LinuxPPC RPMS should available from
`ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.

   A LinuxPPC RPM can be made using the `lilypond.redhat.spec' file.

SuSE
----

Some SUSE RPMS should available from
`ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE'.

   You can also compile a RPM for SUSE yourself.  A spec file is in
`make/out/lilypond.suse.spec', see the instructions for building the
Red Hat RPM.

   You must have the following packages: guile tcsh tetex te_latex
te_kpath te_mpost libpng python gpp libgpp gettext autoconf netpbm
libnetpb gs_serv gs_lib gs_fonts guile

Slackware
---------

No precompiled packages for Slackware are available.

   Problems have been reported with Slackware 7.0; apparently, it ships
with a faulty compiler. Do not compile LilyPond with -O2 on this
platform.

   At least on Slackware 8.0, you have to manually specify the paths to
the Kpathsea library, see the section on kpathsea

Mandrake
--------

Some binaries are available at rpmfind.net. Refer to
`http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/'.

   You can also compile a RPM for Mandrake yourself.  A spec file is in
`make/out/lilypond.mandrake.spec', see the instructions for building
the Red Hat RPM.

Debian GNU/Linux
----------------

A Debian package is also available.  You may install it easily by
running `apt-get' as root:

     	apt-get install lilypond lilypond-doc

   You can also compile the .deb for Debian yourself, do:

     	apt-get -b source lilypond

   If you're real impatient, you may even do:

     	cd lilypond-x.y.z   # a previous version
             uscan               # download and build latest directly from upstream

   Debian's TeX installation is a bit short on memory, you may want to
increase it like this:
     --- texmf.cnf.orig	Sun Dec 16 23:47:07 2001
     +++ texmf.cnf	Sun Dec 16 23:46:34 2001
     @ -411,8 +411,8 @
      main_memory.context = 1500000
      main_memory.mpost = 1000000
      main_memory = 263000 % words of inimemory available; also applies to inimf&mp
     -extra_mem_top = 0    % extra high memory for chars, tokens, etc.
     -extra_mem_bot = 0    % extra low memory for boxes, glue, breakpoints, etc.
     +extra_mem_top = 1000000    % extra high memory for chars, tokens, etc.
     +extra_mem_bot = 1000000    % extra low memory for boxes, glue, breakpoints, etc.
     
      obj_tab_size.context = 300000
     
     @ -430,7 +430,7 @
      % Max number of characters in all strings, including all error messages,
      % help texts, font names, control sequences.  These values apply to TeX and MP.
      pool_size.context = 750000
     -pool_size = 125000
     +pool_size = 250000
      % Minimum pool space after TeX/MP's own strings; must be at least
      % 25000 less than pool_size, but doesn't need to be nearly that large.
      string_vacancies.context = 45000

   You could also export `extra_mem_top' and `extra_mem_bot' as
environment variables if you do not want to or cannot modify
`/etc/texmf/texmf.cnf'.

   Alternatively, visit

   * http://packages.debian.org/lilypond
     (http://packages.debian.org/lilypond)

   * http://people.debian.org/~foka/lilypond/
     (http://people.debian.org/~foka/lilypond/) for latest
     semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato)
     users.  The official stable Debian 2.2 is stuck with the old
     LilyPond-1.3.24.  Since LilyPond-1.4 has been released, the older
     lilypond1.3 Debian package is now obsolete.

   Please contact Anthony Fok <lilypond@packages.debian.org> for more
information.

   The build scripts are in the subdirectory `debian/'; you can make
the .deb by doing, for example:

     	$ su - root
     	# dpkg --purge lilypond lilypond1.3
     	# exit
     	$ tar xzf lilypond-1.4.3.tar.gz
     	$ cd lilypond-1.4.3
     	$ dch -p -v 1.4.3-0.local.1 "Local build."
     	$ debuild -B
     	$ su - root
     	# dpkg -i ../lilypond_1.4.3*.deb
     	# exit
     	$

   Use command `debuild' instead of `debuild -B' if you have a very
fast machine and want to build the HTML, PS and DVI documentation too.

   For compilation on a Debian GNU/Linux system you need these packages,
in addition to the those needed for running:

   * g++, cpp, libc6-dev, libstdc++<YOUR-LIBSTDC++-VERSION-HERE>-dev

   * libguile<YOUR-LIBGUILE-VERSION-HERE>-dev

   * make, m4, flex, bison

   * gettext

   * groff, texinfo

   * tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev

   * dpkg-dev, debhelper, fakeroot

   * gs, netpbm

   * pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
      in Debian testing/unstable.)

   Most of these are listed on the `Build-Depends' line in the
`debian/control' file.  To ensure the creation of the lilypond deb is
trouble-free, we recommend that you first install the following packages
by running \`apt-get' as root before building the package:

   For Debian 2.2:

     	apt-get install task-debian-devel task-c++-dev \
     		python-base libguile6-dev tetex-bin tetex-dev \
     		tetex-extra flex bison texinfo groff gs \
     		netpbm pnmtopng m4 gettext

   For Debian in development ("unstable", the future 2.3 or 3.0):

     	apt-get install binutils cpp gcc libc6-dev \
             	g++ libstdc++2.10-dev \
     		python-base libguile-dev tetex-bin libkpathsea-dev \
     		tetex-extra flex bison texinfo  groff gs \
     		netpbm m4 gettext

   And, just so that old fonts from previous versions of LilyPond won't
interfere with your build, you may want to do this before the build too:

     	dpkg --purge lilypond lilypond1.3

MacOS X
-------

LilyPond is available through fink, in the unstable cvs distribution.

   You need to:
   * Get the Fink package manager from `http://fink.sourceforge.net'

   * Get the Lilypond package description by enabling the "unstable"
     tree in fink and executing `fink selfupdate-cvs'.

   Then do:

          	fink install lilypond-unstable

   That's it!  The command should compile and install all LilyPond
prerequisites (python, TeX, X11, ghostscript) and then LilyPond itself.

compiling on MacOS X
--------------------

LilyPond has been built on Darwin, to be precise, on:
         Darwin buoux.aspiratie.nl 5.3 Darwin Kernel Version 5.3: Thu Jan 24
         22:06:02 PST 2002; root:xnu/xnu-201.19.obj~1/RELEASE_PPC  Power Macintosh powerpc

   using:

         Apple Computer, Inc. version gcc-932.1, based on gcc version 2.95.2 19991024 (release)

   To make sure you have all packages needed to build LilyPond
installed, run as root:

             apt-get install bash python guile debianutils flex bison texinfo \
                     ghostscript6 netpbm m4 gettext

   and:

             fink install tetex

   For more information about `apt-get' and `fink', see
fink.sourceforge.net (http://fink.sf.net).

   Then, configure, patch, make and install LilyPond using these
commands:

             CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
                 ./configure --prefix=/sw
             make -C lily out/parser.hh out/parser.cc out/config.h
             patch -p0 < darwin.patch
             make -C lily out/parser.o
             make DEPENDENCIES_OUTPUT=/dev/null all
             make install

   For installing, you must be root, of course.

Problems
========

For help and questions use <lilypond-user@gnu.org>.  Please consult the
FAQ before mailing your problems.  If you find bugs, please send bug
reports to <bug-lilypond@gnu.org>.

   Bugs that are not fault of LilyPond are documented here.

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 a bit flaky.  Try downgrading to 2.95.x, or if you're
adventurous (see below), upgrading to 3.1.x.

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

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

             CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
             make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
             patch -p1 < lexer-gcc-3.0.patch
             make conf=gcc-3.0 -C lily

   Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.

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

Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code.  To compile
LilyPond with gcc-3.1.1 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

   This assumes that the GCC 3.1 binaries are called gcc-3.1 and
g++-3.1.  Note that this is *not* fixed in Debian/unstable for flex <=
2.5.4a-26.

Linux-2.4.0, Guile-1.4 -with-threads
------------------------------------

There's a bug in certain kernels around version 2.4.0, that is
triggered when using Guile 1.4 compiled with pthreads.  You'll see
random segmentation fault crashes of LilyPond.  Upgrade to a newer
version of Linux.  If you can't do that, you may try to recompiling
Guile without threads (YMMV):

              guile-1.4$ ./configure --without-threads; make all install

OpenBSD
-------

   * By default, gcc on OpenBSD doesn't include `/usr/local/include'
     and `/usr/local/lib' in the system paths.  Depending upon
     where/how you installed kpathsea and other libraries, you may need
     to refer to the section "Linking to kpathsea".


NetBSD
------

   * The flex precompiled in NetBSD-1.4.2 is broken.  Download
     flex-2.5.4a, build, install.

   * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
     release)) does not include `/usr/pkg' paths.  Configure using:

          CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./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.
     Please run configure like:
                  CONFIG_SHELL=/bin/ksh ksh -c ./configure
     or
                  CONFIG_SHELL=/bin/bash bash -c ./configure

   * Sparc64/Solaris 2.6, GNU make-3.77

     GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
     newer.

   * Sparc64/Solaris 2.6, ld

     Not yet resolved.

AIX
---

   * AIX 4.3 ld

     The following is from the gcc install/SPECIFIC file.

             Some versions of the AIX binder (linker) can fail with a
          relocation    overflow severe error when the -bbigtoc option
          is used to link    GCC-produced object files into an
          executable that overflows the TOC.     A fix for APAR IX75823
          (OVERFLOW DURING LINK WHEN USING GCC AND    -BBIGTOC) is
          available from IBM Customer Support and from its
          27service.boulder.ibm.com website as PTF U455193.

          Binutils does not support AIX 4.3 (at least through release
          2.9). GNU    as and GNU ld will not work properly and one
          should not configure GCC    to use those GNU utilities. Use
          the native AIX tools which do    interoperate with GCC.

     add -Wl,-bbigtoc to USER_LDFLAGS, ie:
              LDFLAGS='-Wl,-bbigtoc' ./configure


