\input texinfo @c -*-texinfo-*-
@setfilename INSTALL.info
@settitle INSTALL - compiling and installing GNU LilyPond

@documentencoding utf-8
@documentlanguage en

@node Top
@top

@contents

@chapter Compiling and installing on Unix


@html
<a name="download-source">
@end html

@section 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
@uref{http://lilypond.org/download,download a precompiled binary}
for your platform.

@subsection Source code

Download source
@itemize @bullet
@item tarballs from
@itemize @bullet
@uref{http://lilypond.org/download/} by HTTP.
@item @uref{ftp://sca.uwaterloo.ca/pub/} by FTP (Canadian mirror).
@end itemize
@item 
CVS from @uref{http://savannah.gnu.org/cvs/?group=lilypond,savannah.gnu.org}
@itemize @bullet
@c @quotation
@example
CVS_RSH=ssh cvs -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/lilypond co lilypond
@end example
@c @end quotation
The CVS repository does not contain generated files.  To create
@file{configure}, run
@example
./autogen.sh
@end example
@end itemize
@end itemize

For information on packaging, see @uref{http://lilypond.org/devel}.

@subsection Precompiled binary packages

Check out @uref{http://lilypond.org/web/install/} for up to date
information on binary packages for your platform.


@section Requirements

@subsection 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.

@itemize

@item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.

@item New Century Schoolbook fonts, as PFB files. These are shipped
with X11 and Ghostscript, and are named @file{c059033l.pfb}
@file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}

@item @uref{http://www.xs4all.nl/~hanwen/mftrace/,mftrace} (1.1.9 or
newer),

You will need to install some additional packages to get mftrace to
work.

@item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
(version 1.6.7 or newer).  If you are installing binary packages, you
may need to install guile-devel or guile-dev or libguile-dev too.

@item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.8 or newer).

@item
 @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 4.x or
newer). 

@item @uref{http://www.python.org,Python} (version 2.3 or newer)

@item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).

@item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.


@item @uref{http://www.gnu.org/software/flex/,Flex} 

@item @uref{http://www.perl.org/,Perl} 

@item @uref{http://www.gnu.org/software/flex/,GNU Bison} 

@item All packages required for running, including development packages with
header files and libraries.

@end itemize

@subsection Running requirements

Running LilyPond requires proper installation of the following
software

@itemize @bullet

@item @uref{http://www.freetype.org/,Freetype} (version 2).
@item @uref{http://www.freetype.org/,FontConfig} (version 2.2).
@item @uref{http://www.pango.org/,Pango} (version 1.6 or newer).
@item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
(version 1.6.5 or newer).
@item @uref{http://www.python.org,Python} (version 2.1 or newer).
@item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
newer. 8.50 recommended)
@end itemize

@subsection Building documentation

You can view the documentation online at
@uref{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
@quotation
@example
make web
@end example
@end quotation

Building the website requires some additional tools and packages

@itemize @bullet
@item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
@item ImageMagick
@item International fonts (see input/regression/utf-8.ly for hints
about which font packages are necessary for your platform)
@item Ghostscript, 8.50 with the patch from
@uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
and the patch from
@uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
@end itemize

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

@quotation
@example
make out=www web-install
@end example
@end quotation


@section Building LilyPond

To install GNU LilyPond, type
@quotation
@example
gunzip -c lilypond-x.y.z | tar xf -
cd lilypond-x.y.z
./configure		# run with --help for applicable options
make
make install
@end example
@end quotation

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

@quotation
@example
make -C mf get-pfa                # requires rpm2cpio
make -C mf get-debian-pfa         # may not be up to date
@end example
@end quotation

If you are not root, you should choose a @code{--prefix} argument that
points into your home directory, e.g.
@quotation
@example
./configure --prefix=$HOME/usr
@end example
@end quotation


@subsection Configuring for multiple platforms

If you want to build multiple versions of LilyPond with different
configuration settings, you can use the @code{--enable-config=CONF}
option of configure.  You should use @samp{make conf=CONF} to generate
the output in @file{out-CONF}.  Example: Suppose you want to build
with and without profiling, then use the following for the normal
build

@quotation
@example
./configure --prefix=$HOME/usr/ --enable-checking
make
make install
@end example
@end quotation

and for the profiling version, specify a different configuration

@quotation
@example
./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
make conf=prof
make conf=prof install
@end example
@end quotation


@section Emacs mode

An Emacs mode for entering music and running LilyPond is contained in
the source archive in the @file{elisp} directory.  Do @command{make
install} to install it to @var{elispdir}.  The file @file{lilypond-init.el}
should be placed to @var{load-path}@file{/site-start.d/} or appended
to your @file{~/.emacs} or @file{~/.emacs.el}.

As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
your @var{load-path} by appending the following line (as modified) to your
@file{~/.emacs}
@c any reason we do not advise:  (push "~/site-lisp" load-path)
@quotation
@example
(setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
@end example
@end quotation


@section Vim mode

A Vim mode for entering music and running LilyPond is contained in the
source archive in @code{$VIM} directory.

The LilyPond file type is detected if the file @file{~/.vim/filetype.vim} @c
has the following content
@quotation
@example
if exists("did_load_filetypes")
  finish
endif
augroup filetypedetect
  au! BufNewFile,BufRead *.ly           setf lilypond
augroup END
@end example
@end quotation

Please include this path by appending the following line to your
@file{~/.vimrc}

@quotation
@example
set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
@end example
@end quotation

@noindent
where $@{LILYPOND_VERISON@} is your lilypond version.  If Lilypond was not
installed in @file{/usr/local/}, then change this path accordingly.


@section Problems

For help and questions use @email{lilypond-user@@gnu.org}.  Send bug
reports to @email{bug-lilypond@@gnu.org}.

Bugs that are not fault of LilyPond are documented here.

@subsection 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

@quotation
@example
$ cd lily; make out/parser.cc
$ vi +4919 out/parser.cc
# append a semicolon to the line containing "__attribute__ ((__unused__))
# save
$ make
@end example
@end quotation



@unnumberedsubsec Gcc-3.0.4

Gcc 3.0.4 is flaky; upgrade GCC.

@unnumberedsubsec 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

@quotation
@example
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
@end example
@end quotation

@unnumberedsubsec MacOS X

For Fink, use the following command to compile.

@verbatim
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
@end verbatim

@unnumberedsubsec OpenBSD

@itemize @bullet
@item
Refer to the section ``Linking to kpathsea'': GCC on OpenBSD doesn't
set include paths for kpathsea.
@end itemize

@unnumberedsubsec NetBSD

@itemize @bullet
@item The flex precompiled in NetBSD-1.4.2 is broken.
Upgrade to flex-2.5.4a.
@end itemize

@unnumberedsubsec  Solaris

@itemize @bullet
@item Solaris7, ./configure

@file{./configure} needs a POSIX compliant shell.  On Solaris7,
@file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
is.  Run configure like
@quotation
@example
	CONFIG_SHELL=/bin/ksh ksh -c ./configure
@end example
@end quotation
or
@quotation
@example
	CONFIG_SHELL=/bin/bash bash -c ./configure
@end example
@end quotation

@end itemize

@bye

