X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fincluded%2Fcompile.itexi;h=31e68c46a110350123e8c004d142806ab4ef28d2;hb=6baab03c15a08d82b149fa70798e0ba5b144059b;hp=e95cf2629cd8122a1f7c0c909f3f8d731d5bef0e;hpb=b5a72fde8d11be3bbcf2b78d98ece9e513c0de57;p=lilypond.git diff --git a/Documentation/included/compile.itexi b/Documentation/included/compile.itexi index e95cf2629c..31e68c46a1 100644 --- a/Documentation/included/compile.itexi +++ b/Documentation/included/compile.itexi @@ -43,7 +43,7 @@ without compiling}. Attempts to compile LilyPond natively on Windows have been unsuccessful, though a workaround is available (see -@rcontrib{Lilydev}). +@rcontrib{LilyDev}). @node Requirements @@ -75,7 +75,7 @@ installed by default) newer) @item @uref{http://www.gnu.org/software/guile/guile.html, Guile} -(1.8.2 or newer) +(1.8.8 - version 2.x is not currently supported) @item @uref{http://www.pango.org/, Pango} (1.12 or newer) @@ -458,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 @@ -558,7 +562,7 @@ sudo make install @end example @noindent -or... +or@dots{} @example su -c 'make install' @@ -593,14 +597,15 @@ 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} @@ -611,9 +616,11 @@ make [-j@var{X} CPU_COUNT=@var{X}] doc @emph{## usually faster than initial bui @item Reset: -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 +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 @@ -631,11 +638,20 @@ 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 @@ -646,9 +662,20 @@ 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. -@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: +@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 log-clean +@end example + +@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: @example make LANGS='' doc @@ -895,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 @@ -910,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 @@ -962,7 +989,7 @@ automatic font detection, add @end example -@unnumberedsubsubsec Solaris +@unnumberedsubsec Solaris Solaris7, ./configure @@ -981,7 +1008,7 @@ 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}. @@ -995,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 @@ -1022,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 +directory, or @file{@dots{}/usr/lib/lilypond/current/python} in the installation directory structure. @@ -1096,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