X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fincluded%2Fcompile.itexi;h=cc2894019faf699194c5499614f71d772a22fb6b;hb=730d4eb3e0328e8ba0b376f8191a5bb6ae7f904c;hp=b2dcf7fdb737d5bd161173ebe9e670df1f083dba;hpb=1b832d794f1444033f10465971e97d33f76fe310;p=lilypond.git diff --git a/Documentation/included/compile.itexi b/Documentation/included/compile.itexi index b2dcf7fdb7..cc2894019f 100644 --- a/Documentation/included/compile.itexi +++ b/Documentation/included/compile.itexi @@ -7,7 +7,6 @@ @c @n ode Compiling from source @c @s ection Compiling from source - @menu * Overview of compiling:: * Requirements:: @@ -44,7 +43,7 @@ without compiling}. Attempts to compile LilyPond natively on Windows have been unsuccessful, though a workaround is available (see -@rcontrib{Lilybuntu}). +@rcontrib{LilyDev}). @node Requirements @@ -140,7 +139,9 @@ python@var{version}-dev @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} @@ -253,12 +254,12 @@ here: @uref{http://download.linuxaudio.org/lilypond/source/} @end example -Download the tarball to your @file{@/~/@/src/} directory, or some +Download the tarball to your @file{~/src/} directory, or some other appropriate place. @warning{Be careful where you unpack the tarball! Any subdirectories of the current folder named @file{lilypond/} or -@file{lilypond@/-@var{x.y.z}/} (where @var{x.y.z} is the release +@file{lilypond-@var{x.y.z}/} (where @var{x.y.z} is the release number) will be overwritten if there is a name clash with the tarball.} @@ -269,7 +270,7 @@ tar -xzf lilypond-@var{x.y.z}.tar.gz @end example This creates a subdirectory within the current directory called -@file{lilypond@/-@var{x.y.z}/}. Once unpacked, the source files +@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 @@ -283,7 +284,7 @@ download and install the free-software @menu * Running ./autogen.sh:: -* Running ./configure:: +* Running ../configure:: @end menu @@ -299,50 +300,65 @@ Next, you need to create the generated files; enter the following command from your top source directory: @example -./autogen.sh +./autogen.sh --noconfigure @end example -This will: +This will generate a number of files and directories to aid +configuration, such as @file{configure}, @file{README.txt}, etc. + +Next, create the build directory with: + +@example +mkdir build/ +cd build/ +@end example -@enumerate -@item generate a number of files and directories to aid -configuration, such as @file{configure}, @file{README@/.txt}, etc. +We heavily recommend building lilypond inside a separate directory +with this method. -@item automatically run the @command{./configure} command. -@end enumerate +@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} @@ -358,7 +374,7 @@ WARNING: Please consider installing optional programs: @var{bar} 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 @@ -368,22 +384,25 @@ documentation}.} @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}'. +files in @file{/usr/local/bin}, @file{/usr/local/lib} etc. You +can specify an installation prefix other than @file{/usr/local} +using `@option{--prefix}', for instance `@option{--prefix=$HOME}'. @end quotation -A typical installation prefix is @file{$HOME/@/usr}: +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 @@ -394,34 +413,17 @@ write permission (such as your home directory). The installation directory will be automatically created if necessary. The location of the @command{lilypond} command installed by this -process will be @file{@var{prefix}/@/bin/@/lilypond}; you may want to -add @file{@var{prefix}/@/bin/} to your @code{$PATH} if it is not +process will be @file{@var{prefix}/bin/lilypond}; you may want to +add @file{@var{prefix}/bin/} to your @code{$PATH} if it is not already included. 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 @@ -437,6 +439,9 @@ mkdir lily-build && cd lily-build @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: @@ -453,6 +458,10 @@ make help 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 @@ -478,9 +487,9 @@ that case, running @samp{make} without the @option{-j} is advised. 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 @@ -515,7 +524,7 @@ make conf=prof install If a less verbose build output if desired, the variable @code{QUIET_BUILD} may be set to @code{1} on @command{make} -command line, or in @file{local@/.make} at top of the build tree. +command line, or in @file{local.make} at top of the build tree. @node Post-compilation options @@ -543,7 +552,7 @@ make install @end example If instead, your installation directory is not one that you can -normally write to (such as the default @file{/@/usr/@/local/}, which +normally write to (such as the default @file{/usr/local/}, which typically is only writeable by the superuser), you will need to temporarily become the superuser when running @command{make@tie{}install}: @@ -553,7 +562,7 @@ sudo make install @end example @noindent -or... +or@dots{} @example su -c 'make install' @@ -571,6 +580,7 @@ re-install. See @ref{Configuring target directories}. @menu * Documentation editor's edit/compile cycle:: * Building documentation:: +* Building a single document:: * Saving time with CPU_COUNT:: * AJAX search:: * Installing documentation:: @@ -587,28 +597,35 @@ Initial documentation build: @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 @@ -621,71 +638,94 @@ documentation can be built by issuing: 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 +is available in @file{out-www/offline-root/}, and can be browsed locally. Various portions of the documentation can be found by -looking in @file{out/} and @file{out@/-www} subdirectories in other +looking in @file{out/} and @file{out-www} subdirectories in other places in the source tree, but these are only @emph{portions} of the docs. Please do not complain about anything which is broken in those places; the only complete set of documentation is in -@file{out@/-www/@/offline@/-root/} from the top of the source tree. +@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} @@ -695,7 +735,7 @@ running LilyPond to build images of music, and there cannot be several simultaneously running @command{lilypond-book} instances, so the @option{-j} @command{make} option does not significantly speed up the build process. To help speed it up, the makefile -variable @option{CPU_COUNT} may be set in @file{local@/.make} or on +variable @option{CPU_COUNT} may be set in @file{local.make} or on the command line to the number of @code{.ly} files that LilyPond should process simultaneously, e.g. on a bi-processor or dual core machine: @@ -758,12 +798,12 @@ make install-info @noindent Note that to get the images in Info documentation, @code{install-doc} target creates symbolic links to HTML and PDF installed documentation -tree in @file{@var{prefix}/@/share/@/info}, in order to save disk space, +tree in @file{@var{prefix}/share/info}, in order to save disk space, whereas @code{install-info} copies images in -@file{@var{prefix}/@/share/@/info} subdirectories. +@file{@var{prefix}/share/info} subdirectories. It is possible to build a documentation tree in -@file{out@/-www/@/online@/-root/}, with special processing, so it can be +@file{out-www/online-root/}, with special processing, so it can be used on a website with content negotiation for automatic language selection; this can be achieved by issuing @@ -817,10 +857,10 @@ Please note that this may break sometimes -- for example, if a new feature is added with a test file in input/regression, even the latest development release of LilyPond will fail to build the docs. -You may build the manual without building all the @file{input/@/@/*} stuff +You may build the manual without building all the @file{input/*} stuff (i.e. mostly regression tests): change directory, for example to @file{Documentation/}, issue @code{make doc}, which will build -documentation in a subdirectory @file{out@/-www} from the source files in +documentation in a subdirectory @file{out-www} from the source files in current directory. In this case, if you also want to browse the documentation in its post-processed form, change back to top directory and issue @@ -882,7 +922,7 @@ bug reports to @email{bug-lilypond@@gnu.org}. 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 @@ -897,7 +937,7 @@ $ make @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 @@ -915,7 +955,7 @@ export PATH=/opt/local/bin:/opt/local/sbin:$PATH export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH @end example -Now you must edit the generated @file{config@/.make} file. Change +Now you must edit the generated @file{config.make} file. Change @example FLEXLEXER_FILE = /usr/include/FlexLexer.h @@ -949,12 +989,12 @@ automatic font detection, add @end example -@unnumberedsubsubsec Solaris +@unnumberedsubsec Solaris Solaris7, ./configure -@file{@/./@/configure} needs a POSIX compliant shell. On Solaris7, -@file{/@/bin/@/sh} is not yet POSIX compliant, but @file{/@/bin/@/ksh} or bash +@file{./configure} needs a POSIX compliant shell. On Solaris7, +@file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash is. Run configure like @example @@ -968,12 +1008,12 @@ or 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}. +port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}. -Open the file @file{$LILYPONDBASE/@/usr/@/etc/@/fonts/@/local@/.conf} and add the +Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the following line just after the @code{} line. (Adjust as necessary for your hierarchy.) @@ -982,7 +1022,7 @@ for your hierarchy.) @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 @@ -1009,12 +1049,12 @@ Debian GNU/Linux @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 +set @code{PYTHONPATH} to @file{python/out} in your build +directory, or @file{@dots{}/usr/lib/lilypond/current/python} in the installation directory structure. @@ -1083,7 +1123,7 @@ We currently use make and stepmake, which is complicated and only used by us. Hopefully this will change in the future. -@subsubheading Version-specific texinfo macros +@subheading Version-specific texinfo macros @itemize @@ -1093,7 +1133,7 @@ made with @command{scripts/build/create-version-itexi.py} and@* @item used extensively in the @code{WEBSITE_ONLY_BUILD} version of the -website (made with @file{website@/.make}, used on lilypond.org) +website (made with @file{website.make}, used on lilypond.org) @item not (?) used in the main docs?