Doc: resolve various FIXMEs.

[lilypond.git] / Documentation / included / compile.itexi

@c -*- coding: utf-8; mode: texinfo; -*-


@c DO NOT TRANSLATE THIS FILE

@c include any node/sections from the higher-level *texi file.
@c   @n ode Compiling from source
@c   @s ection Compiling from source

@menu
* Downloading source code::
* Requirements::
* Building LilyPond::
* Building documentation::
* Testing LilyPond::
* Problems::
@end menu

@node Downloading source code
@subsection Downloading source code

Download source

@itemize
@item tarballs from
@uref{http://lilypond.org/download/} by HTTP.
@item tarballs from
@uref{http://download.linuxaudio.org/lilypond/} by HTTP.
@item
GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}

@example
git clone git://git.sv.gnu.org/lilypond.git
@end example

The repository does not contain generated files.  To create
@file{configure}, run
@example
./autogen.sh
@end example
@end itemize

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


@node Requirements
@subsection Requirements

@unnumberedsubsubsec Compilation

In addition to the packages needed for running LilyPond (see below), you
need the following extra packages for building.

Below is a full list of packages needed to build LilyPond.  However, for
most common distributions there is an easy way of installing most all
build dependencies in one go

@multitable @columnfractions .5 .5
@headitem Distribution
@tab Command

@item Debian, Ubuntu
@tab @code{sudo apt-get build-dep lilypond}

@item Fedora, RHEL
@tab @code{sudo yum-builddep lilypond}

@item openSUSE, SLED
@c sorry for the idiosyncratic command, I really asked and argued
@c for "zypper build-dep" :-(
@tab @code{sudo zypper --build-deps-only source-install lilypond}

@end multitable

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 @uref{http://metafont.tutorial.free.fr/,MetaFont} (mf-nowin, mf, mfw or
mfont binaries) and @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html,MetaPost}
(mpost binary), usually packaged with a @LaTeX{} distribution like
tetex or texlive.

@item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils,t1utils}
(version 1.33 or newer recommended).

@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.gnu.org/software/guile/guile.html,GUILE} (version
1.8.2 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.11 or newer).

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

@item @uref{http://www.python.org,Python} (version 2.4 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}
(version 0.17 or newer).

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

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

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

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

@end itemize


@unnumberedsubsubsec Running requirements

Running LilyPond requires proper installation of the following software

@itemize

@item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
@item @uref{http://fontconfig.org/,FontConfig} (version 2.2 or newer).
@item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
@item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
(version 1.8.2 or newer)
@item @uref{http://www.python.org,Python} (version 2.4 or newer).
@item @uref{http://www.ghostscript.com,Ghostscript} (version 8.60 or
newer).
@item Dejaview.  (This is normally installed by default)
@end itemize

International fonts are required to create music with international text
or lyrics.


@unnumberedsubsubsec Requirements for 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, and some
additional tools and packages:

@itemize
@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.60 or newer
@item @uref{http://www.nongnu.org/texi2html/,Texi2HTML} 1.82
@item rsync
@end itemize


@node Building LilyPond
@subsection Building LilyPond

@unnumberedsubsubsec Compiling

To install GNU LilyPond, type

@example
gunzip -c lilypond-x.y.z | tar xf -
cd lilypond-x.y.z
./configure             # run with --help for applicable options
make
su -c 'make install'
@end example

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

If you encounter any problems, please see @ref{Problems}.


@unnumberedsubsubsec Compiling 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 @command{configure}.  You should use @code{make conf=CONF}
to generate the output in @file{out-CONF}.  For example, suppose you
want to build with and without profiling, then use the following for
the normal build

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

and for the profiling version, 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


@unnumberedsubsubsec Compiling outside the source tree

It is possible to compile LilyPond in a build tree different from the
source tree, with @code{--srcdir} option of @command{configure}:

@example
mkdir lily-build && cd lily-build
@var{sourcedir}/configure --srcdir=@var{sourcedir}

@end example


@unnumberedsubsubsec Useful @command{make} variables

If a less verbose build output if desired, the variable
@code{QUIET_BUILD} may be set to @code{1} on @command{make} command
line, or in @file{local.make} at top of the build tree.


@node Building documentation
@subsection Building documentation

This requires a successful compile of LilyPond, or using an external
LilyPond binary.

@menu
* Commands for building documentation:: Compiling and installing the documentation.
* Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
@end menu

@node Commands for building documentation
@unnumberedsubsubsec Commands for building documentation

The documentation is built by issuing

@example
make doc
@end example

After compilation, the HTML documentation tree is available in
@file{out-www/offline-root/}, and can be browsed locally.  Various
portions of the documentation can be found by looking in
@file{out/} and @file{out-www} subdirectories in other places in
the source tree, but these are only @emph{portions} of the docs.
Please do not complain about anything which is broken in those
places; the only complete set of documentation is in
@file{out-www/offline-root/} from the top of the source tree.

The HTML, PDF and if available Info files can be installed into the
standard documentation path by issuing

@example
make install-doc
@end example

@noindent
This also installs Info documentation with images if the installation
prefix is properly set; otherwise, instructions to complete proper
installation of Info documentation are printed on standard output.

Compilation of documentation in Info format with images can be done
separately by issuing

@example
make info
@end example

@noindent
Separate installation of this documentation is done by issuing

@example
make install-info
@end example

@noindent
Note that to get the images in Info documentation, @code{install-doc}
target creates symbolic links to HTML and PDF installed documentation
tree in @file{@var{prefix}/share/info}, in order to save disk space,
whereas @code{install-info} copies images in
@file{@var{prefix}/share/info} subdirectories.

It is possible to build a documentation tree in
@file{out-www/online-root/}, with special processing, so it can be
used on a website with content negotiation for automatic language
selection; this can be achieved by issuing

@example
make WEB_TARGETS=online doc
@end example

@noindent
and both @q{offline} and @q{online} targets can be generated by issuing

@example
make WEB_TARGETS="offline online" doc
@end example

Several targets are available to clean the documentation build and
help with maintaining documentation; an overview of these targets is
available with

@example
make help
@end example

@noindent
from every directory in the build tree.  Most targets for
documentation maintenance are available from
@file{Documentation/}.  For more information, see
@rcontrib{Documentation work}.

The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a
less verbose build output, just like for building the programs.


@knownissues

The most time consuming task for building the documentation is running
LilyPond to build images of music, and there cannot be several
simultaneously running @command{lilypond-book} instances, so @code{-j}
@command{make} option does not significantly speed up the build process.
To help speed it up, the makefile variable @var{CPU_COUNT} may be set
in @file{local.make} or on the command line to the number of
@code{.ly} files that LilyPond should process simultaneously, e.g. on
a bi-processor or dual core machine

@example
make -j3 CPU_COUNT=3 doc
@end example

@noindent
The recommended value of @var{CPU_COUNT} is one plus the number of
cores or processors, but it is advisable to set it to a smaller value
if your system has not enough RAM to run that many simultaneous
LilyPond instances.

If source files have changed since last documentation build, output
files that need to be rebuilt are normally rebuilt, even if you do not
run @code{make doc-clean} first.  However, building dependencies in the
documentation are so complex that rebuilding of some targets may not
be triggered as they should be; a workaround is to force rebuilding
by touching appropriate files, e.g.

@example
touch Documentation/extend.texi
touch Documentation/*te??
touch Documentation/snippets/*.te??
@end example


@node Building documentation without compiling LilyPond
@unnumberedsubsubsec Building documentation without compiling LilyPond

The documentation can be built locally without compiling LilyPond
binary, if LilyPond is already installed on your system.

From a fresh Git checkout, do

@example
./autogen.sh   # ignore any warning messages
cp GNUmakefile.in GNUmakefile
make -C scripts && make -C python
nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
@end example

Please note that this may break sometimes -- for example, if a new
feature is added with a test file in input/regression, even the latest
development release of LilyPond will fail to build the docs.

You may build the manual without building all the @file{input/*} stuff
(i.e. mostly regression tests): change directory, for example to
@file{Documentation/}, issue @code{make doc}, which will build
documentation in a subdirectory @file{out-www} from the source files in
current directory.  In this case, if you also want to browse the
documentation in its post-processed form, change back to top directory
and issue

@example
make out=www WWW-post
@end example

@knownissues

You may also need to create a script for @command{pngtopnm} and
@code{pnmtopng}.  On GNU/Linux, I use this:

@verbatim
export LD_LIBRARY_PATH=/usr/lib
exec /usr/bin/pngtopnm "$@"
@end verbatim

On MacOS X with fink, I use this:

@verbatim
export DYLD_LIBRARY_PATH=/sw/lib
exec /sw/bin/pngtopnm "$@"
@end verbatim

On MacOS X with macports, you should use this:

@verbatim
export DYLD_LIBRARY_PATH=/opt/local/lib
exec /opt/local/bin/pngtopnm "$@"
@end verbatim



@node Testing LilyPond
@subsection Testing LilyPond

@html
<a name="testing"></a>
@end html

LilyPond comes with an extensive suite that exercises the entire
program.  This suite can be used to automatically check the impact of a
change.  This is done as follows

@example
make test-baseline
@emph{## apply your changes, compile}
make check
@end example

This will leave an HTML page @file{out/test-results/index.html}.  This
page shows all the important differences that your change introduced,
whether in the layout, MIDI, performance or error reporting.

To rerun tests, use

@example
make test-redo           @emph{## redo files differing from baseline}
make test-clean          @emph{## remove all test results}
@end example

@noindent
and then run @code{make check} again.

For tracking memory usage as part of this test, you will need GUILE
CVS; especially the following patch:
@uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.

For checking the coverage of the test suite, do the following

@example
./scripts/auxiliar/build-coverage.sh
@emph{# uncovered files, least covered first}
./scripts/auxiliar/coverage.py  --summary out-cov/*.cc
@emph{# consecutive uncovered lines, longest first}
./scripts/auxiliar/coverage.py  --uncovered out-cov/*.cc
@end example


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

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

@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


@unnumberedsubsubsec Compiling on MacOS@tie{}X

Here are special instructions for compiling under MacOS@tie{}X.
These instructions assume that dependencies are installed using
@uref{http://www.macports.org/, MacPorts.} The instructions have
been tested using OS X 10.5 (Leopard).

First, install the relevant dependencies using MacPorts.

Next, add the following to your relevant shell initialization
files. This is @code{~/.profile} by default. You should create
this file if it does not exist.

@example
export PATH=/opt/local/bin:/opt/local/sbin:$PATH
export DYLD_LIBRARY_PATH=/System/Library/Frameworks/ApplicationServices.framework/Versions/A/Frameworks/ImageIO.framework/Versions/A/Resources:\
/opt/local/lib:$DYLD_LIBRARY_PATH
@end example

Now you must edit the generated @code{config.make} file.  Change

@example
FLEXLEXER_FILE = /usr/include/FlexLexer.h
@end example

@noindent
to:

@example
FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
@end example

At this point, you should verify that you have the appropriate
fonts installed with your ghostscript installation. Check @code{ls
/opt/local/share/ghostscript/fonts} for: 'c0590*' files (.pfb,
.pfb and .afm).  If you don't have them, run the following
commands to grab them from the ghostscript SVN server and install
them in the appropriate location:

@example
svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
rm -rf urw-fonts-1.07pre44
@end example

Now run the @code{./configure} script. To avoid complications with
automatic font detection, add

@example
--with-ncsb-dir=/opt/local/share/ghostscript/fonts
@end example


@unnumberedsubsubsec Solaris

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

@example
CONFIG_SHELL=/bin/ksh ksh -c ./configure
@end example

@noindent
or

@example
CONFIG_SHELL=/bin/bash bash -c ./configure
@end example

@unnumberedsubsubsec FreeBSD

To use system fonts, dejaview must be installed.  With the default
port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.

Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
following line just after the @code{<fontconfig>} line.  (Adjust as necessary
for your hierarchy.)

@example
<dir>/usr/X11R6/lib/X11/fonts</dir>
@end example


@unnumberedsubsubsec International fonts

On Mac OS X, all fonts are installed by default.  However, finding all
system fonts requires a bit of configuration; see
@uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
this post} on the @code{lilypond-user} mailing list.

On Linux, international fonts are installed by different means on
every distribution.  We cannot list the exact commands or packages
that are necessary, as each distribution is different, and the exact
package names within each distribution changes.  Here are some
hints, though:

@verbatim
Red Hat Fedora

    taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
         ttfonts-zh_CN fonts-ja fonts-hebrew

Debian GNU/Linux

   apt-get install emacs-intl-fonts xfonts-intl-.* \
        ttf-kochi-gothic ttf-kochi-mincho \
        xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
@end verbatim


@unnumberedsubsubsec Using lilypond python libraries

If you want to use lilypond's python libraries (either running
certain build scripts manually, or using them in other programs),
set @code{PYTHONPATH} to @file{python/out} in your build
directory, or @file{.../usr/lib/lilypond/current/python} in the
installation directory structure.