From 7a2a04de7050f1f13a457b682abcec69dc7a37b3 Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Mon, 30 Jul 2007 15:49:44 -0700 Subject: [PATCH] Reorg of install.itely. --- Documentation/user/install.itely | 249 +++++++++++++++++-------------- 1 file changed, 141 insertions(+), 108 deletions(-) diff --git a/Documentation/user/install.itely b/Documentation/user/install.itely index 1e1b86c423..08c033b61c 100644 --- a/Documentation/user/install.itely +++ b/Documentation/user/install.itely @@ -11,21 +11,71 @@ @node Install @chapter Install -@html +@c I don't know what this comment does. Remove? -gp +@ignore +@h tml -@end html +@e nd html +@end ignore + +There are two sets of releases for LilyPond: stable releases, and +unstable development releases. Stable versions have an even-numbered +@q{minor} version number (i.e. 2.8, 2.10, 2.12, etc). Development +versions have an odd-numbered @q{minor} version number (i.e. 2.7, 2.9, +2.11, etc). + +Building LilyPond is an involved process, so we @strong{highly} +recommend using the precompiled binaries. + +@menu +* Precompiled binaries:: +* Compiling from source:: +@end menu -@section Downloading -Even numbered minor versions are `stable' (2.6, 2.8, etc), while odd -version are development releases (2.7, 2.9, etc). Building LilyPond -is an involved process. If possible -@uref{http://lilypond.org/install,download a precompiled binary} for -your platform. +@node Precompiled binaries +@section Precompiled binaries -@subsection Source code +@subsection Downloading + +Check out @uref{http://lilypond.org/web/install/} for up to date +information on binary packages for your platform. If your operating +system is not covered on that general page, please see the complete list +at @uref{http://download.linuxaudio.org/lilypond/binaries/} + +We currently create binaries for + +@example +MacOS +darwin-ppc +darwin-x86 +freebsd-64 +freebsd-x86 +linux-64 +linux-arm +linux-ppc +linux-x86 +mingw +@end example + + + +@node Compiling from source +@section Compiling from source + +@menu +* Downloading source code:: +* Requirements:: +* Building LilyPond:: +* Testing LilyPond:: +* Problems:: +@end menu + +@node Downloading source code +@subsection Downloading source code Download source + @itemize @bullet @item tarballs from @uref{http://lilypond.org/download/} by HTTP. @@ -33,6 +83,7 @@ Download source @uref{http://download.linuxaudio.org/lilypond/} by HTTP. @item GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org} + @example git clone git://git.sv.gnu.org/lilypond.git @end example @@ -46,19 +97,14 @@ The repository does not contain generated files. To create For information on packaging, see @uref{http://lilypond.org/devel}. -@subsection Precompiled binary packages - -Check out @uref{http://lilypond.org/web/install/} for up to date -information on binary packages for your platform. - - -@section Requirements +@node Requirements +@subsection Requirements -@subsection Compilation +@unnumberedsubsubsec Compilation -In addition to the packages needed for running Lilypond (see below), -you need the following extra packages for building. +In addition to the packages needed for running Lilypond (see below), you +need the following extra packages for building. When installing a binary package FOO, you may need to install the FOO-devel, libFOO-dev or FOO-dev package too. @@ -67,24 +113,21 @@ FOO-devel, libFOO-dev or FOO-dev package too. @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer. -@item New Century Schoolbook fonts, as PFB files. These are shipped -with X11 and Ghostscript, and are named @file{c059033l.pfb} +@item New Century Schoolbook fonts, as PFB files. These are shipped with +X11 and Ghostscript, and are named @file{c059033l.pfb} @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb} @item @uref{http://www.xs4all.nl/~hanwen/mftrace/,mftrace} (1.1.19 or -newer), - -You will need to install some additional packages to get mftrace to -work. +newer); you may need to install some additional packages to get mftrace +to work. -@item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} -(version 1.8.2 or newer). If you are installing binary packages, you -may need to install guile-devel or guile-dev or libguile-dev too. +@item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version +1.8.2 or newer). If you are installing binary packages, you may need to +install guile-devel or guile-dev or libguile-dev too. @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.8 or newer). -@item -@uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 4.x or +@item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 4.x or newer). @item @uref{http://www.python.org,Python} (version 2.4 or newer) @@ -104,10 +147,10 @@ header files and libraries. @end itemize -@subsection Running requirements -Running LilyPond requires proper installation of the following -software +@unnumberedsubsubsec Running requirements + +Running LilyPond requires proper installation of the following software @itemize @bullet @@ -127,17 +170,16 @@ International fonts are required to create music with international text or lyrics. -@subsection Building documentation +@unnumberedsubsubsec Building documentation You can view the documentation online at @uref{http://lilypond.org/doc/}, but you can also build it locally. This process requires a successful compile of lilypond. The documentation is built by issuing -@quotation + @example make web @end example -@end quotation Building the website requires some additional tools and packages @@ -155,60 +197,16 @@ and the patch from The HTML files can be installed into the standard documentation path by issuing -@quotation @example make out=www web-install @end example -@end quotation - -@section Testing LilyPond - -@html - -@end html - -LilyPond comes with an extensive suite that excercises the entire -program. This suite can be used to automatically check the impact of a -change. This is done as follows - -@example - make test-baseline - @emph{## apply your changes, compile} - make check -@end example - -This will leave an HTML page @file{out/test-results/index.html}. This -page shows all the important differences that your change introduced, -whether in the layout, MIDI, performance or error reporting. - -To rerun tests, use - -@example - make test-redo @emph{## redo files differing from baseline} - make test-clean @emph{## remove all test results} -@end example - -@noindent -and then run @code{make check} again. -For tracking memory usage as part of this test, you will need GUILE -CVS; especially the following patch: -@uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}. -For checking the coverage of the test suite, do the following - -@example - ./buildscripts/build-coverage.sh - @emph{# uncovered files, least covered first} - python ./buildscripts/coverage.py --summary out-cov/*.cc - @emph{# consecutive uncovered lines, longest first} - python ./buildscripts/coverage.py --uncovered out-cov/*.cc -@end example - -@section Building LilyPond +@node Building LilyPond +@subsection Building LilyPond To install GNU LilyPond, type -@quotation + @example gunzip -c lilypond-x.y.z | tar xf - cd lilypond-x.y.z @@ -216,15 +214,13 @@ cd lilypond-x.y.z make make install @end example -@end quotation If you are not root, you should choose a @code{--prefix} argument that points into your home directory, e.g. -@quotation + @example ./configure --prefix=$HOME/usr @end example -@end quotation @subsection Configuring for multiple platforms @@ -236,40 +232,81 @@ the output in @file{out-CONF}. Example: Suppose you want to build with and without profiling, then use the following for the normal build -@quotation @example ./configure --prefix=$HOME/usr/ --enable-checking make make install @end example -@end quotation and for the profiling version, specify a different configuration -@quotation @example ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking make conf=prof make conf=prof install @end example -@end quotation +@node Testing LilyPond +@subsection Testing LilyPond + +@html + +@end html + +LilyPond comes with an extensive suite that exercises the entire +program. This suite can be used to automatically check the impact of a +change. This is done as follows + +@example +make test-baseline +@emph{## apply your changes, compile} +make check +@end example + +This will leave an HTML page @file{out/test-results/index.html}. This +page shows all the important differences that your change introduced, +whether in the layout, MIDI, performance or error reporting. + +To rerun tests, use + +@example +make test-redo @emph{## redo files differing from baseline} +make test-clean @emph{## remove all test results} +@end example + +@noindent +and then run @code{make check} again. + +For tracking memory usage as part of this test, you will need GUILE +CVS; especially the following patch: +@uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}. -@section Problems +For checking the coverage of the test suite, do the following + +@example +./buildscripts/build-coverage.sh +@emph{# uncovered files, least covered first} +python ./buildscripts/coverage.py --summary out-cov/*.cc +@emph{# consecutive uncovered lines, longest first} +python ./buildscripts/coverage.py --uncovered out-cov/*.cc +@end example + + +@node Problems +@subsection Problems For help and questions use @email{lilypond-user@@gnu.org}. Send bug reports to @email{bug-lilypond@@gnu.org}. Bugs that are not fault of LilyPond are documented here. -@subsection Bison 1.875 +@unnumberedsubsubsec 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 recompile bison 1.875 with the following fix -@quotation @example $ cd lily; make out/parser.cc $ vi +4919 out/parser.cc @@ -277,10 +314,9 @@ $ vi +4919 out/parser.cc # save $ make @end example -@end quotation -@unnumberedsubsec MacOS X +@unnumberedsubsubsec MacOS X For Fink, use the following command to compile. @@ -291,27 +327,26 @@ export PKG_CONFIG_PATH=/sw/lib/freetype219/lib/pkgconfig/:/sw/lib/fontconfig2/li ./configure @end verbatim -@unnumberedsubsec Solaris +@unnumberedsubsubsec Solaris -@itemize @bullet -@item Solaris7, ./configure +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 is. Run configure like -@quotation + @example - CONFIG_SHELL=/bin/ksh ksh -c ./configure +CONFIG_SHELL=/bin/ksh ksh -c ./configure @end example -@end quotation + +@noindent or -@quotation + @example - CONFIG_SHELL=/bin/bash bash -c ./configure +CONFIG_SHELL=/bin/bash bash -c ./configure @end example -@end quotation -@item FreeBSD +@unnumberedsubsubsec 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}. @@ -324,10 +359,8 @@ for your hierarchy.) /usr/X11R6/lib/X11/fonts @end example -@end itemize - -@section International fonts +@unnumberedsubsubsec International fonts On MacOs X, all fonts are installed by default. However, finding all system fonts requires a bit of configuration; see -- 2.39.5