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

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 download a precompiled binary (http://lilypond.org/download) for your platform.

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.

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

Check out http://lilypond.org/download for up to date information on binary packages for your platform.

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

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.

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

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

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

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

  * International fonts (see input/regression/utf-8.ly for hints about which font packages are necessary for your platform)

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 for applicable options
          make
          make install

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 not root, you should choose a --prefix argument that points into your home directory, e.g.

          ./configure --prefix=$HOME/usr

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

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

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/

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

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