release: 1.5.24

[lilypond.git] / Documentation / topdocs / INSTALL.texi

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

@html
<!--- @@WEB-TITLE@@=Installation Instructions --->
@end html

@node Top, , , (dir)
@top

@contents

@chapter INSTALL - compiling and installing GNU LilyPond


This document describes how to build LilyPond on Unix platforms.  It is
also known to run and compile on Windows NT/95/98 as well.  More
information on this topic can be found at the
@uref{http://www.lilypond.org/gnu-windows/, LilyPond on Windows page}.


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

@section Downloading

Even numbered versions are `stable'. The webpages for the stable version
(1.2) reside @uref{http://www.gnu.org/software/lilypond, on the GNU
servers}. Big enhancements go into the latest odd numbered version
(1.3), whose webpages are on @uref{http://www.lilypond.org/,the lilypond
site}.

@subsection Source code

If you want to compile LilyPond from source, download here:
@itemize @bullet
@item Download development releases from
@c Hmm, these won't show up in lilypond.org/stats
@c Otoh, lilypond.org is not updated when release mail arrives
@uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/} by FTP and
@uref{http://ftp.cs.uu.nl/pub/GNU/LilyPond/}, by HTTP.
@item @uref{ftp://sca.uwaterloo.ca/pub/} by FTP (Canadian mirror)
@item at @code{lilypond.org} 
@uref{ftp://ftp.lilypond.org/pub/LilyPond/} by FTP and
@uref{http://www.lilypond.org/ftp/} by HTTP.
@end itemize

Of course, if your platform supports LilyPond, such as Debian GNU/Linux,
FreeBSD, OpenBSD or NetBSD, you're encouraged to use the native build
from source drill.

For Red Hat Linux and SuSE Linux, @file{.spec} files are included in the
tarball; see instructions below.

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



@subsection Precompiled binaries

If you want to track bleeding edge development, try:

@itemize @bullet
@item @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond/, Debian
GNU/Linux} usually has the latest binaries for the most useful stable
and development versions, while
@item @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/,
Mandrake Cooker} also provides fairly recent versions.
@end itemize

Binaries are made available for other popular platforms, but as we need
to compile them ourselves, they are not updated for every version
released.

@itemize @bullet
@item @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/, Red Hat i386}
@item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE, SuSE}
@item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/,
LinuxPPC}
@item
@uref{http://www.lilypond.org/gnu-windows/, Windows}
@end itemize

@subsection Upgrading

There are two options for upgrading sources.

@itemize
@item if you have an unpacked source tree of a previous version, you
may the patches.

@emph{If you upgrade by patching do remember to rerun autoconf after
applying the patch}.

@item if you have the @code{.tar.gz} file of a previous release, you can
use
@uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
 This is much safer than using patches, and is the recommended way.

The following command produces @file{lilypond-1.4.3.tar.gz} from
@file{lilypond-1.4.2.tar.gz} identical (up to compression dates) to the .3
on the FTP site.
@example
  xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
@end example
@end itemize

@section Requirements

@subsection Compilation

You need the following packages to compile Lilypond.

@itemize
@item A reasonably new C++ compiler:  EGCS 1.1, GCC 2.95.2 or
newer. Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.

@item  Python 1.5,
Check out @uref{http://www.python.org, the python website}.

@item  GUILE 1.3.4 or newer,  check out
@uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
Version 1.4 is recommended for better performance.

@item GNU Make. 
Check out
@uref{ftp://ftp.gnu.org/gnu/make/, the GNU
make FTP directory}.

@item Flex (version 2.5.4a or newer). 
Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.

@item Bison (version 1.25 or newer).
Check out @uref{http://www.gnu.org/software/bison/,the bison  webpage}

@item @TeX{}.

@TeX{} is used as an output backend.

Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf}, @file{.afm}, @file{.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 package too.

@item Texinfo (version 4.0 or newer).
The documentation of lily is written in texinfo.  Check out
@uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.

@item The geometry package for LaTeX is needed to use ly2dvi.  
It is available at
@uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
FTP directory for @code{geometry}}. This package is normally included
with the @TeX{} distribution.

@item kpathsea, a library for searching (@TeX{}) files.  @code{kpathsea} is
usually included with your installation of @TeX{}.  You may need to install
a tetex-devel or tetex-dev package too.

In the very unlikely case that kpathsea is not available for your
platform (ie, you're not running GNU/Linux, Windows, or any recent
UNIX), you can compile LilyPond without kpathsea support.  In that case,
you'll probably have to indicate where @TeX{}'s tfm files live.  Invoke
configure something like:

@example
./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
@end example


@item pktrace, [OPTIONAL], needed for generating PostScript Type1
fonts. Get it from  @uref{http://www.cs.uu.nl/~hanwen/pktrace/}

@item autotrace-0.27a, [OPTIONAL], needed for generating PostScript Type1
fonts. @uref{http://autotrace.sourceforge.net}.
 
@item MetaPost [OPTIONAL] needed for generating PostScript Type3 fonts. Please
note that tetex-0.4pl8 (included with Red Hat 5.x) does not include
@file{mfplain.mp}, which is needed for producing the scalable font
files.

If you don't have MetaPost and don't want to use PostScript output, then
edit @file{mf/GNUmakefile}, removing the line saying @code{PFA_FILES=}.



@end itemize

@subsection Running requirements

GNU LilyPond does use a lot of resources. For operation you need the
following software

@itemize @bullet
@item @TeX{}.
@item Xdvi and Ghostscript
@item GUILE 1.3.4, or newer.  Check out
@uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
@end itemize

For running LilyPond successfully you have to help @TeX{} and MetaFont find
various files.  The recommended way of doing so is adjusting the
environment variables in the start-up scripts of your shell. Appropriate
Csh and bourne sh scripts are left in
@file{buildscripts/out/lilypond-profile} and
@file{buildscripts/out/lilypond-login} after compilation.

LilyPond is a big and slow program.  A fast CPU and plenty of RAM is
recommended for comfortable use.

@subsection Website requirements

The documentation comes in the form of a website. You can view this
website on the internet, but you can also build it locally. This process
requires a successful compile of lilypond. The website is built 
by issuing
@example 

  make web-doc
 
@end example 

Building the website requires some additional tools: 

@itemize @bullet
@item xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
        The original is at
@uref{ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz,the
netpbm FTP site}

@item pnmtopng. The original is
at
@uref{ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz,in
the pnmtopng FTP site}.

@item @uref{http://www.lri.fr/~filliatr/ftp/bibtex2html/, Bibtex2html}, or
@uref{http://www.uni-koblenz.de/ag-ki/ftp/bib2html/, Bib2html}.
Bibtex2html is available in debian, while bib2html is in some rpm based
distributions.
Bib2html, in turn depends on man2html for proper installation.
man2html can be had from @uref{http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05,http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05}.

The website will build without bib converter utility, but you will not
see our hypertextified bibliography.

@item texinfo (a development release)
The documentation will build with texinfo-4.0, but if you want split
html pages, you're best off using the lates pretest version from
@uref{ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz,
texinfo-4.0b} or
@uref{ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz,texinfo-4.0b}
@end itemize

@section Building  LilyPond

to install GNU LilyPond, type:
@example 
        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      
@end example 

If you are doing an upgrade, you should remove all @file{feta}
@code{.pk} and @file{.tfm} files.  A script has been provided to do the
work for you, see @file{buildscripts/clean-fonts.sh}.


If you are not root, you should choose a @code{--prefix} argument that
points into your home directory, eg.
@example 

        ./configure --prefix=$HOME/usr
 
@end example 

In this case, you have to insert the contents of
@code{buildscripts/out/lilypond-login} or
@code{buildscripts/out/lilypond-profile} into your start up scripts by
hand.



@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 I want to build with
and without profiling.  Then I'd use the following for the normal build,
@example 

      ./configure --prefix=~ --enable-checking
      make
      make install
@end example 

and for the profiling version, I specify a different configuration.

@example 

      ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
      make conf=prof
      make conf=prof install

@end example 





@section Emacs mode

An Emacs mode for entering music and running LilyPond is included with
the source archive as @file{lilypond-mode.el} and
@file{lilypond-font-lock.el}.  You should install these files somewhere
in your @var{load-path}.  If you have installed a precompiled LilyPond
package, these files can be found in
@file{/usr/share/doc/lilypond-x.y.z/}.

Add this to your @file{~/.emacs} or @file{~/.emacs.el}, or install this
file in Emacs' @file{site-start.d}:
@example
    ;;; lilypond-init.el --- Startup code for LilyPond mode

    (load-library "lilypond-mode.el")
    (setq auto-mode-alist
      (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
    (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
@end example

If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode is
automatically loaded, you not even need to modify your @code{~/.emacs}
file.

@section Compiling for distributions 

@subsection Red Hat Linux

Red Hat 7.0 i386 RPMS are available from
@uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.

You can also compile them yourself.  A spec file is in
@file{make/out/lilypond.redhat.spec}. This file is distributed along
with the sources.  You can make the rpm by issuing
@example 

        tar xfz lilypond-x.y.z.tar.gz
        rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
        rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z

@end example 

For running on a Red Hat system you need these packages: guile, tetex,
tetex-latex, tetex-dvips, libstdc++, python, ghostscript.

For compilation on a Red Hat system you need these packages, in addition
to the those needed for running: glibc-devel, gcc-c++, libstdc++-devel,
guile-devel, flex, bison, texinfo, tetex-devel, groff,
libgr-progs.


@subsection LinuxPPC


Some LinuxPPC RPMS should available from
@uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.

A LinuxPPC RPM can be made using the @file{lilypond.redhat.spec} file.

@subsection SuSE

Some SUSE RPMS should available from
@uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.

You can also compile a RPM for SUSE yourself.  A spec file is in
@file{make/out/lilypond.suse.spec}, see the instructions for building
the Red Hat RPM.

You must have the following packages: guile tcsh tetex te_latex te_kpath
te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
gs_serv gs_lib gs_fonts guile

@subsection Slackware

No precompiled packages for Slackware are available.

Problems have been reported with Slackware 7.0; apparently, it ships
with a faulty compiler. Do not compile LilyPond with -O2 on this
platform.

@subsection Mandrake

Some binaries are available at rpmfind.net. Refer to 
@uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.

You can also compile a RPM for Mandrake yourself.  A spec file is in
@file{make/out/lilypond.mandrake.spec}, see the instructions for building
the Red Hat RPM.

@subsection Debian GNU/Linux

A Debian package is also available.  You may install it easily by running
@command{apt-get} as root:
@example

        apt-get install lilypond lilypond-doc
@end example

You can also compile the .deb for Debian yourself, do:
@example

        apt-get -b source lilypond
@end example

If you're real impatient, you may even do:
@example

        cd lilypond-x.y.z   # a previous version
        uscan               # download and build latest directly from upstream
@end example


Debian's @TeX{} installation is a bit short on memory, you may want to
increase it like this:
@example
--- /etc/texmf/texmf.cnf.dpkg   Sun Jan 28 14:12:14 2001
+++ /etc/texmf/texmf.cnf        Fri Apr 27 11:09:35 2001
@@ -384,8 +384,8 @@
 main_memory.context = 1500000
 main_memory.mpost = 1000000
 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
-extra_mem_top = 0    % extra high memory for chars, tokens, etc.
-extra_mem_bot = 0    % extra low memory for boxes, glue, breakpoints, etc.
+extra_mem_top = 100000    % extra high memory for chars, tokens, etc.
+extra_mem_bot = 100000    % extra low memory for boxes, glue, breakpoints, etc.
 
 obj_tab_size.context = 256000

@end example

You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
environment variables if you do not want to or cannot modify
@file{/etc/texmf/texmf.cnf}.

Alternatively, visit

@itemize @bullet
@item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
@item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
package is now obsolete.
@end itemize

Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
information.

The build scripts are in the subdirectory @file{debian/}; you can
make the .deb by doing, for example:

@example
        $ su - root
        # dpkg --purge lilypond lilypond1.3
        # exit
        $ tar xzf lilypond-1.4.3.tar.gz
        $ cd lilypond-1.4.3
        $ dch -p -v 1.4.3-0.local.1 "Local build."
        $ debuild -B
        $ su - root
        # dpkg -i ../lilypond_1.4.3*.deb
        # exit
        $
@end example

Use command @command{debuild} instead of @command{debuild -B} if you have
a very fast machine and want to build the HTML, PS and DVI documentation
too.

For compilation on a Debian GNU/Linux system you need these packages,
in addition to the those needed for running:

@itemize @bullet
@item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
@item libguile<@var{your-libguile-version-here}>-dev
@item make, m4, flex, bison
@item gettext
@item groff, texinfo
@item bibtex2html (not in Debian 2.2)
@item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
@item dpkg-dev, debhelper, fakeroot
@item gs, netpbm
@item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
  in Debian testing/unstable.)
@end itemize

Most of these are listed on the @samp{Build-Depends} line in the
@file{debian/control} file.  To ensure the creation of the lilypond deb is
trouble-free, we recommend that you first install the following packages
by running \@command{apt-get} as root before building the package:

For Debian 2.2:

@example
        apt-get install task-debian-devel task-c++-dev \
                python-base libguile6-dev tetex-bin tetex-dev \
                tetex-extra flex bison texinfo groff gs \
                netpbm pnmtopng m4 gettext
@end example

For Debian in development ("unstable", the future 2.3 or 3.0):

@example
        apt-get install binutils cpp gcc libc6-dev \
                g++ libstdc++2.10-dev \
                python-base libguile-dev tetex-bin libkpathsea-dev \
                tetex-extra flex bison texinfo bibtex2html groff gs \
                netpbm m4 gettext
@end example

And, just so that old fonts from previous versions of LilyPond won't
interfere with your build, you may want to do this before the build too:

@example
        dpkg --purge lilypond lilypond1.3
@end example


@c Why isn't this in BUGS (where it belongs?)
@section Problems

For help and questions use @email{lilypond-user@@gnu.org}.  Please
consult the FAQ before mailing your problems.  If you find bugs, please
send bug reports to @email{bug-lilypond@@gnu.org}.

Bugs that are not fault of LilyPond are documented here.

@unnumberedsubsec FLex-2.5.4a and gcc-3.0

Flex 2.5.4a does not produce g++-3.0 compliant C++ code.  To compile
LilyPond with gcc-3.0 you may do:

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

Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.

 
 
@unnumberedsubsec Linux-2.4.0, Guile-1.4 --with-threads

There's a bug in certain kernels around version 2.4.0, that is
triggered when using Guile 1.4 compiled with pthreads.  You'll see
random segmentation fault crashes of LilyPond.  Upgrade to a newer
version of Linux.  If you can't do that, you may try to recompiling
Guile without threads (YMMV):

@example
         guile-1.4$ ./configure --without-threads; make all install
@end example


@unnumberedsubsec NetBSD

@itemize @bullet
@item The flex precompiled in NetBSD-1.4.2 is broken.
Download flex-2.5.4a, build, install.

@item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
release)) does not include @file{/usr/pkg} paths.  Configure using:
@example

CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure

@end example

@end itemize

@unnumberedsubsec  Solaris:

@itemize @bullet
@item Sparc64/Solaris 2.6, GNU make-3.77

GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.

@item Sparc64/Solaris 2.6, ld

Not yet resolved.
@end itemize


@unnumberedsubsec   AIX

@itemize @bullet
@item AIX 4.3 ld

The following is from the gcc install/SPECIFIC file.
@quotation
   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.
@end quotation

add -Wl,-bbigtoc to USER_LDFLAGS, ie:
@example
    LDFLAGS='-Wl,-bbigtoc' ./configure
@end example

@end itemize


@bye