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

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

Even numbered minor versions are `stable' (2.4, 2.6 etc), while odd version are development releases (2.5, 2.7, 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/web/install/ 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/) 20050624 or newer.

  * mftrace (http://www.xs4all.nl/~hanwen/mftrace/) (1.1.9 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.

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

  * The GNU c++ compiler (http://gcc.gnu.org/) (version 3.3 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).

  * FontConfig (http://www.freetype.org/) (version 2.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

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

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.

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

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

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

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