* Overview of compiling::
* Requirements::
* Getting the source code::
-* Configuring @command{make}::
+* Configuring make::
* Compiling LilyPond::
* Post-compilation options::
* Problems::
@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)
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
@end enumerate
-@node Running @command{./configure}
+@node Running ./configure
@subsection Running @command{./configure}
@menu
@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}
LilyPond is compiled with the @command{make} command. Assuming
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
@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}::
+* Saving time with CPU_COUNT::
+* AJAX search::
* Installing documentation::
* Building documentation without compiling::
@end menu
the affected files.
-@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.
-
-@menu
-* Developer's edit/compile/test cycle::
-* Other tests::
-@end menu
-
-@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
+program. This suite can be used to test that the binary has
+been built correctly.
-@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
+The test suite can be executed with:
-TODO: fix broken link here.
-
-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
+@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
@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.
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
+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:
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
+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.
@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
+@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
+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,
@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})
+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
Edit local.make for local Makefile overrides.
@end example
-@item First type @code{make all} to build Lilypond. This will take
+@item First type @code{make all} to build Lilypond. This will take
a while.
@item When Lilypond is finished building, build the documentation
used by us. Hopefully this will change in the future.
-@subsubheading Version-specific texinfo macors
+@subsubheading Version-specific texinfo macros
@itemize
projects / lilypond.git / blobdiff