INSTALL - compiling and installing GNU LilyPond
***********************************************

Table of Contents
*****************

INSTALL - compiling and installing GNU LilyPond
  Overview of compiling
  Requirements
    Requirements for running LilyPond
    Requirements for compiling LilyPond
    Requirements for building documentation
  Getting the source code
  Configuring `make'
    Running `./autogen.sh'
    Running `../configure'
      Configuration options
      Checking build dependencies
      Configuring target directories
  Compiling LilyPond
    Using `make'
    Saving time with the `-j' option
    Compiling for multiple platforms
    Useful `make' variables
  Post-compilation options
    Installing LilyPond from a local build
    Generating documentation
      Documentation editor's edit/compile cycle
      Building documentation
      Saving time with `CPU_COUNT'
      AJAX search
      Installing documentation
      Building documentation without compiling
    Testing LilyPond binary
  Problems
      Bison 1.875
      Compiling on MacOS X
      Solaris
      FreeBSD
      International fonts
      Using lilypond python libraries
  Concurrent stable and development versions
  Build system


Overview of compiling
=====================

Compiling LilyPond from source is an involved process, and is only
recommended for developers and packagers.  Typical program users are
instead encouraged to obtain the program from a package manager (on
Unix) or by downloading a precompiled binary configured for a specific
operating system.  Pre-compiled binaries are available on the *note
Download: (lilypond-web)Download. page.

   Compiling LilyPond from source is necessary if you want to build,
install, or test your own version of the program.

   A successful compile can also be used to generate and install the
documentation, incorporating any changes you may have made.  However, a
successful compile is not a requirement for generating the
documentation.  The documentation can be built using a Git repository
in conjunction with a locally installed copy of the program.  For more
information, see *note Building documentation without compiling::.

   Attempts to compile LilyPond natively on Windows have been
unsuccessful, though a workaround is available (see *note Lilydev:
(lilypond-contributor)Lilydev.).

Requirements
============

Requirements for running LilyPond
---------------------------------

Running LilyPond requires proper installation of the following software:

   * DejaVu fonts (http://www.dejavu-fonts.org/) (normally installed by
     default)

   * FontConfig (http://www.fontconfig.org/) (2.4.0 or newer)

   * Freetype (http://www.freetype.org/) (2.1.10 or newer)

   * Ghostscript (http://www.ghostscript.com) (8.60 or newer)

   * Guile (http://www.gnu.org/software/guile/guile.html) (1.8.2 or
     newer)

   * Pango (http://www.pango.org/) (1.12 or newer)

   * Python (http://www.python.org) (2.4 or newer)

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

Requirements for compiling LilyPond
-----------------------------------

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:

Distribution                         Command
-------------------------------------------------------------------------- 
Debian, Ubuntu                       `sudo apt-get build-dep lilypond'
Fedora, RHEL                         `sudo yum-builddep lilypond'
openSUSE, SLED                       `sudo zypper --build-deps-only
                                     source-install lilypond'

   * Everything listed in *note Requirements for running LilyPond::

   * Development packages for the above items (which should include
     header files and libraries).

     Red Hat Fedora:

          guile-devel-VERSION
          fontconfig-devel-VERSION
          freetype-devel-VERSION
          pango-devel-VERSION
          python-devel-VERSION

     Debian GNU/Linux:

          guile-VERSION-dev
          libfontconfig1-dev
          libfreetype6-dev
          libpango1.0-dev
          pythonVERSION-dev

   * Flex (http://flex.sourceforge.net/)

   * FontForge (http://fontforge.sf.net/) (20060125 or newer; 20100501
     or newer is recommended; must be compiled with `--enable-double'.
     Failure to do so can lead to poor intersection calculations and
     poorly-rendered glyphs.)

   * GNU Bison (http://www.gnu.org/software/bison/)

   * GNU Compiler Collection (http://gcc.gnu.org/) (3.4 or newer, 4.X
     recommended)

   * GNU gettext (http://www.gnu.org/software/gettext/gettext.html)
     (0.17 or newer)

   * GNU Make (http://www.gnu.org/software/make/) (3.78 or newer)

   * MetaFont (http://metafont.tutorial.free.fr/) (mf-nowin, mf, mfw or
     mfont binaries), usually packaged with TeX
     (http://www.latex-project.org/ftp.html).

   * MetaPost (http://cm.bell-labs.com/who/hobby/MetaPost.html) (mpost
     binary), usually packaged with TeX
     (http://www.latex-project.org/ftp.html).

   * Perl (http://www.perl.org/)

   * Texinfo (http://www.gnu.org/software/texinfo/) (4.11 or newer)

   * Type 1 utilities (http://www.lcdf.org/~eddietwo/type/#t1utils)
     (1.33 or newer recommended)

Requirements for building documentation
---------------------------------------

You can view the documentation online at
`http://www.lilypond.org/doc/', but you can also build it locally.
This process requires some additional tools and packages:

   * Everything listed in *note Requirements for compiling LilyPond::

   * ImageMagick (http://www.imagemagick.org/)

   * Netpbm (http://netpbm.sourceforge.net/)

   * gzip (http://gzip.org/)

   * rsync (http://rsync.samba.org/)

   * Texi2HTML (http://www.nongnu.org/texi2html/) (1.82)

   * International fonts

     Red Hat Fedora:

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

     Debian GNU/Linux:

          emacs-intl-fonts
          ttf-kochi-gothic
          ttf-kochi-mincho
          xfonts-bolkhov-75dpi
          xfonts-cronyx-75dpi
          xfonts-cronyx-100dpi
          xfonts-intl-.*

Getting the source code
=======================

Downloading the Git repository
------------------------------

In general, developers compile LilyPond from within a local Git
repository.  Setting up a local Git repository is explained in *note
Starting with Git: (lilypond-contributor)Starting with Git.

Downloading a source tarball
----------------------------

Packagers are encouraged to use source tarballs for compiling.

   The tarball for the latest stable release is available on the *note
Source: (lilypond-web)Source. page.

The latest source code snapshot
(http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot) is also
available as a tarball from the GNU Savannah Git server.

All tagged releases (including legacy stable versions and the most
recent development release) are available here:

     `http://download.linuxaudio.org/lilypond/source/'

   Download the tarball to your `~/src/' directory, or some other
appropriate place.

          Note: Be careful where you unpack the tarball!  Any
          subdirectories of the current folder named `lilypond/' or
          `lilypond-X.Y.Z/' (where X.Y.Z is the release number) will be
          overwritten if there is a name clash with the tarball.

   Unpack the tarball with this command:

     tar -xzf lilypond-X.Y.Z.tar.gz

   This creates a subdirectory within the current directory called
`lilypond-X.Y.Z/'.  Once unpacked, the source files occupy about 40 MB
of disk space.

   Windows users wanting to look at the source code may have to
download and install the free-software 7zip archiver
(http://www.7-zip.org) to extract the tarball.

Configuring `make'
==================

Running `./autogen.sh'
----------------------

After you unpack the tarball (or download the Git repository), the
contents of your top source directory should be similar to the current
source tree listed at
`http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree'.

   Next, you need to create the generated files; enter the following
command from your top source directory:

     ./autogen.sh --noconfigure

   This will generate a number of files and directories to aid
configuration, such as `configure', `README.txt', etc.

   Next, create the build directory with:

     mkdir build/
     cd build/

   We heavily recommend building lilypond inside a separate directory
with this method.

Running `../configure'
----------------------

Configuration options
.....................

          Note: make sure that you are in the `build/' subdirectory of
          your source tree.

The `../configure' command (generated by `./autogen.sh') provides many
options for configuring `make'.  To see them all, run:

     ../configure --help

Checking build dependencies
...........................

          Note: make sure that you are in the `build/' subdirectory of
          your source tree.

When `../configure' is run without any arguments, it will check to make
sure your system has everything required for compilation:

     ../configure

   If any build dependency is missing, `../configure' will return with:

     ERROR: Please install required programs:  FOO

   The following message is issued if you are missing programs that are
only needed for building the documentation:

     WARNING: Please consider installing optional programs:  BAR

   If you intend to build the documentation locally, you will need to
install or update these programs accordingly.

          Note: `../configure' may fail to issue warnings for certain
          documentation build requirements that are not met.  If you
          experience problems when building the documentation, you may
          need to do a manual check of *note Requirements for building
          documentation::.

Configuring target directories
..............................

          Note: make sure that you are in the `build/' subdirectory of
          your source tree.

If you intend to use your local build to install a local copy of the
program, you will probably want to configure the installation
directory.  Here are the relevant lines taken from the output of
`../configure --help':

     By default, ``make install'' will install all the files in
     `/usr/local/bin', `/usr/local/lib' etc.  You can specify an
     installation prefix other than `/usr/local' using ``--prefix'',
     for instance ``--prefix=$HOME''.

   A typical installation prefix is `$HOME/usr':

     ../configure --prefix=$HOME/usr

   Note that if you plan to install a local build on a system where you
do not have root privileges, you will need to do something like this
anyway--`make install' will only succeed if the installation prefix
points to a directory where you have write permission (such as your
home directory).  The installation directory will be automatically
created if necessary.

   The location of the `lilypond' command installed by this process
will be `PREFIX/bin/lilypond'; you may want to add `PREFIX/bin/' to
your `$PATH' if it is not already included.

   It is also possible to specify separate installation directories for
different types of program files.  See the full output of
`../configure --help' for more information.

   If you encounter any problems, please see *note Problems::.

Compiling LilyPond
==================

Using `make'
------------

          Note: make sure that you are in the `build/' subdirectory of
          your source tree.

LilyPond is compiled with the `make' command.  Assuming `make' is
configured properly, you can simply run:

     make

   `make' is short for `make all'.  To view a list of `make' targets,
run:

     make help

   TODO: Describe what `make' actually does.

Saving time with the `-j' option
--------------------------------

If your system has multiple CPUs, you can speed up compilation by
adding `-jX' to the `make' command, where `X' is one more than the
number of cores you have.  For example, a typical Core2Duo machine
would use:

     make -j3

   If you get errors using the `-j' option, and `make' succeeds without
it, try lowering the `X' value.

   Because multiple jobs run in parallel when `-j' is used, it can be
difficult to determine the source of an error when one occurs.  In that
case, running `make' without the `-j' is advised.

Compiling for multiple platforms
--------------------------------

If you want to build multiple versions of LilyPond with different
configuration settings, you can use the `--enable-config=CONF' option
of `configure'.  You should use `make conf=CONF' to generate the output
in `out-CONF'.  For example, suppose you want to build with and without
profiling, then use the following for the normal build

     ./configure --prefix=$HOME/usr/ --enable-checking
     make

   and for the profiling version, specify a different configuration

     ./configure --prefix=$HOME/usr/ --enable-profiling \
       --enable-config=prof --disable-checking
     make conf=prof

   If you wish to install a copy of the build with profiling, don't
forget to use `conf=CONF' when issuing `make install':

     make conf=prof install


See also
........



   *note Installing LilyPond from a local build::

Useful `make' variables
-----------------------

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

Post-compilation options
========================

Installing LilyPond from a local build
--------------------------------------

If you configured `make' to install your local build in a directory
where you normally have write permission (such as your home directory),
and you have compiled LilyPond by running `make', you can install the
program in your target directory by running:

     make install

   If instead, your installation directory is not one that you can
normally write to (such as the default `/usr/local/', which typically
is only writeable by the superuser), you will need to temporarily
become the superuser when running `make install':

     sudo make install

or...

     su -c 'make install'

   If you don't have superuser privileges, then you need to configure
the installation directory to one that you can write to, and then
re-install.  See *note Configuring target directories::.

Generating documentation
------------------------

Documentation editor's edit/compile cycle
.........................................

   * Initial documentation build:

          make [-jX]
          make [-jX CPU_COUNT=X] doc  _## can take an hour or more_

   * Edit/compile cycle:

          _## edit source files, then..._

          make [-jX]                  _## needed if editing outside_
                                      _##   Documentation/, but useful anyway_
                                      _##   for finding Texinfo errors._
          touch Documentation/*te??   _## bug workaround_
          make [-jX CPU_COUNT=X] doc  _## usually faster than initial build._

   * Reset:

     In some cases, it is possible to clean the compiled documentation
     with `make doc-clean', but this method is not guaranteed to fix
     everything.  Instead, we recommend that you delete your `build/'
     directory, and begin compiling from scratch.  Since the
     documentation compile takes much longer than the non-documentation
     compile, this does not increase the overall time by a great deal.


Building documentation
......................

After a successful compile (using `make'), the documentation can be
built by issuing:

     make doc

   The first time you run `make doc', the process can easily take an
hour or more.  After that, `make doc' only makes changes to the
pre-built documentation where needed, so it may only take a minute or
two to test changes if the documentation is already built.

   If `make doc' succeeds, the HTML documentation tree is available in
`out-www/offline-root/', and can be browsed locally.  Various portions
of the documentation can be found by looking in `out/' and `out-www'
subdirectories in other places in the source tree, but these are only
_portions_ of the docs.  Please do not complain about anything which is
broken in those places; the only complete set of documentation is in
`out-www/offline-root/' from the top of the source tree.

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

     make info


Known issues and warnings
.........................

If source files have changed since the last documentation build, output
files that need to be rebuilt are normally rebuilt, even if you do not
run `make doc-clean' first.  However, build dependencies in the
documentation are so complex that some newly-edited files may not be
rebuilt as they should be; a workaround is to `touch' the top source
file for any manual you've edited.  For example, if you make changes to
a file in `notation/', do:

     touch Documentation/notation.tely

The top sources possibly affected by this are:

     Documentation/extend.texi
     Documentation/changes.tely
     Documentation/contributor.texi
     Documentation/essay.tely
     Documentation/extending.tely
     Documentation/learning.tely
     Documentation/notation.tely
     Documentation/snippets.tely
     Documentation/usage.tely
     Documentation/web.texi

You can `touch' all of them at once with:

     touch Documentation/*te??

However, this will rebuild all of the manuals indiscriminately--it is
more efficient to `touch' only the affected files.

Saving time with `CPU_COUNT'
............................

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

     make -j3 CPU_COUNT=3 doc

The recommended value of `CPU_COUNT' is one plus the number of cores or
processors, but it is advisable to set it to a smaller value unless
your system has enough RAM to run that many simultaneous LilyPond
instances.  Also, values for the `-j' option that pose problems with
`make' are less likely to pose problems with `make doc' (this applies
to both `-j' and `CPU_COUNT').  For example, with a quad-core processor,
it is possible for `make -j5 CPU_COUNT=5 doc' to work consistently even
if `make -j5' rarely succeeds.

AJAX search
...........

To build the documentation with interactive searching, use:

     make doc AJAX_SEARCH=1

   This requires PHP, and you must view the docs via a http connection
(you cannot view them on your local filesystem).

          Note: Due to potential security or load issues, this option is
          not enabled in the official documentation builds.  Enable at
          your own risk.

Installing documentation
........................

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

     make install-doc

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.

   To install the Info documentation separately, run:

     make install-info

Note that to get the images in Info documentation, `install-doc' target
creates symbolic links to HTML and PDF installed documentation tree in
`PREFIX/share/info', in order to save disk space, whereas
`install-info' copies images in `PREFIX/share/info' subdirectories.

   It is possible to build a documentation tree in
`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

     make WEB_TARGETS=online doc

and both `offline' and `online' targets can be generated by issuing

     make WEB_TARGETS="offline online" doc

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

     make help

from every directory in the build tree.  Most targets for documentation
maintenance are available from `Documentation/'; for more information,
see *note Documentation work: (lilypond-contributor)Documentation work.

   The makefile variable `QUIET_BUILD' may be set to `1' for a less
verbose build output, just like for building the programs.

Building documentation without compiling
........................................

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

   From a fresh Git checkout, do

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

   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 `input/*' stuff
(i.e. mostly regression tests): change directory, for example to
`Documentation/', issue `make doc', which will build documentation in a
subdirectory `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

     make out=www WWW-post


Known issues and warnings
.........................

You may also need to create a script for `pngtopnm' and `pnmtopng'.  On
GNU/Linux, I use this:

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

   On MacOS X with fink, I use this:

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

   On MacOS X with macports, you should use this:

export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
exec /opt/local/bin/pngtopnm "$@"

Testing LilyPond binary
-----------------------

LilyPond comes with an extensive suite that exercises the entire
program.  This suite can be used to test that the binary has been built
correctly.

   The test suite can be executed with:

make test

   If the test suite completes successfully, the LilyPond binary has
been verified.

   More information on the regression test suite is found at *note
Regression tests: (lilypond-contributor)Regression tests.

Problems
========

For help and questions use <lilypond-user@gnu.org>.  Send bug reports
to <bug-lilypond@gnu.org>.

   Bugs that are not fault of LilyPond are documented here.

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

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

Compiling on MacOS X
....................

Here are special instructions for compiling under MacOS X.  These
instructions assume that dependencies are installed using MacPorts.
(http://www.macports.org/) 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 `~/.profile' by default.  You should create this file if it
does not exist.

     export PATH=/opt/local/bin:/opt/local/sbin:$PATH
     export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH

   Now you must edit the generated `config.make' file.  Change

     FLEXLEXER_FILE = /usr/include/FlexLexer.h

to:

     FLEXLEXER_FILE = /opt/local/include/FlexLexer.h

   At this point, you should verify that you have the appropriate fonts
installed with your ghostscript installation.  Check `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:

     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

   Now run the `./configure' script.  To avoid complications with
automatic font detection, add

     --with-ncsb-dir=/opt/local/share/ghostscript/fonts

Solaris
.......

Solaris7, ./configure

   `./configure' needs a POSIX compliant shell.  On Solaris7, `/bin/sh'
is not yet POSIX compliant, but `/bin/ksh' or bash is.  Run configure
like

     CONFIG_SHELL=/bin/ksh ksh -c ./configure

or

     CONFIG_SHELL=/bin/bash bash -c ./configure

FreeBSD
.......

To use system fonts, dejaview must be installed.  With the default
port, the fonts are installed in `usr/X11R6/lib/X11/fonts/dejavu'.

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

     <dir>/usr/X11R6/lib/X11/fonts</dir>

International fonts
...................

On Mac OS X, all fonts are installed by default.  However, finding all
system fonts requires a bit of configuration; see this post
(http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
on the `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:

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

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
`PYTHONPATH' to `python/out' in your build directory, or
`.../usr/lib/lilypond/current/python' in the installation directory
structure.

Concurrent stable and development versions
==========================================

It can be useful to have both the stable and the development versions
of Lilypond available at once.  One way to do this on GNU/Linux is to
install the stable version using the precompiled binary, and run the
development version from the source tree.  After running `make all'
from the top directory of the Lilypond source files, there will be a
binary called `lilypond' in the `out' directory:

     <PATH TO>/lilypond/out/bin/lilypond

   This binary can be run without actually doing the `make install'
command.  The advantage to this is that you can have all of the latest
changes available after pulling from git and running `make all',
without having to uninstall the old version and reinstall the new.

   So, to use the stable version, install it as usual and use the
normal commands:

     lilypond foobar.ly

   To use the development version, create a link to the binary in the
source tree by saving the following line in a file somewhere in your
`$PATH':

     exec <PATH TO>/lilypond/out/bin/lilypond "$@"

   Save it as `Lilypond' (with a capital L to distinguish it from the
stable `lilypond'), and make it executable:

     chmod +x Lilypond

   Then you can invoke the development version this way:

     Lilypond foobar.ly

   TODO: ADD

   - other compilation tricks for developers

Build system
============

We currently use make and stepmake, which is complicated and only used
by us.  Hopefully this will change in the future.

Version-specific texinfo macros
...............................

   * made with `scripts/build/create-version-itexi.py' and
     `scripts/build/create-weblinks-itexi.py'

   * used extensively in the `WEBSITE_ONLY_BUILD' version of the
     website (made with `website.make', used on lilypond.org)

   * not (?) used in the main docs?

   * the numbers in VERSION file: MINOR_VERSION should be 1 more than
     the last release, VERSION_DEVEL should be the last *online*
     release.  Yes, VERSION_DEVEL is less than VERSION.


