@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
@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
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:
@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
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
@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?