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 1.1 may work, but is no longer supported.

  * 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.0.patch and lexer-gcc-3.1.sh in the source directory.

  * Bison (http://www.gnu.org/software/bison/) (version 1.25 or newer).

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

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 MAKE_PFA_FILES=1 install
             texhash

PFA versions of the fonts for the latest LilyPond version can also be obtained from the web site using

             mkdir /tmp/newfonts
             cd /tmp/newfonts/
             wget -l 1 -nd -r -A pfa,map http://lilypond.org/stable/mf/out/
             mv *.pfa $LILYPONDSHARE/fonts/type1/
             mv *.map $LILYPONDSHARE/dvips/
             texhash

where $LILYPONDSHARE denotes /usr/share/lilypond/1.7.*/ or wherever LilyPond is installed on your system.

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.0 compliant C++ code.  To compile LilyPond with gcc-3.0 you may do

     	CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
     	make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
     	patch -p1 < lexer-gcc-3.0.patch
     	make conf=gcc-3.0 -C lily

Flex-2.5.4a and gcc-3.1.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.

  * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1 release)) does not include /usr/pkg paths.  Configure it using:

          	CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./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.  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