*****************
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'
+1 Compilation
+ 1.1 Overview of compiling
+ 1.2 Requirements
+ 1.2.1 Requirements for running LilyPond
+ 1.2.2 Requirements for compiling LilyPond
+ Fedora
+ Linux Mint
+ OpenSUSE
+ Ubuntu
+ Other
+ 1.2.3 Requirements for building documentation
+ 1.3 Getting the source code
+ 1.4 Configuring `make'
+ 1.4.1 Running `./autogen.sh'
+ 1.4.2 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
+ 1.5 Compiling LilyPond
+ 1.5.1 Using `make'
+ 1.5.2 Saving time with the `-j' option
+ 1.5.3 Compiling for multiple platforms
+ 1.5.4 Useful `make' variables
+ 1.6 Post-compilation options
+ 1.6.1 Installing LilyPond from a local build
+ 1.6.2 Generating documentation
Documentation editor's edit/compile cycle
Building documentation
Building a single document
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
+ 1.6.3 Testing LilyPond binary
+ 1.7 Problems
+ Compiling on MacOS X
+ Solaris
+ FreeBSD
+ International fonts
+ Using lilypond python libraries
+ 1.8 Concurrent stable and development versions
+ 1.9 Build system
-Overview of compiling
-=====================
+1 Compilation
+*************
+
+1.1 Overview of compiling
+=========================
Compiling LilyPond from source is an involved process, and is only
recommended for developers and packagers. Typical program users are
unsuccessful, though a workaround is available (see *note LilyDev:
(lilypond-contributor)LilyDev.).
-Requirements
-============
+1.2 Requirements
+================
-Requirements for running LilyPond
----------------------------------
+1.2.1 Requirements for running LilyPond
+---------------------------------------
-Running LilyPond requires proper installation of the following software:
+This section contains the list of separate software packages that are
+required to run LilyPond.
- * DejaVu fonts (http://www.dejavu-fonts.org/) (normally installed by
- default)
+ * DejaVu fonts (http://www.dejavu-fonts.org/) These are normally
+ installed by default.
- * FontConfig (http://www.fontconfig.org/) (2.4.0 or newer)
+ * FontConfig (http://www.fontconfig.org/) Use version 2.4.0 or newer.
- * Freetype (http://www.freetype.org/) (2.1.10 or newer)
+ * Freetype (http://www.freetype.org/) Use version 2.1.10 or newer.
- * Ghostscript (http://www.ghostscript.com) (8.60 or newer)
+ * Ghostscript (http://www.ghostscript.com) Use version 8.60 or newer.
- * Guile (http://www.gnu.org/software/guile/guile.html) (1.8.2 or
- newer)
+ * Guile (http://www.gnu.org/software/guile/guile.html) Use version
+ 1.8.8. Version 2.x of Guile is not currently supported.
- * Pango (http://www.pango.org/) (1.12 or newer)
+ * Pango (http://www.pango.org/) User version 1.12 or newer.
- * Python (http://www.python.org) (2.4 or newer)
+ * Python (http://www.python.org) Use version 2.4 or newer.
- International fonts are required to create music with international
-text or lyrics.
+ * International fonts. For example:
-Requirements for compiling LilyPond
------------------------------------
+ Fedora:
-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:
+ fonts-arabic
+ fonts-hebrew
+ fonts-ja
+ fonts-xorg-truetype
+ taipeifonts
+ ttfonts-ja
+ ttfonts-zh_CN
-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'
+ Debian based distributions:
- * Everything listed in *note Requirements for running LilyPond::
+ emacs-intl-fonts
+ fonts-ipafont-gothic
+ fonts-ipafont-mincho
+ xfonts-bolkhov-75dpi
+ xfonts-cronyx-75dpi
+ xfonts-cronyx-100dpi
+ xfonts-intl-.*
- * Development packages for the above items (which should include
- header files and libraries).
+ These are normally installed by default and are required only to
+ create music with international text or lyrics.
- Red Hat Fedora:
- guile-devel-VERSION
- fontconfig-devel-VERSION
- freetype-devel-VERSION
- pango-devel-VERSION
- python-devel-VERSION
+1.2.2 Requirements for compiling LilyPond
+-----------------------------------------
- Debian GNU/Linux:
+This section contains instructions on how to quickly and easily get all
+the software packages required to build LilyPond.
- guile-VERSION-dev
- libfontconfig1-dev
- libfreetype6-dev
- libpango1.0-dev
- pythonVERSION-dev
+ Most of the more popular Linux distributions only require a few
+simple commands to download all the software needed. For others, there
+is an explicit list of all the individual packages (as well as where to
+get them from) for those that are not already included in your
+distributions' own repositories.
- * Flex (http://flex.sourceforge.net/)
+Fedora
+......
+
+The following instructions were tested on `Fedora' versions 22 & 23 and
+will download all the software required to both compile LilyPond and
+build the documentation.
+
+ * Download and install all the LilyPond build-dependencies
+ (approximately 700MB);
+
+ sudo dnf builddep lilypond --nogpgcheck
+
+ * Download and install additional `build' tools required for
+ compiling;
+
+ sudo dnf install autoconf gcc-c++
+
+ * Download `texi2html 1.82' directly from:
+ `http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz';
+
+ `texi2html' is only required if you intend to compile LilyPond's
+ own documentation (e.g. to help with any document writing). The
+ version available in the Fedora repositories is too new and will
+ not work. Extract the files into an appropriate location and then
+ run the commands;
+
+ ./configure
+ make
+ sudo make install
+
+ This should install `texi2html 1.82' into `/usr/local/bin', which
+ will normally take priority over `/usr/bin' where the later,
+ pre-installed versions gets put. Now verify that your operating
+ system is able to see the correct version of `texi2html'.
+
+ texi2html --version
+
+ * Although not `required' to compile LilyPond, if you intend to
+ contribute to LilyPond (codebase or help improve the
+ documentation) then it is recommended that you also need to
+ install `git'.
+
+ sudo dnf install git
+
+ Also see *note Starting with Git: (lilypond-notation)Starting with
+ Git.
+
+ * To use the `lily-git.tcl' GUI;
+
+ sudo dnf install tk
+
+ See *note lily-git: (lilypond-notation)lily-git.
+
+
+ Note: By default, when building LilyPond's documentation,
+ `pdfTeX' is be used. However ligatures (fi, fl, ff etc.) may
+ not be printed in the PDF output. In this case XeTeX can be
+ used instead. Download and install the `texlive-xetex'
+ package.
+
+ sudo dnf install texlive-xetex
+
+ The scripts used to build the LilyPond documentation will use
+ `XeTex' instead of `pdfTex' to generate the PDF documents if
+ it is available. No additional configuration is required.
+
+Linux Mint
+..........
+
+The following instructions were tested on `Linux Mint 17.1' and `LMDE -
+Betsy' and will download all the software required to both compile
+LilyPond and build the documentation..
+
+ * Enable the _sources_ repository;
+
+ 1. Using the _Software Sources_ GUI (located under
+ _Administration_).
+
+ 2. Select _Official Repositories_.
+
+ 3. Check the _Enable source code repositories_ box under the
+ _Source Code_ section.
+
+ 4. Click the _Update the cache_ button and when it has completed,
+ close the _Software Sources_ GUI.
+
+
+ * Download and install all the LilyPond build-dependencies
+ (approximately 200MB);
+
+ sudo apt-get build-dep lilypond
+
+ * Download and install additional `build' tools required for
+ compiling;
+
+ sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
+
+ * Although not `required' to compile LilyPond, if you intend to
+ contribute to LilyPond (codebase or help improve the
+ documentation) then it is recommended that you also need to
+ install `git'.
+
+ sudo apt-get install git
+
+ Also see *note Starting with Git: (lilypond-notation)Starting with
+ Git.
+
+ * To use the `lily-git.tcl' GUI;
+
+ sudo apt-get install tk
+
+ Also see *note lily-git: (lilypond-notation)lily-git.
+
+
+ Note: By default, when building LilyPond's documentation,
+ `pdfTeX' is be used. However ligatures (fi, fl, ff etc.) may
+ not be printed in the PDF output. In this case XeTeX can be
+ used instead. Download and install the `texlive-xetex'
+ package.
+
+ sudo apt-get install texlive-xetex
+
+ The scripts used to build the LilyPond documentation will use
+ `XeTex' instead of `pdfTex' to generate the PDF documents if
+ it is available. No additional configuration is required.
+
+OpenSUSE
+........
+
+The following instructions were tested on `OpenSUSE 13.2' and will
+download all the software required to both compile LilyPond and build
+the documentation.
+
+ * Add the _sources_ repository;
+
+ sudo zypper addrepo -f \
+ "http://download.opensuse.org/source/distribution/13.2/repo/oss/" sources
+
+ * Download and install all the LilyPond build-dependencies
+ (approximately 680MB);
+
+ sudo zypper source-install lilypond
+
+ * Download and install additional `build' tools required for
+ compiling;
+
+ sudo zypper install make
+
+ * Although not `required' to compile LilyPond, if you intend to
+ contribute to LilyPond (codebase or help improve the
+ documentation) then it is recommended that you also need to
+ install `git'.
+
+ sudo zypper install git
+
+ Also see *note Starting with Git: (lilypond-notation)Starting with
+ Git.
+
+ * To use the `lily-git.tcl' GUI;
+
+ sudo zypper install tk
+
+ Also see *note lily-git: (lilypond-notation)lily-git.
- * 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.)
+
+ Note: By default, when building LilyPond's documentation,
+ `pdfTeX' is be used. However ligatures (fi, fl, ff etc.) may
+ not be printed in the PDF output. In this case XeTeX can be
+ used instead. Download and install the `texlive-xetex'
+ package.
+
+ sudo zypper install texlive-xetex
+
+ The scripts used to build the LilyPond documentation will use
+ `XeTex' instead of `pdfTex' to generate the PDF documents if
+ it is available. No additional configuration is required.
+
+Ubuntu
+......
+
+The following commands were tested on Ubuntu versions `14.04 LTS',
+`14.10' and `15.04' and will download all the software required to both
+compile LilyPond and build the documentation.
+
+ * Download and install all the LilyPond build-dependencies
+ (approximately 200MB);
+
+ sudo apt-get build-dep lilypond
+
+ * Download and install additional `build' tools required for
+ compiling;
+
+ sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
+
+ * Although not `required' to compile LilyPond, if you intend to
+ contribute to LilyPond (codebase or help improve the
+ documentation) then it is recommended that you also need to
+ install `git'.
+
+ sudo apt-get install git
+
+ Also see *note Starting with Git: (lilypond-notation)Starting with
+ Git.
+
+ * To use the `lily-git.tcl' GUI;
+
+ sudo apt-get install tk
+
+ Also see *note lily-git: (lilypond-notation)lily-git.
+
+
+ Note: By default, when building LilyPond's documentation,
+ `pdfTeX' is be used. However ligatures (fi, fl, ff etc.) may
+ not be printed in the PDF output. In this case XeTeX can be
+ used instead. Download and install the `texlive-xetex'
+ package.
+
+ sudo apt-get install texlive-xetex
+
+ The scripts used to build the LilyPond documentation will use
+ `XeTex' instead of `pdfTex' to generate the PDF documents if
+ it is available. No additional configuration is required.
+
+Other
+.....
+
+The following individual software packages are required just to compile
+LilyPond.
+
+ * GNU Autoconf (http://www.gnu.org/software/autoconf)
* GNU Bison (http://www.gnu.org/software/bison/)
- * GNU Compiler Collection (http://gcc.gnu.org/) (3.4 or newer, 4.X
- recommended)
+ Use version `2.0' or newer.
+
+ * GNU Compiler Collection (http://gcc.gnu.org/)
+
+ Use version `3.4' or newer (`4.x' recommended).
+
+ * Flex (http://flex.sourceforge.net/)
+
+ * FontForge (http://fontforge.sf.net/)
+
+ Use version `20060125' or newer (we recommend using at least
+ `20100501'); it must also be compiled with the `--enable-double'
+ switch, else this can lead to inaccurate intersection calculations
+ which end up with poorly-rendered glyphs in the output.
* 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)
+ Use version `0.17' 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).
+ * GNU Make (http://www.gnu.org/software/make/)
+
+ Use version `3.78' or newer.
+
+ * MetaFont (http://metafont.tutorial.free.fr/)
+
+ The `mf-nowin', `mf', `mfw' or `mfont' binaries are usually
+ packaged along with TeX (http://www.latex-project.org/ftp.html).
+
+ * MetaPost (http://cm.bell-labs.com/who/hobby/MetaPost.html)
- * MetaPost (http://cm.bell-labs.com/who/hobby/MetaPost.html) (mpost
- binary), usually packaged with TeX
+ The `mpost' binary is also 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)
+ * Texinfo (http://www.gnu.org/software/texinfo/)
+
+ Use version `4.11' or newer.
* Type 1 utilities (http://www.lcdf.org/~eddietwo/type/#t1utils)
- (1.33 or newer recommended)
-Requirements for building documentation
----------------------------------------
+ Use version `1.33' or newer.
+
+ * Cyrillic fonts (https://www.ctan.org/pkg/cyrillic?lang=en)
+
+ Often packaged in repositories as `texlive-lang-cyrillic'.
-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:
+ * TeX Gyre `OTF' font packages. As of LilyPond version `2.19.26',
+ the previous default serif, san serif and monospace fonts now use
+ Tex Gyre's _Schola_, _Heros_ and _Cursor_ fonts respectively.
+ Also See *note Fonts: (lilypond-notation)Fonts.
+
+ Some distributions do not always provide `OTF' font files in the
+ Tex Gyre packages from their repositories. Use the command
+ `fc-list | grep texgyre' to list the fonts available to your system
+ and check that the appropriate `*.otf' files are reported. If they
+ are not then download and manually extract the `OTF' files to
+ either your local `~/.fonts/' directory or use the `configure'
+ command and the `--with-texgyre-dir=/path_to_otf_files/' option.
+
+ The following font families are required:
+
+ Schola (http://www.gust.org.pl/projects/e-foundry/tex-gyre/schola),
+ Heros (http://www.gust.org.pl/projects/e-foundry/tex-gyre/heros)
+ and Cursor
+ (http://www.gust.org.pl/projects/e-foundry/tex-gyre/cursor).
+
+
+1.2.3 Requirements for building documentation
+---------------------------------------------
+
+The entire set of documentation for the most current build of LilyPond
+is available online at
+`http://lilypond.org/doc/v2.19/Documentation/web/development', but you
+can also build them locally from the source code. This process
+requires some additional tools and packages.
+
+ Note: If the instructions for one of the previously listed
+ Linux in the previous section (*note Requirements for
+ compiling LilyPond: (lilypond-contributor)Requirements for
+ compiling LilyPond.) have been used, then the following can
+ be ignored as the software should already be installed.
* Everything listed in *note Requirements for compiling LilyPond::
* rsync (http://rsync.samba.org/)
- * Texi2HTML (http://www.nongnu.org/texi2html/) (1.82)
+ * Texi2HTML (http://www.nongnu.org/texi2html/)
- * International fonts
+ Use version `1.82'. Later versions will not work.
- Red Hat Fedora:
+ Download `texi2html 1.82' directly from:
+ `http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz';
- fonts-arabic
- fonts-hebrew
- fonts-ja
- fonts-xorg-truetype
- taipeifonts
- ttfonts-ja
- ttfonts-zh_CN
+ Extract the files into an appropriate location and then run the
+ commands;
- Debian GNU/Linux:
+ ./configure
+ make
+ sudo make install
+
+ Now verify that your operating system is able to see the correct
+ version of `texi2html'.
+
+ texi2html --version
+
+ * Fonts required to build the documentation in addition to those
+ required to run LilyPond:
+
+ gsfonts
+ fonts-linuxlibertine
+ fonts-liberation
+ fonts-dejavu
+ fonts-freefont-otf
+ ttf-bitstream-vera
+ texlive-fonts-recommended
+ ttf-xfree86-nonfree
- emacs-intl-fonts
- ttf-kochi-gothic
- ttf-kochi-mincho
- xfonts-bolkhov-75dpi
- xfonts-cronyx-75dpi
- xfonts-cronyx-100dpi
- xfonts-intl-.*
-Getting the source code
-=======================
+ Note: By default, when building LilyPond's documentation,
+ `pdfTeX' is be used. However ligatures (fi, fl, ff etc.) may
+ not be printed in the PDF output. In this case XeTeX can be
+ used instead. Download and install the `texlive-xetex'
+ package. The scripts used to build the LilyPond documentation
+ will use `XeTex' instead of `pdfTex' to generate the PDF
+ documents if it is available. No additional configuration is
+ required.
+
+1.3 Getting the source code
+===========================
Downloading the Git repository
------------------------------
download and install the free-software 7zip archiver
(http://www.7-zip.org) to extract the tarball.
-Configuring `make'
-==================
+1.4 Configuring `make'
+======================
-Running `./autogen.sh'
-----------------------
+1.4.1 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
We heavily recommend building lilypond inside a separate directory
with this method.
-Running `../configure'
-----------------------
+1.4.2 Running `../configure'
+----------------------------
Configuration options
.....................
If you encounter any problems, please see *note Problems::.
-Compiling LilyPond
-==================
+1.5 Compiling LilyPond
+======================
-Using `make'
-------------
+1.5.1 Using `make'
+------------------
Note: make sure that you are in the `build/' subdirectory of
your source tree.
*note Generating documentation:: provides more info on the `make'
targets used to build the LilyPond documentation.
-Saving time with the `-j' option
---------------------------------
+1.5.2 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
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
---------------------------------
+1.5.3 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
*note Installing LilyPond from a local build::
-Useful `make' variables
------------------------
+1.5.4 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
-========================
+1.6 Post-compilation options
+============================
-Installing LilyPond from a local build
---------------------------------------
+1.6.1 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),
the installation directory to one that you can write to, and then
re-install. See *note Configuring target directories::.
-Generating documentation
-------------------------
+1.6.2 Generating documentation
+------------------------------
Documentation editor's edit/compile cycle
.........................................
export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
exec /opt/local/bin/pngtopnm "$@"
-Testing LilyPond binary
------------------------
+1.6.3 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
More information on the regression test suite is found at *note
Regression tests: (lilypond-contributor)Regression tests.
-Problems
-========
+1.7 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.
Now run the `./configure' script. To avoid complications with
automatic font detection, add
- --with-ncsb-dir=/opt/local/share/ghostscript/fonts
+ --with-fonts-dir=/opt/local/share/ghostscript/fonts
Solaris
-.......
+-------
Solaris7, ./configure
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'.
<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
Debian GNU/Linux
apt-get install emacs-intl-fonts xfonts-intl-.* \
- ttf-kochi-gothic ttf-kochi-mincho \
+ fonts-ipafont-gothic fonts-ipafont-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
`.../usr/lib/lilypond/current/python' in the installation directory
structure.
-Concurrent stable and development versions
-==========================================
+1.8 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
- other compilation tricks for developers
-Build system
-============
+1.9 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'
projects / lilypond.git / blobdiff