@c @n ode Compiling from source
@c @s ection Compiling from source
-
@menu
* Overview of compiling::
* Requirements::
Attempts to compile LilyPond natively on Windows have been
unsuccessful, though a workaround is available (see
-@rcontrib{Lilybuntu}).
+@rcontrib{LilyDev}).
@node Requirements
@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}
@menu
* Running ./autogen.sh::
-* Running ./configure::
+* Running ../configure::
@end menu
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 ../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
@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.
+@seealso
+@ref{Generating documentation} provides more info on the @command{make} targets
+used to build the LilyPond documentation.
+
@node Saving time with the -j option
@subsection Saving time with the @option{-j} option
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
@end example
@noindent
-or...
+or@dots{}
@example
su -c 'make install'
@menu
* Documentation editor's edit/compile cycle::
* Building documentation::
+* Building a single document::
* Saving time with CPU_COUNT::
* AJAX search::
* Installing documentation::
@example
make [-j@var{X}]
-make [-j@var{X} CPU_COUNT=@var{X}] doc @emph{## can take an hour or more}
+make [-j@var{X} CPU_COUNT=@var{X}] doc @emph{## can take an hour or more}
+make [-j@var{X} CPU_COUNT=@var{X}] doc-stage-1 @emph{## to build only PDF documentation}
@end example
@item
Edit/compile cycle:
@example
-@emph{## edit source files, then...}
+@emph{## edit source files, then@dots{}}
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
+It is generally possible to remove the compiled documentation from
+your system
+with @samp{make@tie{}doc-clean}, but this method is not 100%
+guaranteed. Instead, if you want to be sure you have a clean
+system, 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
make doc
@end example
-The first time you run @command{make@tie{}doc}, the process can
-easily take an hour or more. After that, @command{make@tie{}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.
+or, to build only the PDF documentation and not the HTML,
+
+@example
+make doc-stage-1
+@end example
+
+@warning{The first time you run @command{make@tie{}doc}, the
+process can easily take an hour or more with not much output
+on the command line.}
+
+After this initial build, @command{make@tie{}doc} only makes
+changes to the documentation where needed, so it may only take
+a minute or two to test changes if the documentation is already
+built.
If @command{make@tie{}doc} succeeds, the HTML documentation tree
is available in @file{out-www/offline-root/}, and can be browsed
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:
+@command{make@tie{}doc} sends the output from most of the
+compilation to logfiles. If the build fails for any reason, it
+should prompt you with the name of a logfile which will provide
+information to help you work out why the build failed. These
+logfiles are not deleted with @command{make@tie{}doc-clean}. To
+remove all the logfiles generated by the compilation process, use:
@example
-make info
+make log-clean
@end example
-@knownissues
+@code{make@tie{}doc} compiles the documents for all languages. To
+save some compile time, the English language documents can be
+compiled on their own with:
-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:
+@example
+make LANGS='' doc
+@end example
+
+@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 CPU_COUNT
@unnumberedsubsubsec Saving time with @code{CPU_COUNT}
Bugs that are not fault of LilyPond are documented here.
-@unnumberedsubsubsec Bison 1.875
+@unnumberedsubsec 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
@end example
-@unnumberedsubsubsec Compiling on MacOS@tie{}X
+@unnumberedsubsec Compiling on MacOS@tie{}X
Here are special instructions for compiling under MacOS@tie{}X.
These instructions assume that dependencies are installed using
@end example
-@unnumberedsubsubsec Solaris
+@unnumberedsubsec Solaris
Solaris7, ./configure
CONFIG_SHELL=/bin/bash bash -c ./configure
@end example
-@unnumberedsubsubsec FreeBSD
+@unnumberedsubsec 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}.
@end example
-@unnumberedsubsubsec International fonts
+@unnumberedsubsec International fonts
On Mac OS X, all fonts are installed by default. However, finding all
system fonts requires a bit of configuration; see
@end verbatim
-@unnumberedsubsubsec Using lilypond python libraries
+@unnumberedsubsec 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
+directory, or @file{@dots{}/usr/lib/lilypond/current/python} in the
installation directory structure.
used by us. Hopefully this will change in the future.
-@subsubheading Version-specific texinfo macros
+@subheading Version-specific texinfo macros
@itemize