From: John Mandereau Date: Tue, 10 Jun 2008 21:25:09 +0000 (+0200) Subject: Improve compilation instructions X-Git-Tag: release/2.11.49-1~1^2~7 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=074285347c9783a31f6bba90eec9c9799c0eda6c;p=lilypond.git Improve compilation instructions - fix formatting nitpicks, - document srcdir builds, - better document documentation building. --- diff --git a/Documentation/user/install.itely b/Documentation/user/install.itely index 277aaa0e6d..18c1c6fe1b 100644 --- a/Documentation/user/install.itely +++ b/Documentation/user/install.itely @@ -75,7 +75,7 @@ mingw - Windows x86 * Downloading source code:: * Requirements:: * Building LilyPond:: -* Building documentation without compiling LilyPond:: +* Building documentation:: * Testing LilyPond:: * Problems:: @end menu @@ -175,7 +175,7 @@ International fonts are required to create music with international text or lyrics. -@unnumberedsubsubsec Building documentation +@unnumberedsubsubsec Requirements for building documentation You can view the documentation online at @uref{http://lilypond.org/doc/}, but you can also build it locally. @@ -190,41 +190,11 @@ about which font packages are necessary for your platform) @item Ghostscript, 8.50 with the patch from @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154} and the patch from -@uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}. +@uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}, or use +a release of Ghostscript which includes these patches, for example +8.60 or newer. @end itemize -The documentation is built by issuing - -@example -make web -@end example - -After compilation, the HTML documentation tree is available in -@file{out-www/offline-root/}, and can be browsed locally. - -The HTML and PDF files can be installed into the standard documentation -path by issuing - -@example -make out=www web-install -@end example - -It is also possible to build a documentation tree in -@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 - -@example -make WEB_TARGETS=online web -@end example - -@noindent -and both @q{offline} and @q{online} targets can be generated by issuing - -@example -make WEB_TARGETS="offline online" web -@end example - @node Building LilyPond @subsection Building LilyPond @@ -238,9 +208,10 @@ gunzip -c lilypond-x.y.z | tar xf - cd lilypond-x.y.z ./configure # run with --help for applicable options make -make install +su -c 'make install' @end example +@noindent If you are not root, you should choose a @code{--prefix} argument that points into your home directory, e.g. @@ -253,10 +224,10 @@ points into your home directory, e.g. If you want to build multiple versions of LilyPond with different configuration settings, you can use the @code{--enable-config=CONF} -option of configure. You should use @code{make conf=CONF} to generate -the output in @file{out-CONF}. Example: Suppose you want to build -with and without profiling, then use the following for the normal -build +option of @command{configure}. You should use @code{make conf=CONF} +to generate the output in @file{out-CONF}. For example, suppose you +want to build with and without profiling, then use the following for +the normal build @example ./configure --prefix=$HOME/usr/ --enable-checking @@ -273,33 +244,113 @@ make conf=prof install @end example +@unnumberedsubsubsec Compiling outside the source tree + +It is possible to compile LilyPond in a build tree different from the +source tree, with @code{--srcdir} option of @command{configure}: + +@example +mkdir lily-build && cd lily-build +@var{sourcedir}/configure --srcdir=@var{sourcedir} + +@end example + +@node Building documentation +@subsection Building documentation + +This requires a successful compile of LilyPond, or using an external +LilyPond binary. + +@menu +* Commands for building documentation:: Compiling and installing the documentation. +* Building documentation without compiling LilyPond:: Using a LilyPond binary already installed. +@end menu + +@node Commands for building documentation +@unnumberedsubsubsec Commands for building documentation + +The documentation is built by issuing + +@example +make web +@end example + +After compilation, the HTML documentation tree is available in +@file{out-www/offline-root/}, and can be browsed locally. + +The HTML and PDF files can be installed into the standard documentation +path by issuing + +@example +make web-install +@end example + +It is also possible to build a documentation tree in +@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 + +@example +make WEB_TARGETS=online web +@end example + +@noindent +and both @q{offline} and @q{online} targets can be generated by issuing + +@example +make WEB_TARGETS="offline online" web +@end example + +Several targets are available to clean the documentation build and +help with maintaining documentation; an overview of these targets is +available with + +@example +make help +@end example + +@noindent +from every directory in the build tree. Most targets for +documentation maintenance are available from @file{Documentation/}; +for more information, see @file{Documentation/user/README.txt} and +@file{Documentation/TRANSLATION}. + + @node Building documentation without compiling LilyPond -@subsection Building documentation without compiling LilyPond +@unnumberedsubsubsec Building documentation without compiling LilyPond -The documentation can be built locally without compiling LilyPond from -scratch. +The documentation can be built locally without compiling LilyPond +binary, if LilyPond is already installed on your system. -From a fresh git checkout, do +From a fresh Git checkout, do @example -./autogen.sh % ignore any warning messages +./autogen.sh # ignore any warning messages cp GNUmakefile.in GNUmakefile make -C python nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web -% change the lilypond directory as appropriate @end example 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 -unstable Lily will fail to build the docs. +development release of LilyPond will fail to build the docs. -You may build the manual ( Documentation/user/ ) without building all -the input/* stuff. +You may build the manual without building all +the input/* stuff: change directory, for example to +@file{Documentation/user}, issue @code{make web}, which will build +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 + +@example +make out=www WWW-post +@end example @knownissues You may also need to create a script for @command{pngtopnm} and -@code{pnmtopng}. On Linux, I use this: +@code{pnmtopng}. On GNU/Linux, I use this: @verbatim export LD_LIBRARY_PATH=/usr/lib @@ -313,26 +364,6 @@ export DYLD_LIBRARY_PATH=/sw/lib exec /sw/bin/pngtopnm "$@" @end verbatim -In order to force make to build a complete manual (this does not -rebuild all examples, only things which are changed), I recommend -writing a script like this: - -@verbatim -### run from Documentation/user/ -# possibly required on OS X and/or old texinfo -# ulimit -n 4096 -if [ -e out-www/lilypond.texi ]; then rm out-www/lilypond.* ; fi; -if [ -e out-www/lilypond-program.texi ]; then rm -out-www/lilypond-program.* ; fi; -if [ -e out-www/lilypond-learning.texi ]; then rm -out-www/lilypond-learning.* ; fi; -nice make LILYPOND_EXTERNAL_BINARY=~/usr/bin/lilypond web -@end verbatim - -To rebuild the complete HTML docs, run the above script from the -@file{Documentation/user/} directory, then run the final line (the -@code{nice make}) from the top source dir. - @node Testing LilyPond