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)

International fonts are required to create music with international text or lyrics.  See Fonts for more information.

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, MIDI, performance or error reporting.

To rerun tests, use

       make test-redo           ## redo files differing from baseline
       make test-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.

For checking the coverage of the test suite, do the following

       ./buildscripts/build-coverage.sh
       # uncovered files, least covered first
       python ./buildscripts/coverage.py  --summary out-cov/*.cc
       # consecutive uncovered lines, longest first
       python ./buildscripts/coverage.py  --uncovered out-cov/*.cc

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

Fonts
=====

On MacOs X, all fonts are installed by default.

On Linux, international fonts are installed by different means on every distribution.  We cannot list the exact commands or packages that are necessary, as each distribution is different, and the exact package names within each distribution changes.  Here are some hints, though:

Red Hat Fedora

    taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
         ttfonts-zh_CN fonts-ja fonts-hebrew

Debian GNU/Linux

   apt-get install emacs-intl-fonts xfonts-intl-.* \
        ttf-kochi-gothic ttf-kochi-mincho \
        xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi