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


Compiling and installing on Unix
  Downloading
    Source code
    Precompiled binaries
    Font problems
  Requirements
    Compilation
    Running requirements
    Building documentation
  Building LilyPond
    Configuring for multiple platforms
  Emacs mode
  Vim mode
  Problems
    Linking to kpathsea
    Gcc-3.0.4
    Flex-2.5.4a and gcc-3.x
    OpenBSD
    NetBSD
    Solaris
    AIX


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

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

Download source tarballs from here:
   * Download development releases from
     `ftp://ftp.lilypond.org/pub/LilyPond/' by FTP and
     `http://www.lilypond.org/ftp/' by HTTP.

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

   Use Xdelta to patch tarballs, e.g. to patch `lilypond-1.4.2.tar.gz'
to `lilypond-1.4.3.tar.gz', do
     	xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz

   For information on packaging and CVS, see `http://lilypond.org/',
under "develoment".

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

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

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

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

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

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

   * Bison (http://www.gnu.org/software/bison/) (version 1.25 or newer,
     but not 1.50 or 1.75).

   * 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 (ftp://ftp.gnu.org/gnu/texinfo/) (version 4.2 or newer).

   * The geometry package for LaTeX
     (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.


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

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

   * TeX.

   * Xdvi and Ghostscript.

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

   For running LilyPond successfully

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

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

You can view the documentation online at
`http://www.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:

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

   * ImageMagick

   * mftrace (http://www.cs.uu.nl/~hanwen/mftrace/) (1.0.17 or newer),

     You will need to install some additional packages to get mftrace to
     work.

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

             make out=www web-install

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, in addition, you want to generate PDF files of your scores and
have installed mftrace, type
     make pfa-fonts
     make install-pfa-fonts
     texhash

   PFA versions of the fonts for the latest LilyPond version can also be
obtained from the internet: download the .deb file that corresponds to
your version, eg.

     wget http://ftp.us.debian.org/debian/pool/main/l/lilypond/lilypond_1.8.0-1_i386.deb
     ar x lilypond_1.8.0-1_i386.deb data.tar.gz
     tar -C / -zxf data.tar.gz /usr/share/lilypond/1.8.0/fonts/type1/
     tar -C / -zxf data.tar.gz /usr/share/lilypond/1.8.0/dvips/
     texhash
   If you are installing LilyPond somewhere else, unpack the appropriate
files as shown, and move them to the appropriate paths. Of course, the
.deb version number should correspond to what you are installing.

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

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

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

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

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 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 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.
     Please run configure like:
          	CONFIG_SHELL=/bin/ksh ksh -c ./configure
     or:
          	CONFIG_SHELL=/bin/bash bash -c ./configure

   * 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, i.e.:
          	LDFLAGS='-Wl,-bbigtoc' ./configure


