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

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

Even numbered minor versions are `stable' (2.6, 2.8, etc), while odd version are development releases (2.7, 2.9, etc).  Building LilyPond is an involved process.  If possible download a precompiled binary (http://lilypond.org/install) for your platform.

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

Download source

  * tarballs from http://lilypond.org/download/ by HTTP.

  * tarballs from http://download.linuxaudio.org/lilypond/ by HTTP.

  * GIT from git.sv.gnu.org (http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary)

          git clone git://git.sv.gnu.org/lilypond.git

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

  * New Century Schoolbook fonts, as PFB files. These are shipped with X11 and Ghostscript, and are named c059033l.pfb c059036l.pfb, c059013l.pfb and c059016l.pfb

  * mftrace (http://www.xs4all.nl/~hanwen/mftrace/) (1.1.19 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.8.2 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 4.x or newer).

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

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

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

  * Flex (http://www.gnu.org/software/flex/)

  * Perl (http://www.perl.org/)

  * GNU Bison (http://www.gnu.org/software/flex/)

  * 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.12 or newer).

  * GUILE (http://www.gnu.org/software/guile/guile.html) (version 1.8.2 or newer), or patch 1.8.1 with http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch.

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

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

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)

  * Ghostscript, 8.50 with the patch from http://bugs.ghostscript.com/show_bug.cgi?id=688154 and the patch from http://bugs.ghostscript.com/show_bug.cgi?id=688017.

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

          make out=www web-install

Testing LilyPond
================

LilyPond comes with an extensive suite that excercises the entire program. This suite can be used to automatically check the impact of a change. This is done as follows

       make test-baseline
       apply your changes, compile
       make check

This will leave an HTML page out/test-results/index.html.  This page shows all the important differences that your change introduced, whether in the layout, the MIDI output, or error reporting.

To rerun tests, use

       make test-clean          ## remove files differing from baseline
       make test-real-clean     ## remove all test results

and then run make check again.

For tracking memory usage as part of this test, you will need GUILE CVS; especially the following patch: http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch.

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

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

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

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