* Documentation/topdocs/INSTALL.texi (Top): Add some warnings

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

@node 
@comment  node-name,  next,  previous,  up\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/ME/XP as well.
More information on this topic can be found at the
@uref{http://www.lilypond.org/cygwin/, 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.4) reside @uref{http://www.gnu.org/software/lilypond, on the GNU
servers}. Big enhancements go into the latest odd numbered version
(1.5), 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.


@subsubsection Anonymous CVS access

Short version:

@quotation
@example
cvs -d :pserver:anoncvs@@lilypond.org:/home/lilypond login
cvs -d :pserver:anoncvs@@lilypond.org:/home/lilypond co -P lilypond
@end example
@end quotation

See @uref{http://lilypond.org/wiki/?CVS} for more information.

@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 The GNU c++ compiler (version 2.95.2 or newer).
EGCS 1.1 may work, but is no longer supported.
Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.

WARNING: if you choose to upgrade to GCC 3.x, enquire if your
distribution supports g++ 3.x and flex.

@item Python (version 1.5 or newer).
Check out @uref{http://www.python.org, the python website}.

@item GUILE (version 1.4 or newer), --without-threads.
Using guile, ./configure'd --with-threads may give nasty memory
corruption errors on large scores.
Check out
@uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.

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

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 a workaround, see
lexer-gcc-3.0 below.

@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.2 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. If kpathsea is not installed in
a directory where the compiler normally looks, read the hints for
Slackware below.

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:

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

@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.4, or newer, --without-threads.  Check out
@uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
Using guile, ./configure'd --with-threads may give nasty memory
corruption errors on large scores.
@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 The netpbm utilities, see @uref{http://netpbm.sourceforge.net/}
@item pktrace 1.0 or newer, needed for generating PostScript Type1
fonts. Get it from @uref{http://www.cs.uu.nl/~hanwen/pktrace/}.  You
will need to install some additional packages to get pktrace to work.
@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,
@c prefix=~ ?
@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},
@file{lilypond-indent.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}:
@quotation
@example
  ;;; lilypond-init.el --- Startup code for LilyPond mode

  (autoload 'LilyPond-mode "lilypond-mode")
  (setq auto-mode-alist
        (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))

  (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
@end example
@end quotation

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.x i386 RPMS are available from
@uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.  For running on
a Red Hat system you need these packages: guile, tetex, tetex-latex,
tetex-dvips, libstdc++, python, ghostscript.

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 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, groff, pktrace,
netpbm-progs, autotrace, t1utils.



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

At least on Slackware 8.0, you have to manually specify the paths to the
Kpathsea library, using
@itemize
@item @code{rm config.cache}
@item @code{export LDFLAGS=-L/usr/share/texmf/lib}
@item @code{export CPPFLAGS=-I/usr/share/texmf/include}
@item @code{./configure}
@end itemize


@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
--- texmf.cnf.orig      Sun Dec 16 23:47:07 2001
+++ texmf.cnf   Sun Dec 16 23:46:34 2001
@@ -411,8 +411,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 = 1000000    % extra high memory for chars, tokens, etc.
+extra_mem_bot = 1000000    % extra low memory for boxes, glue, breakpoints, etc.
 
 obj_tab_size.context = 300000
 
@@ -430,7 +430,7 @@
 % Max number of characters in all strings, including all error messages,
 % help texts, font names, control sequences.  These values apply to TeX and MP.
 pool_size.context = 750000
-pool_size = 125000             
+pool_size = 250000             
 % Minimum pool space after TeX/MP's own strings; must be at least
 % 25000 less than pool_size, but doesn't need to be nearly that large.
 string_vacancies.context = 45000
@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 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  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

@subsection MacOS X

LilyPond is available through fink, in the unstable cvs distribution.

You need to:
@itemize @bullet
@item Get the Fink package manager from @uref{http://fink.sourceforge.net}
@item Get the Lilypond package description by enabling the "unstable" tree
in fink and executing @command{fink selfupdate-cvs}.
@end itemize

Then do:
@quotation
@example
        fink install lilypond-unstable
@end example
@end quotation

That's it!  The command should compile and install all LilyPond
prerequisites (python, TeX, X11, ghostscript) and then LilyPond
itself.


@subsubsection compiling on MacOS X
LilyPond has been built on Darwin, to be precise, on:
@example
    Darwin buoux.aspiratie.nl 5.3 Darwin Kernel Version 5.3: Thu Jan 24
    22:06:02 PST 2002; root:xnu/xnu-201.19.obj~1/RELEASE_PPC  Power Macintosh powerpc
@end example

using:   

@example
    Apple Computer, Inc. version gcc-932.1, based on gcc version 2.95.2 19991024 (release)
@end example

To make sure you have all packages needed to build LilyPond installed,
run as root:

@example
        apt-get install bash python guile debianutils flex bison texinfo \
                ghostscript6 netpbm m4 gettext
@end example        

and:
                
@example
        fink install tetex
@end example        

For more information about @file{apt-get} and @file{fink}, see
@uref{http://fink.sf.net,fink.sourceforge.net}.

@c  brokenness of autoconf; don't ask
Then, configure, patch, make and install LilyPond using these commands:

@example
        CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
            ./configure --prefix=/sw
        make -C lily out/parser.hh out/parser.cc out/config.h
        patch -p0 < darwin.patch
        make -C lily out/parser.o
        make DEPENDENCIES_OUTPUT=/dev/null all
        make install
@end example

For installing, you must be root, of course.

@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