* configure.in: bump GCC requirements to 3.x

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

@node Top, , , (dir)
@top
@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

@contents

@chapter Compiling and installing on Unix


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

Building LilyPond is an involved process. We advise to use binary
packages if these are available for your platform.



@subsection Source code

Download source tarballs from here:
@itemize @bullet
@item Download development releases from
@uref{ftp://ftp.lilypond.org/pub/LilyPond/} by FTP and
@uref{http://www.lilypond.org/ftp/} by HTTP.
@item @uref{ftp://sca.uwaterloo.ca/pub/} by FTP (Canadian mirror).
@end itemize


Use Xdelta to patch tarballs, e.g. to patch  
@file{lilypond-1.4.2.tar.gz} to @file{lilypond-1.4.3.tar.gz}, do
@example
        xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
@end example

For information on packaging and CVS, see  
@uref{http://lilypond.org/}, under ``develoment''.


@subsection Precompiled binaries

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


@subsection Font problems

If you are upgrading from a previous version of LilyPond, be sure to
remove all old font files. These include @file{.pk} and @file{.tfm} files
that may be located in @file{/var/lib/texmf}, @file{/var/spool/texmf},
@file{/var/tmp/texmf} or @file{@var{prefix}/share/lilypond/fonts/}.  A
script automating this has been included, see
@file{buildscripts/clean-fonts.sh}.




@section Requirements

@subsection Compilation

You need the following packages to compile LilyPond:

@itemize
@item
 @uref{http://gcc.gnu.org/,
The GNU c++ compiler} (version 3.1 or newer).
EGCS and 2.x are known to cause crashes.

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

@item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version 1.6.0 or newer).

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

@item  @uref{http://www.gnu.org/software/flex/,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.1.sh in the source directory.

@item @uref{http://www.gnu.org/software/bison/,Bison} (version 1.25 or
newer, but not 1.50 or 1.75).

@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 or libkpathsea-dev) package too.

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

@item The
@uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,geometry
package for LaTeX}.

 This package is normally included with the @TeX{} distribution.

@item kpathsea, a library for searching (@TeX{}) files.

@ignore
@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 (i.e., 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 ignore

@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 @uref{http://www.gnu.org/software/guile/guile.html,GUILE} 1.6.0, or newer.
@end itemize

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
@file{buildscripts/out/lilypond-profile} and
@file{buildscripts/out/lilypond-login}.

@subsection Building documentation

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

Building the website requires some additional tools: 

@itemize @bullet
@item The @uref{http://netpbm.sourceforge.net/,netpbm utilities} see 
@item ImageMagick
@item @uref{http://www.cs.uu.nl/~hanwen/mftrace/,mftrace} (1.0.17 or
newer),

  You will need to install some additional packages to get mftrace 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, in addition, you want to generate PDF files of your scores and have 
installed mftrace, type
@example 
make pfa-fonts
make MAKE_PFA_FILES=1 install
texhash
@end example 

PFA versions of the fonts for the latest LilyPond version can also be
obtained from the internet: download the .deb file that corresponds to
your version, eg.  

@example
wget http://ftp.us.debian.org/debian/pool/main/l/lilypond/lilypond_1.8.0-1_i386.deb
ar x lilypond_1.8.0.-1_i386.deb
tar -C / -zxf  data.tar.gz /usr/share/lilypond/1.8.0/fonts/type1/
tar -C / -zxf  data.tar.gz /usr/share/lilypond/1.8.0/dvips/
texhash
@end example
If you are installing LilyPond somewhere else, unpack the appropriate
files as shown, and move them to the appropriate paths. Of course, the
.deb version number should correspond to what you are installing.



If you are doing an upgrade, you should remove all @file{feta}
@code{.pk} and @code{.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, e.g.:
@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=$HOME/usr/ --enable-checking
        make
        make install
@end example 

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

@example 
        ./configure --prefix=$HOME/usr/ --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 contained in
the source archive as @file{lilypond-mode.el},
@file{lilypond-indent.el}, @file{lilypond-font-lock.el} and
@file{lilypond.words}.  You should install these files to a directory
included in your @var{load-path}. 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 or, e.g., @file{~/site-lisp/} 
to your @var{load-path}. Append the following line (modified) to your 
@file{~/.emacs}:
@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. Append the content of @file{vimrc} to @file{~/.vimrc}
to get shortcuts. Install file @file{lilypond.words} to @file{~/.vim/} to 
get auto-completion. Syntax highlighting you get by installing 
@file{lilypond.vim} to @file{~/.vim/syntax/} and appending the following
to @file{~/.vim/filetype.vim}:
@quotation
@example
        " my filetype file
        if exists("did_load_filetypes")
          finish
        endif
        augroup filetypedetect
          au! BufRead,BufNewFile  *.ly          setfiletype lilypond
        augroup
@end example
@end quotation



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

@subsection 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
@file{/usr/local/lib/} and @file{/usr/local/include/} respectively,
you have to explicitly tell configure where to find it. To do this:

@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
Once configure has found them, the paths are stored in
@file{config.make} and will be used even if you don't have the
environment variables set during make.


@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 you may do

@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


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

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

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

@end example
@end ignore

@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.  Please run configure like:
@example
        CONFIG_SHELL=/bin/ksh ksh -c ./configure
@end example
or:
@example
        CONFIG_SHELL=/bin/bash bash -c ./configure
@end example

@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, i.e.:
@example
        LDFLAGS='-Wl,-bbigtoc' ./configure
@end example

@end itemize


@bye