@c @n ode Compiling from source
@c @s ection Compiling from source
-
@menu
* Overview of compiling::
* Requirements::
* Getting the source code::
-* Configuring @command{make}::
+* Configuring make::
* Compiling LilyPond::
* Post-compilation options::
* Problems::
* Concurrent stable and development versions::
-* Using a Virtual Machine to Compile LilyPond::
* Build system::
@end menu
without compiling}.
Attempts to compile LilyPond natively on Windows have been
-unsuccessful, though a workaround is available (see @ref{Using a
-Virtual Machine to Compile LilyPond}).
+unsuccessful, though a workaround is available (see
+@rcontrib{Lilydev}).
@node Requirements
@item @uref{http://www.dejavu-fonts.org/, DejaVu fonts} (normally
installed by default)
-@item @uref{http://www.fontconfig.org/, FontConfig} (2.2 or newer)
+@item @uref{http://www.fontconfig.org/, FontConfig} (2.4.0 or newer)
@item @uref{http://www.freetype.org/, Freetype} (2.1.10 or newer)
@item @uref{http://flex.sourceforge.net/, Flex}
@item @uref{http://fontforge.sf.net/, FontForge} (20060125 or
-newer)
+newer; 20100501 or newer is recommended; must be compiled
+with @option{--enable-double}. Failure to do so can lead to
+poor intersection calculations and poorly-rendered glyphs.)
@item @uref{http://www.gnu.org/software/bison/, GNU Bison}
@item @uref{http://netpbm.sourceforge.net/, Netpbm}
+@item @uref{http://gzip.org/, gzip}
+
@item @uref{http://rsync.samba.org/, rsync}
@item @uref{http://www.nongnu.org/texi2html/, Texi2HTML} (1.82)
In general, developers compile LilyPond from within a local Git
repository. Setting up a local Git repository is explained in
-@ref{Starting with Git}.
+@rcontrib{Starting with Git}.
@subheading Downloading a source tarball
Packagers are encouraged to use source tarballs for compiling.
+
The tarball for the latest stable release is available on the
@rweb{Source} page.
+@noindent
+The latest
+@uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot, source code snapshot}
+is also available as a tarball from the GNU Savannah Git server.
+
@noindent
All tagged releases (including legacy stable
versions and the most recent development release) are available
@file{lilypond-@var{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
+@uref{http://www.7-zip.org, 7zip archiver} to extract the tarball.
-@node Configuring @command{make}
+
+@node Configuring make
@section Configuring @command{make}
@menu
-* Running @command{./autogen.sh}::
-* Running @command{./configure}::
+* Running ./autogen.sh::
+* Running ../configure::
@end menu
-@node Running @command{./autogen.sh}
+@node Running ./autogen.sh
@subsection Running @command{./autogen.sh}
After you unpack the tarball (or download the Git repository), the
command from your top source directory:
@example
-./autogen.sh
+./autogen.sh --noconfigure
@end example
-This will:
-
-@enumerate
-@item generate a number of files and directories to aid
+This will generate a number of files and directories to aid
configuration, such as @file{configure}, @file{README.txt}, etc.
-@item automatically run the @command{./configure} command.
-@end enumerate
+Next, create the build directory with:
+
+@example
+mkdir build/
+cd build/
+@end example
+
+We heavily recommend building lilypond inside a separate directory
+with this method.
-@node Running @command{./configure}
-@subsection Running @command{./configure}
+@node Running ../configure
+@subsection Running @command{../configure}
+
@menu
* Configuration options::
* Checking build dependencies::
* Configuring target directories::
-* Making an out-of-tree build::
@end menu
@node Configuration options
@unnumberedsubsubsec Configuration options
-The @command{./configure} command (generated by
+@warning{make sure that you are in the @file{build/} subdirectory
+of your source tree.}
+
+The @command{../configure} command (generated by
@command{./autogen.sh}) provides many options for configuring
@command{make}. To see them all, run:
@example
-./configure --help
+../configure --help
@end example
@node Checking build dependencies
@unnumberedsubsubsec Checking build dependencies
-When @command{./configure} is run without any arguments, it will
+@warning{make sure that you are in the @file{build/} subdirectory
+of your source tree.}
+
+When @command{../configure} is run without any arguments, it will
check to make sure your system has everything required for
-compilation. This is done automatically when
-@command{./autogen.sh} is run. If any build dependency is
-missing, @command{./configure} will return with:
+compilation:
+
+@example
+../configure
+@end example
+
+If any build dependency is missing, @command{../configure} will
+return with:
@example
ERROR: Please install required programs: @var{foo}
If you intend to build the documentation locally, you will need to
install or update these programs accordingly.
-@warning{@command{./configure} may fail to issue warnings for
+@warning{@command{../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 @ref{Requirements for building
@node Configuring target directories
@unnumberedsubsubsec Configuring target directories
+@warning{make sure that you are in the @file{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
-@command{./configure@tie{}--help}:
+@command{../configure@tie{}--help}:
@quotation
By default, `@command{make@tie{}install}' will install all the
files in @file{/usr/local/bin}, @file{/usr/local/lib} etc. You
can specify an installation prefix other than @file{/usr/local}
-using `@code{--prefix}', for instance `@code{--prefix=$HOME}'.
+using `@option{--prefix}', for instance `@option{--prefix=$HOME}'.
@end quotation
A typical installation prefix is @file{$HOME/usr}:
@example
-./configure --prefix=$HOME/usr
+../configure --prefix=$HOME/usr
@end example
Note that if you plan to install a local build on a system where
It is also possible to specify separate installation directories
for different types of program files. See the full output of
-@command{./configure@tie{}--help} for more information.
+@command{../configure@tie{}--help} for more information.
If you encounter any problems, please see @ref{Problems}.
-@node Making an out-of-tree build
-@unnumberedsubsubsec Making an out-of-tree build
-
-It is possible to compile LilyPond in a build tree different from
-the source tree, using the @option{--srcdir} option of
-@command{configure}. Note that in some cases you may need to
-remove the output of a previous @command{configure} command by
-running @command{make@tie{}distclean} in the main source directory
-before configuring the out-of-tree build:
-
-@example
-make distclean
-mkdir lily-build && cd lily-build
-@var{sourcedir}/configure --srcdir=@var{sourcedir}
-@end example
-
-
@node Compiling LilyPond
@section Compiling LilyPond
@menu
-* Using @command{make}::
-* Saving time with the @option{-j} option::
+* Using make::
+* Saving time with the -j option::
* Compiling for multiple platforms::
-* Useful @command{make} variables::
+* Useful make variables::
@end menu
-@node Using @command{make}
+@node Using make
@subsection Using @command{make}
+@warning{make sure that you are in the @file{build/} subdirectory
+of your source tree.}
+
LilyPond is compiled with the @command{make} command. Assuming
@command{make} is configured properly, you can simply run:
TODO: Describe what @command{make} actually does.
-@node Saving time with the @option{-j} option
+@node Saving time with the -j option
@subsection Saving time with the @option{-j} option
If your system has multiple CPUs, you can speed up compilation by
If you get errors using the @option{-j} option, and @samp{make}
succeeds without it, try lowering the @code{@var{X}} value.
+Because multiple jobs run in parallel when @option{-j} is used, it can
+be difficult to determine the source of an error when one occurs. In
+that case, running @samp{make} without the @option{-j} is advised.
@node Compiling for multiple platforms
@subsection Compiling for multiple platforms
If you want to build multiple versions of LilyPond with different
configuration settings, you can use the
-@code{--enable-config=@var{CONF}} option of @command{configure}.
-You should use @code{make@tie{}conf=@var{CONF}} to generate the
-output in @file{out-@var{CONF}}. For example, suppose you want to
+@option{--enable-config=@var{conf}} option of @command{configure}.
+You should use @code{make@tie{}conf=@var{conf}} to generate the
+output in @file{out-@var{conf}}. For example, suppose you want to
build with and without profiling, then use the following for the
normal build
@ref{Installing LilyPond from a local build}
-@node Useful @command{make} variables
+@node Useful make variables
@subsection Useful @command{make} variables
If a less verbose build output if desired, the variable
@menu
* Installing LilyPond from a local build::
* Generating documentation::
-* Testing LilyPond::
+* Testing LilyPond binary::
@end menu
@menu
* Documentation editor's edit/compile cycle::
* Building documentation::
-* Saving time with @code{CPU_COUNT}::
+* Building a single document::
+* Saving time with CPU_COUNT::
+* AJAX search::
* Installing documentation::
* Building documentation without compiling::
@end menu
make [-j@var{X}] @emph{## needed if editing outside}
@emph{## Documentation/, but useful anyway}
@emph{## for finding Texinfo errors.}
-touch Documentation/*te?? @emph{## bug workaround}
make [-j@var{X} CPU_COUNT=@var{X}] doc @emph{## usually faster than initial build.}
@end example
@item
Reset:
-@example
-make doc-clean @emph{## use only as a last resort.}
-@end example
+In some cases, it is possible to clean the compiled documentation
+with @samp{make@tie{}doc-clean}, but this method is not guaranteed
+to fix everything. Instead, we recommend that you delete your
+@file{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.
+
@end itemize
@node Building documentation
in those places; the only complete set of documentation is in
@file{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:
+@code{make doc} compiles the documents for all languages. To save
+some compile time, the English language documents can be compiled
+on their own with:
@example
-make info
+make LANGS='' doc
@end example
-@knownissues
-
-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 @code{make@tie{}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 @command{touch} the top source file for any
-manual you've edited. For example, if you make changes to a file
-in @file{notation/}, do:
+@noindent Similarly, it is possible to compile a subset of the
+translated documentation by specifying their language codes on the
+command line. For example, the French and German translations are
+compiled with:
@example
-touch Documentation/notation.tely
+make LANGS='de fr' doc
@end example
-@noindent
-The top sources possibly affected by this are:
+@noindent Note that this will also compile the English version.
+
+Compilation of documentation in Info format with images can be
+done separately by issuing:
@example
-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
+make info
@end example
@noindent
-You can @command{touch} all of them at once with:
+An issue when switching branches between master and translation
+is the appearance/disappearance of translated versions of some manuals.
+If you see such a warning from make:
@example
-touch Documentation/*te??
+No rule to make target `X', needed by `Y'
@end example
@noindent
-However, this will rebuild all of the manuals
-indiscriminately---it is more efficient to @command{touch} only
-the affected files.
+Your best bet is to delete the file Y.dep and to try again.
+
+@node Building a single document
+@unnumberedsubsubsec Building a single document
+It's possible to build a single document. For example, to rebuild
+only @file{contributor.pdf}, do the following:
+
+@example
+cd build/
+cd Documentation/
+touch ../../Documentation/contributor.texi
+make out=www out-www/contributor.pdf
+@end example
+If you are only working on a single document, test-building it in
+this way can give substantial time savings - recreating
+@file{contributor.pdf}, for example, takes a matter of seconds.
-@node Saving time with @code{CPU_COUNT}
+@node Saving time with CPU_COUNT
@unnumberedsubsubsec Saving time with @code{CPU_COUNT}
The most time consuming task for building the documentation is
consistently even if @samp{make -j5} rarely succeeds.
+@node AJAX search
+@unnumberedsubsubsec AJAX search
+
+To build the documentation with interactive searching, use:
+
+@example
+make doc AJAX_SEARCH=1
+@end example
+
+This requires PHP, and you must view the docs via a http
+connection (you cannot view them on your local filesystem).
+
+@warning{Due to potential security or load issues, this option is
+not enabled in the official documentation builds. Enable at your
+own risk.}
+
+
@node Installing documentation
@unnumberedsubsubsec Installing documentation
On MacOS X with macports, you should use this:
@verbatim
-export DYLD_LIBRARY_PATH=/opt/local/lib
+export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
exec /opt/local/bin/pngtopnm "$@"
@end verbatim
-@node Testing LilyPond
-@subsection Testing LilyPond
+@node Testing LilyPond binary
+@subsection Testing LilyPond binary
LilyPond comes with an extensive suite that exercises the entire
-program. This suite can be used to automatically check the impact
-of a change.
+program. This suite can be used to test that the binary has
+been built correctly.
-@menu
-* Developer's edit/compile/test cycle::
-* Other tests::
-@end menu
+The test suite can be executed with:
-@node Developer's edit/compile/test cycle
-@unnumberedsubsubsec Developer's edit/compile/test cycle
-
-TODO: is @code{[-j@var{X} CPU_COUNT=@var{X}]} useful for
-@code{test-baseline}, @code{check}, @code{clean},
-@code{test-redo}?
-
-@itemize
-@item
-Initial test:
-
-@example
-make [-j@var{X}]
-make test-baseline
-make [-j@var{X} CPU_COUNT=@var{X}] check
-@end example
-
-@item
-Edit/compile/test cycle:
-
-@example
-@emph{## edit source files, then...}
-
-make clean @emph{## only if needed (see below)}
-make [-j@var{X}] @emph{## only if needed (see below)}
-make test-redo @emph{## redo files differing from baseline}
-make [-j@var{X} CPU_COUNT=@var{X}] check @emph{## CPU_COUNT here?}
-@end example
-
-@item
-Reset:
-
-@example
-make test-clean
-@end example
-@end itemize
-
-If you modify any source files that have to be compiled (such as
-@file{.cc} or @file{.hh} files in @file{flower/} or @file{lily/}),
-then you must run @command{make} before @command{make test-redo},
-so @command{make} can compile the modified files and relink all
-the object files. If you only modify files which are interpreted,
-like those in the @file{scm/} and @file{ly/} directories, then
-@command{make} is not needed before @command{make test-redo}.
-
-Also, if you modify any font definitions in the @file{mf/}
-directory then you must run @command{make clean} and
-@command{make} before running @command{make test-redo}. This will
-recompile everything, whether modified or not, and takes a lot
-longer.
-
-Running @command{make@tie{}check} 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.
-
-
-@node Other tests
-@unnumberedsubsubsec Other tests
-
-For tracking memory usage as part of this test, you will need
-GUILE CVS; especially the following patch:
-@uref{http://www.lilypond.org/vc/old/gub.darcs/patches/guile-1.9-gcstats.patch}.
-
-For checking the coverage of the test suite, do the following
+@verbatim
+make test
+@end verbatim
-@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
+If the test suite completes successfully, the LilyPond binary
+has been verified.
+More information on the regression test suite is found at
+@rcontrib{Regression tests}.
@node Problems
@section Problems
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
+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
+export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
@end example
-Now you must edit the generated @code{config.make} file. Change
+Now you must edit the generated @file{config.make} file. Change
@example
FLEXLEXER_FILE = /usr/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
+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
rm -rf urw-fonts-1.07pre44
@end example
-Now run the @code{./configure} script. To avoid complications with
+Now run the @code{./configure} script. To avoid complications with
automatic font detection, add
@example
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
+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 @command{make
+development version from the source tree. After running @command{make
all} from the top directory of the Lilypond source files, there will
be a binary called @code{lilypond} in the @code{out} directory:
@end example
This binary can be run without actually doing the @code{make
-install} command. The advantage to this is that you can have all
+install} command. The advantage to this is that you can have all
of the latest changes available after pulling from git and running
@code{make all}, without having to uninstall the old version and
reinstall the new.
- other compilation tricks for developers
-@node Using a Virtual Machine to Compile LilyPond
-@section Using a Virtual Machine to Compile LilyPond
-
-
-TODO: rewrite for lily-git.tcl !!! do before GOP! -gp
-
-Since it is not possible to compile Lilypond on Windows, some
-developers may find it useful to install a GNU/Linux virtual
-machine. A disk image with a special remix of @strong{Ubuntu}
-has been created for this purpose. It has all of the Lilypond
-build dependencies in place, so that once installed, it is
-ready to compile both Lilypond and the Documentation.
-The @code{lilybuntu} remix is available for download here:
-
-@example
-@uref{http://@/files.lilynet.net/@/lilybuntu.iso}
-@end example
-
-We do not necessarily recommend any one virtualization tool,
-however the @code{lilybuntu} remix is known to work well on
-@uref{http://www.virtualbox.org/wiki/Downloads, Sun VirtualBox},
-which is a free download. Consult your virtualization software's
-documentation for instructions on setting up the software and
-for general instructions on installing a virtual machine.
-
-Steps to setting up @code{lilybuntu} in a virtual machine:
-
-@enumerate
-@item Download the @code{lilybuntu} disk image.
-
-@item Install @code{lilybuntu}. You will use the @code{.iso}
-file as the boot disk. It should not be necessary to burn it
-to a DVD, but consult the documentation for your virtualization
-software for specific instructions. If possible, use at least
-the recommended amount of RAM for the virtual machine (384 MB on
-VirtualBox), and use a dynamically expanding virtual hard drive.
-A virtual hard drive with 6 GB will be enough to compile LilyPond,
-but if you intend to build the docs and run the regression tests
-the virtual hard drive should be at least 10 GB.
-The Ubuntu installation should be straightforward, although in the
-partitioning stage do not be afraid to select @qq{use entire disk,}
-since this is only your @strong{virtual disk} and not your
-machine's actual hard drive.
-
-@item After installation is complete, restart the virtual
-machine. If you are using @strong{VirtualBox}, you may wish
-to install the @qq{Guest Additions}, which while not essential for
-compiling @code{Lilypond} will allow you to use the virtual machine
-in full screen, Seamless mode (also known as Unity mode on other
-virtualization platforms) and allow you to share clipboards between
-the physical and virtual machine. From the @code{Devices} menu select
-@code{Install Guest Additions...}, the @code{VBOXADDITIONS} CDROM device
-will appear on the desktop. Open a @strong{terminal} session.
-(@code{Applications > Accessories > Terminal}) and @code{cd} to the
-top level of the CDROM. Run the @code{autorun.sh} script as superuser
-(@code{sudo ./autorun.sh }), a console window will open while the
-@qq{Guest Additions} are being installed. Once the script has
-been finished, reboot your Virtual Machine to complete the installation
-of the @qq{Guest Additions}.
-
-@item Open a @strong{terminal} session.
-(@code{Applications > Accessories > Terminal})
-
-@item Open @strong{Firefox} (there's an icon for it on the
-panel at the top of the screen) and go to the online Lilypond
-@uref{http://lilypond.org/doc/latest/Documentation/contributor/,
-Contributor's Guide}.
-
-@item To retrieve the Lilypond source code from @code{git},
-copy-and-paste each command from the CG @qq{Main source code}
-section into the terminal. (paste into the terminal with keystroke
-@code{CTRL+SHIFT+V})
-
-@item Prepare to build Lilypond by running the configuration script.
-Type
-
-@example
-./autogen.sh
-@end example
-
-When it is finished you should be presented
-with the three most common @code{make} options:
-
-@example
-Type:
- make all to build LilyPond
- make install to install LilyPond
- make help to see all possible targets
-
-Edit local.make for local Makefile overrides.
-@end example
-
-@item First type @code{make all} to build Lilypond. This will take
-a while.
-
-@item When Lilypond is finished building, build the documentation
-by typing
-
-@example
-make doc
-@end example
-
-Depending on your system specs it could take from 30-60 minutes
-to finish.
-
-@end enumerate
-
-At this point everything has been compiled.
-You may install Lilypond using @code{make install}, or you may wish
-to set up your system with concurrent stable and development
-versions as described in the previous section.
-
-
@node Build system
@section Build system
used by us. Hopefully this will change in the future.
-@subsubheading Version-specific texinfo macors
+@subsubheading Version-specific texinfo macros
@itemize
@item
used extensively in the @code{WEBSITE_ONLY_BUILD} version of the
-website (made with website.make, used on lilypond.org)
+website (made with @file{website.make}, used on lilypond.org)
@item
not (?) used in the main docs?