X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fincluded%2Fcompile.itexi;h=896fa0cb3c31c10137310542ce534aa40c6ff728;hb=f2f2ed7bd177ed22334c9d3bc1ab3352050557e7;hp=bdbd4a90f3d7f00277bd1553bf37fdcb03667ab9;hpb=6303df4b6273a87b956453168f37ac3ecaa23e4e;p=lilypond.git diff --git a/Documentation/included/compile.itexi b/Documentation/included/compile.itexi index bdbd4a90f3..896fa0cb3c 100644 --- a/Documentation/included/compile.itexi +++ b/Documentation/included/compile.itexi @@ -7,17 +7,15 @@ @c @n ode Compiling from source @c @s ection Compiling from source - @menu * Overview of compiling:: * Requirements:: * Getting the source code:: -* Configuring @command{make}:: +* Configuring make:: * Compiling LilyPond:: * Post-compilation options:: * Problems:: * Concurrent stable and development versions:: -* Using a Virtual Machine to Compile LilyPond:: * Build system:: @end menu @@ -44,8 +42,8 @@ program. For more information, see @ref{Building documentation without compiling}. Attempts to compile LilyPond natively on Windows have been -unsuccessful, though a workaround is available (see @ref{Using a -Virtual Machine to Compile LilyPond}). +unsuccessful, though a workaround is available (see +@rcontrib{LilyDev}). @node Requirements @@ -62,163 +60,577 @@ Virtual Machine to Compile LilyPond}). @node Requirements for running LilyPond @subsection Requirements for running LilyPond -Running LilyPond requires proper installation of the following -software: +This section contains the list of separate software packages that are +required to run LilyPond. @itemize -@item @uref{http://www.dejavu-fonts.org/, DejaVu fonts} (normally -installed by default) -@item @uref{http://www.fontconfig.org/, FontConfig} (2.2 or newer) +@item @uref{http://www.dejavu-fonts.org/, DejaVu fonts} +These are normally installed by default. -@item @uref{http://www.freetype.org/, Freetype} (2.1.10 or newer) +@item +@uref{http://www.fontconfig.org/, FontConfig} +Use version 2.4.0 or newer. -@item @uref{http://www.ghostscript.com, Ghostscript} (8.60 or -newer) +@item +@uref{http://www.freetype.org/, Freetype} +Use version 2.1.10 or newer. -@item @uref{http://www.gnu.org/software/guile/guile.html, Guile} -(1.8.2 or newer) +@item +@uref{http://www.ghostscript.com, Ghostscript} +Use version 8.60 or newer. -@item @uref{http://www.pango.org/, Pango} (1.12 or newer) +@item +@uref{http://www.gnu.org/software/guile/guile.html, Guile} +Use version 1.8.8. Version 2.x of Guile is not currently supported. -@item @uref{http://www.python.org, Python} (2.4 or newer) -@end itemize +@item +@uref{http://www.pango.org/, Pango} +User version 1.12 or newer. -International fonts are required to create music with -international text or lyrics. +@item +@uref{http://www.python.org, Python} +Use version 2.4 or newer. + +@item +International fonts. For example: + +Fedora: + +@example +fonts-arabic +fonts-hebrew +fonts-ja +fonts-xorg-truetype +taipeifonts +ttfonts-ja +ttfonts-zh_CN +@end example + +Debian based distributions: + +@example +emacs-intl-fonts +fonts-ipafont-gothic +fonts-ipafont-mincho +xfonts-bolkhov-75dpi +xfonts-cronyx-75dpi +xfonts-cronyx-100dpi +xfonts-intl-.* +@end example + +These are normally installed by default and are required only to create +music with international text or lyrics. + +@end itemize @node Requirements for compiling LilyPond @subsection Requirements for compiling LilyPond -Below is a full list of packages needed to build LilyPond. -However, for most common distributions there is an easy way of -installing most all build dependencies in one go: +This section contains instructions on how to quickly and easily get all +the software packages required to build LilyPond. + +Most of the more popular Linux distributions only require a few simple +commands to download all the software needed. For others, there is an +explicit list of all the individual packages (as well as where to get +them from) for those that are not already included in your +distributions' own repositories. + +@ignore +I have tested all of the following four Linux Distributions listed here +Using a simple virtual machine and the appropriate ISO image file +downloaded from each distribution's own website. The instructions +documented were run immediately after the initial installation +(without any further additional configuration to the OS) and I made sure +that I was able to run the full set of make, make test-baseline, make +check and a full make doc. - James +@end ignore + +@menu +* Fedora:: +* Linux Mint:: +* OpenSUSE:: +* Ubuntu:: +* Other:: +@end menu + + +@node Fedora +@unnumberedsubsubsec Fedora + +The following instructions were tested on @q{Fedora} versions 22 & 23 +and will download all the software required to both compile LilyPond and +build the documentation. + +@itemize + +@item +Download and install all the LilyPond build-dependencies (approximately +700MB); + +@example +sudo dnf builddep lilypond --nogpgcheck +@end example + +@item +Download and install additional @q{build} tools required for compiling; + +@example +sudo dnf install autoconf gcc-c++ +@end example + +@item +Download @code{texi2html 1.82} directly from: +@uref{http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz}; + +@code{texi2html} is only required if you intend to compile LilyPond's +own documentation (e.g. to help with any document writing). The version +available in the Fedora repositories is too new and will not work. +Extract the files into an appropriate location and then run the +commands; + +@example +./configure +make +sudo make install +@end example + +This should install @code{texi2html 1.82} into @code{/usr/local/bin}, +which will normally take priority over @code{/usr/bin} where the +later, pre-installed versions gets put. Now verify that your operating +system is able to see the correct version of @code{texi2html}. + +@example +texi2html --version +@end example + +@item +Although not @q{required} to compile LilyPond, if you intend to +contribute to LilyPond (codebase or help improve the documentation) then +it is recommended that you also need to install @code{git}. + +@example +sudo dnf install git +@end example + +Also see @ruser{Starting with Git}. + +@item +To use the @code{lily-git.tcl} GUI; + +@example +sudo dnf install tk +@end example + +See @ruser{lily-git}. + +@end itemize + +@warning{By default, when building LilyPond's documentation, +@code{pdfTeX} is be used. However ligatures (fi, fl, ff etc.) may not +be printed in the PDF output. In this case XeTeX can be used instead. +Download and install the @code{texlive-xetex} package. + +@example +sudo dnf install texlive-xetex +@end example + +The scripts used to build the LilyPond documentation will use +@code{XeTex} instead of @code{pdfTex} to generate the PDF documents if +it is available. No additional configuration is required.} + + + +@node Linux Mint +@unnumberedsubsubsec Linux Mint + +The following instructions were tested on @q{Linux Mint 17.1} and +@q{LMDE - Betsy} and will download all the software required to both +compile LilyPond and build the documentation.. + +@itemize + +@item +Enable the @emph{sources} repository; + +@enumerate + +@item +Using the @emph{Software Sources} GUI (located under +@emph{Administration}). + +@item +Select @emph{Official Repositories}. + +@item +Check the @emph{Enable source code repositories} box under the +@emph{Source Code} section. -@multitable @columnfractions .5 .5 -@headitem Distribution @tab Command -@item Debian, Ubuntu -@tab @code{sudo apt-get build-dep lilypond} +@item +Click the @emph{Update the cache} button and when it has completed, +close the @emph{Software Sources} GUI. -@item Fedora, RHEL -@tab @code{sudo yum-builddep lilypond} +@end enumerate -@item openSUSE, SLED -@c sorry for the idiosyncratic command, I really asked and argued -@c for "zypper build-dep" :-( -@tab @code{sudo zypper --build-deps-only source-install lilypond} -@end multitable +@item +Download and install all the LilyPond build-dependencies (approximately +200MB); + +@example +sudo apt-get build-dep lilypond +@end example + +@item +Download and install additional @q{build} tools required for compiling; + +@example +sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic +@end example + +@item +Although not @q{required} to compile LilyPond, if you intend to +contribute to LilyPond (codebase or help improve the documentation) then +it is recommended that you also need to install @code{git}. + +@example +sudo apt-get install git +@end example + +Also see @ruser{Starting with Git}. + +@item +To use the @code{lily-git.tcl} GUI; + +@example +sudo apt-get install tk +@end example + +Also see @ruser{lily-git}. + +@end itemize + +@warning{By default, when building LilyPond's documentation, +@code{pdfTeX} is be used. However ligatures (fi, fl, ff etc.) may not +be printed in the PDF output. In this case XeTeX can be used instead. +Download and install the @code{texlive-xetex} package. + +@example +sudo apt-get install texlive-xetex +@end example + +The scripts used to build the LilyPond documentation will use +@code{XeTex} instead of @code{pdfTex} to generate the PDF documents if +it is available. No additional configuration is required.} + + +@node OpenSUSE +@unnumberedsubsubsec OpenSUSE + +The following instructions were tested on @q{OpenSUSE 13.2} and will +download all the software required to both compile LilyPond and build +the documentation. @itemize -@item Everything listed in @ref{Requirements for running -LilyPond} -@item Development packages for the above items (which should -include header files and libraries). +@item +Add the @emph{sources} repository; + +@smallexample +sudo zypper addrepo -f \ +"http://download.opensuse.org/source/distribution/13.2/repo/oss/" sources +@end smallexample + +@item +Download and install all the LilyPond build-dependencies (approximately +680MB); + +@example +sudo zypper source-install lilypond +@end example -Red Hat Fedora: +@item +Download and install additional @q{build} tools required for compiling; -@c ghostscript-devel-[version] isn't needed @example -guile-devel-@var{version} -fontconfig-devel-@var{version} -freetype-devel-@var{version} -pango-devel-@var{version} -python-devel-@var{version} +sudo zypper install make @end example -Debian GNU/Linux: +@item +Although not @q{required} to compile LilyPond, if you intend to +contribute to LilyPond (codebase or help improve the documentation) then +it is recommended that you also need to install @code{git}. -@c libgs-dev isn't needed @example -guile-@var{version}-dev -libfontconfig1-dev -libfreetype6-dev -libpango1.0-dev -python@var{version}-dev +sudo zypper install git @end example -@item @uref{http://flex.sourceforge.net/, Flex} +Also see @ruser{Starting with Git}. -@item @uref{http://fontforge.sf.net/, FontForge} (20060125 or -newer) +@item +To use the @code{lily-git.tcl} GUI; + +@example +sudo zypper install tk +@end example + +Also see @ruser{lily-git}. -@item @uref{http://www.gnu.org/software/bison/, GNU Bison} +@end itemize -@item @uref{http://gcc.gnu.org/, GNU Compiler Collection} (3.4 or -newer, 4.@var{x} recommended) +@warning{By default, when building LilyPond's documentation, +@code{pdfTeX} is be used. However ligatures (fi, fl, ff etc.) may not +be printed in the PDF output. In this case XeTeX can be used instead. +Download and install the @code{texlive-xetex} package. -@item @uref{http://www.gnu.org/software/gettext/gettext.html, GNU -gettext} (0.17 or newer) +@example +sudo zypper install texlive-xetex +@end example + +The scripts used to build the LilyPond documentation will use +@code{XeTex} instead of @code{pdfTex} to generate the PDF documents if +it is available. No additional configuration is required.} + +@node Ubuntu +@unnumberedsubsubsec Ubuntu + +The following commands were tested on Ubuntu versions @code{14.04 LTS}, +@code{14.10} and @code{15.04} and will download all the software +required to both compile LilyPond and build the documentation. + +@itemize + +@item +Download and install all the LilyPond build-dependencies (approximately +200MB); + +@example +sudo apt-get build-dep lilypond +@end example + +@item +Download and install additional @q{build} tools required for compiling; + +@example +sudo apt-get install autoconf fonts-texgyre texlive-land-cyrillic +@end example + +@item +Although not @q{required} to compile LilyPond, if you intend to +contribute to LilyPond (codebase or help improve the documentation) then +it is recommended that you also need to install @code{git}. + +@example +sudo apt-get install git +@end example + +Also see @ruser{Starting with Git}. + +@item +To use the @code{lily-git.tcl} GUI; + +@example +sudo apt-get install tk +@end example + +Also see @ruser{lily-git}. + +@end itemize + +@warning{By default, when building LilyPond's documentation, +@code{pdfTeX} is be used. However ligatures (fi, fl, ff etc.) may not +be printed in the PDF output. In this case XeTeX can be used instead. +Download and install the @code{texlive-xetex} package. + +@example +sudo apt-get install texlive-xetex +@end example + +The scripts used to build the LilyPond documentation will use +@code{XeTex} instead of @code{pdfTex} to generate the PDF documents if +it is available. No additional configuration is required.} + + +@node Other +@unnumberedsubsubsec Other + +The following individual software packages are required just to compile +LilyPond. + +@itemize + +@item +@uref{http://www.gnu.org/software/autoconf, GNU Autoconf} + +@item +@uref{http://www.gnu.org/software/bison/, GNU Bison} + +Use version @code{2.0} or newer. + +@item +@uref{http://gcc.gnu.org/, GNU Compiler Collection} -@item @uref{http://www.gnu.org/software/make/, GNU Make} (3.78 or -newer) +Use version @code{3.4} or newer (@code{4.x} recommended). -@item @uref{http://metafont.tutorial.free.fr/, MetaFont} -(mf-nowin, mf, mfw or mfont binaries), usually packaged with +@item +@uref{http://flex.sourceforge.net/, Flex} + +@item +@uref{http://fontforge.sf.net/, FontForge} + +Use version @code{20060125} or newer (we recommend using at least +@code{20100501}); it must also be compiled with the +@option{--enable-double} switch, else this can lead to inaccurate +intersection calculations which end up with poorly-rendered glyphs in +the output. + +@item +@uref{http://www.gnu.org/software/gettext/gettext.html, GNU gettext} + +Use version @code{0.17} or newer. + +@item +@uref{http://www.gnu.org/software/make/, GNU Make} + +Use version @code{3.78} or newer. + +@item +@uref{http://metafont.tutorial.free.fr/, MetaFont} + +The @code{mf-nowin}, @code{mf}, @code{mfw} or @code{mfont} binaries are +usually packaged along with @uref{http://www.latex-project.org/ftp.html, @TeX{}}. -@item @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html, -MetaPost} (mpost binary), usually packaged with +@item +@uref{http://cm.bell-labs.com/who/hobby/MetaPost.html, MetaPost} + +The @code{mpost} binary is also usually packaged with @uref{http://www.latex-project.org/ftp.html, @TeX{}}. -@item @uref{http://www.perl.org/, Perl} +@item +@uref{http://www.perl.org/, Perl} + +@item +@uref{http://www.gnu.org/software/texinfo/, Texinfo} + +Use version @code{4.11} or newer. -@item @uref{http://www.gnu.org/software/texinfo/, Texinfo} (4.11 -or newer) +@item +@uref{http://www.lcdf.org/~eddietwo/type/#t1utils, Type 1 utilities} + +Use version @code{1.33} or newer. + +@item +@uref{https://www.ctan.org/pkg/cyrillic?lang=en, Cyrillic fonts} + +Often packaged in repositories as @code{texlive-lang-cyrillic}. + +@item +TeX Gyre @q{OTF} font packages. As of LilyPond version @code{2.19.26}, +the previous default serif, san serif and monospace fonts now use Tex +Gyre's @emph{Schola}, @emph{Heros} and @emph{Cursor} fonts respectively. +Also See @ruser{Fonts}. + +Some distributions do not always provide @q{OTF} font files in the Tex +Gyre packages from their repositories. Use the command +@code{fc-list | grep texgyre} to list the fonts available to your system +and check that the appropriate @code{*.otf} files are reported. If they +are not then download and manually extract the @q{OTF} files to either +your local @code{~/.fonts/} directory or use the +@code{configure} command and the +@code{--with-texgyre-dir=/path_to_otf_files/} option. + +The following font families are required: + +@uref{http://www.gust.org.pl/projects/e-foundry/tex-gyre/schola, Schola}, +@uref{http://www.gust.org.pl/projects/e-foundry/tex-gyre/heros, Heros} +and +@uref{http://www.gust.org.pl/projects/e-foundry/tex-gyre/cursor, Cursor}. -@item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils, Type 1 -utilities} (1.33 or newer recommended) @end itemize + @node Requirements for building documentation @subsection Requirements for building documentation -You can view the documentation online at -@uref{http://www.lilypond.org/doc/}, but you can also build it -locally. This process requires some additional tools and -packages: +The entire set of documentation for the most current build of LilyPond +is available online at +@uref{http://lilypond.org/doc/v2.19/Documentation/web/development}, but +you can also build them locally from the source code. This process +requires some additional tools and packages. + +@warning{If the instructions for one of the previously listed Linux +in the previous section (@rcontrib{Requirements for compiling LilyPond}) +have been used, then the following can be ignored as the software should +already be installed.} @itemize -@item Everything listed in @ref{Requirements for compiling -LilyPond} -@item @uref{http://www.imagemagick.org/, ImageMagick} +@item +Everything listed in @ref{Requirements for compiling LilyPond} + +@item +@uref{http://www.imagemagick.org/, ImageMagick} + +@item +@uref{http://netpbm.sourceforge.net/, Netpbm} + +@item +@uref{http://gzip.org/, gzip} -@item @uref{http://netpbm.sourceforge.net/, Netpbm} +@item +@uref{http://rsync.samba.org/, rsync} -@item @uref{http://rsync.samba.org/, rsync} +@item +@uref{http://www.nongnu.org/texi2html/, Texi2HTML} -@item @uref{http://www.nongnu.org/texi2html/, Texi2HTML} (1.82) +Use version @code{1.82}. Later versions will not work. -@item International fonts +Download @code{texi2html 1.82} directly from: +@uref{http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz}; -Red Hat Fedora: +Extract the files into an appropriate location and then run the +commands; @example -fonts-arabic -fonts-hebrew -fonts-ja -fonts-xorg-truetype -taipeifonts -ttfonts-ja -ttfonts-zh_CN +./configure +make +sudo make install @end example -Debian GNU/Linux: +Now verify that your operating system is able to see the correct version +of @code{texi2html}. @example -emacs-intl-fonts -ttf-kochi-gothic -ttf-kochi-mincho -xfonts-bolkhov-75dpi -xfonts-cronyx-75dpi -xfonts-cronyx-100dpi -xfonts-intl-.* +texi2html --version +@end example + +@item +Fonts required to build the documentation in addition to those required +to run LilyPond: + +@example +gsfonts +fonts-linuxlibertine +fonts-liberation +fonts-dejavu +fonts-freefont-otf +ttf-bitstream-vera +texlive-fonts-recommended +ttf-xfree86-nonfree @end example + @end itemize +@warning{By default, when building LilyPond's documentation, +@code{pdfTeX} is be used. However ligatures (fi, fl, ff etc.) may not +be printed in the PDF output. In this case XeTeX can be used instead. +Download and install the @code{texlive-xetex} package. The scripts used +to build the LilyPond documentation will use @code{XeTex} instead of +@code{pdfTex} to generate the PDF documents if it is available. No +additional configuration is required.} + @node Getting the source code @section Getting the source code @@ -234,9 +646,15 @@ repository. Setting up a local Git repository is explained in @subheading Downloading a source tarball Packagers are encouraged to use source tarballs for compiling. + The tarball for the latest stable release is available on the @rweb{Source} page. +@noindent +The latest +@uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot, source code snapshot} +is also available as a tarball from the GNU Savannah Git server. + @noindent All tagged releases (including legacy stable versions and the most recent development release) are available @@ -265,18 +683,22 @@ This creates a subdirectory within the current directory called @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 +download and install the free-software +@uref{http://www.7-zip.org, 7zip archiver} to extract the tarball. -@node Configuring @command{make} + +@node Configuring make @section Configuring @command{make} @menu -* Running @command{./autogen.sh}:: -* Running @command{./configure}:: +* Running ./autogen.sh:: +* Running ../configure:: @end menu -@node Running @command{./autogen.sh} +@node Running ./autogen.sh @subsection Running @command{./autogen.sh} After you unpack the tarball (or download the Git repository), the @@ -288,50 +710,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: - -@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 @command{./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} @@ -347,7 +784,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 @@ -357,22 +794,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}'. +using `@option{--prefix}', for instance `@option{--prefix=$HOME}'. @end quotation 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 @@ -389,43 +829,29 @@ 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 @menu -* Using @command{make}:: -* Saving time with the @option{-j} option:: +* Using make:: +* Saving time with the -j option:: * Compiling for multiple platforms:: -* Useful @command{make} variables:: +* Useful make variables:: @end menu -@node Using @command{make} +@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: @@ -442,8 +868,12 @@ 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 @option{-j} option +@node Saving time with the -j option @subsection Saving time with the @option{-j} option If your system has multiple CPUs, you can speed up compilation by @@ -458,15 +888,18 @@ make -j3 If you get errors using the @option{-j} option, and @samp{make} succeeds without it, try lowering the @code{@var{X}} value. +Because multiple jobs run in parallel when @option{-j} is used, it can +be difficult to determine the source of an error when one occurs. In +that case, running @samp{make} without the @option{-j} is advised. @node Compiling for multiple platforms @subsection Compiling for multiple platforms 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 @@ -496,7 +929,7 @@ make conf=prof install @ref{Installing LilyPond from a local build} -@node Useful @command{make} variables +@node Useful make variables @subsection Useful @command{make} variables If a less verbose build output if desired, the variable @@ -511,7 +944,7 @@ command line, or in @file{local.make} at top of the build tree. @menu * Installing LilyPond from a local build:: * Generating documentation:: -* Testing LilyPond:: +* Testing LilyPond binary:: @end menu @@ -539,7 +972,7 @@ sudo make install @end example @noindent -or... +or@dots{} @example su -c 'make install' @@ -557,7 +990,9 @@ re-install. See @ref{Configuring target directories}. @menu * Documentation editor's edit/compile cycle:: * Building documentation:: -* Saving time with @code{CPU_COUNT}:: +* Building a single document:: +* Saving time with CPU_COUNT:: +* AJAX search:: * Installing documentation:: * Building documentation without compiling:: @end menu @@ -572,28 +1007,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 @@ -606,11 +1048,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 @@ -621,58 +1072,72 @@ 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. -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: + +@example +make LANGS='' doc +@end example -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: +@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 @code{CPU_COUNT} +@node Saving time with CPU_COUNT @unnumberedsubsubsec Saving time with @code{CPU_COUNT} The most time consuming task for building the documentation is @@ -701,6 +1166,23 @@ it is possible for @samp{make -j5 CPU_COUNT=5 doc} to work consistently even if @samp{make -j5} rarely succeeds. +@node AJAX search +@unnumberedsubsubsec AJAX search + +To build the documentation with interactive searching, use: + +@example +make doc AJAX_SEARCH=1 +@end example + +This requires PHP, and you must view the docs via a http +connection (you cannot view them on your local filesystem). + +@warning{Due to potential security or load issues, this option is +not enabled in the official documentation builds. Enable at your +own risk.} + + @node Installing documentation @unnumberedsubsubsec Installing documentation @@ -822,93 +1304,25 @@ exec /opt/local/bin/pngtopnm "$@" @end verbatim -@node Testing LilyPond -@subsection Testing LilyPond +@node Testing LilyPond binary +@subsection Testing LilyPond binary LilyPond comes with an extensive suite that exercises the entire -program. This suite can be used to automatically check the impact -of a change. - -@menu -* Developer's edit/compile/test cycle:: -* Other tests:: -@end menu - -@node Developer's edit/compile/test cycle -@unnumberedsubsubsec Developer's edit/compile/test cycle - -TODO: is @code{[-j@var{X} CPU_COUNT=@var{X}]} useful for -@code{test-baseline}, @code{check}, @code{clean}, -@code{test-redo}? - -@itemize -@item -Initial test: - -@example -make [-j@var{X}] -make test-baseline -make [-j@var{X} CPU_COUNT=@var{X}] check -@end example - -@item -Edit/compile/test cycle: - -@example -@emph{## edit source files, then...} - -make clean @emph{## only if needed (see below)} -make [-j@var{X}] @emph{## only if needed (see below)} -make test-redo @emph{## redo files differing from baseline} -make [-j@var{X} CPU_COUNT=@var{X}] check @emph{## CPU_COUNT here?} -@end example - -@item -Reset: - -@example -make test-clean -@end example -@end itemize - -If you modify any source files that have to be compiled (such as -@file{.cc} or @file{.hh} files in @file{flower/} or @file{lily/}), -then you must run @command{make} before @command{make test-redo}, -so @command{make} can compile the modified files and relink all -the object files. If you only modify files which are interpreted, -like those in the @file{scm/} and @file{ly/} directories, then -@command{make} is not needed before @command{make test-redo}. - -Also, if you modify any font definitions in the @file{mf/} -directory then you must run @command{make clean} and -@command{make} before running @command{make test-redo}. This will -recompile everything, whether modified or not, and takes a lot -longer. +program. This suite can be used to test that the binary has +been built correctly. -Running @command{make@tie{}check} 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. +The test suite can be executed with: +@verbatim +make test +@end verbatim -@node Other tests -@unnumberedsubsubsec Other tests - -For tracking memory usage as part of this test, you will need -GUILE CVS; especially the following patch: -@uref{http://www.lilypond.org/vc/old/gub.darcs/patches/guile-1.9-gcstats.patch}. - -For checking the coverage of the test suite, do the following - -@example -./scripts/auxiliar/build-coverage.sh -@emph{# uncovered files, least covered first} -./scripts/auxiliar/coverage.py --summary out-cov/*.cc -@emph{# consecutive uncovered lines, longest first} -./scripts/auxiliar/coverage.py --uncovered out-cov/*.cc -@end example +If the test suite completes successfully, the LilyPond binary +has been verified. +More information on the regression test suite is found at +@rcontrib{Regression tests}. @node Problems @section Problems @@ -918,22 +1332,8 @@ bug reports to @email{bug-lilypond@@gnu.org}. Bugs that are not fault of LilyPond are documented here. -@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 - -@example -$ cd lily; make out/parser.cc -$ vi +4919 out/parser.cc -# append a semicolon to the line containing "__attribute__ ((__unused__)) -# save -$ 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 @@ -943,16 +1343,15 @@ been tested using OS X 10.5 (Leopard). First, install the relevant dependencies using MacPorts. Next, add the following to your relevant shell initialization -files. This is @code{~/.profile} by default. You should create +files. This is @code{~/.profile} by default. You should create this file if it does not exist. @example export PATH=/opt/local/bin:/opt/local/sbin:$PATH -export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:\ -$DYLD_FALLBACK_LIBRARY_PATH +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 @@ -966,7 +1365,7 @@ FLEXLEXER_FILE = /opt/local/include/FlexLexer.h @end example At this point, you should verify that you have the appropriate -fonts installed with your ghostscript installation. Check @code{ls +fonts installed with your ghostscript installation. Check @code{ls /opt/local/share/ghostscript/fonts} for: 'c0590*' files (.pfb, .pfb and .afm). If you don't have them, run the following commands to grab them from the ghostscript SVN server and install @@ -978,15 +1377,15 @@ sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/ rm -rf urw-fonts-1.07pre44 @end example -Now run the @code{./configure} script. To avoid complications with +Now run the @code{./configure} script. To avoid complications with automatic font detection, add @example ---with-ncsb-dir=/opt/local/share/ghostscript/fonts +--with-fonts-dir=/opt/local/share/ghostscript/fonts @end example -@unnumberedsubsubsec Solaris +@unnumberedsubsec Solaris Solaris7, ./configure @@ -1005,7 +1404,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}. @@ -1019,7 +1418,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 @@ -1041,17 +1440,17 @@ Red Hat Fedora Debian GNU/Linux apt-get install emacs-intl-fonts xfonts-intl-.* \ - ttf-kochi-gothic ttf-kochi-mincho \ + fonts-ipafont-gothic fonts-ipafont-mincho \ xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi @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. @@ -1062,9 +1461,9 @@ installation directory structure. It can be useful to have both the stable and the development versions -of Lilypond available at once. One way to do this on GNU/Linux is to +of Lilypond available at once. One way to do this on GNU/Linux is to install the stable version using the precompiled binary, and run the -development version from the source tree. After running @command{make +development version from the source tree. After running @command{make all} from the top directory of the Lilypond source files, there will be a binary called @code{lilypond} in the @code{out} directory: @@ -1073,7 +1472,7 @@ be a binary called @code{lilypond} in the @code{out} directory: @end example This binary can be run without actually doing the @code{make -install} command. The advantage to this is that you can have all +install} command. The advantage to this is that you can have all of the latest changes available after pulling from git and running @code{make all}, without having to uninstall the old version and reinstall the new. @@ -1112,119 +1511,6 @@ TODO: ADD - other compilation tricks for developers -@node Using a Virtual Machine to Compile LilyPond -@section Using a Virtual Machine to Compile LilyPond - - -TODO: rewrite for lily-git.tcl !!! do before GOP! -gp - -Since it is not possible to compile Lilypond on Windows, some -developers may find it useful to install a GNU/Linux virtual -machine. A disk image with a special remix of @strong{Ubuntu} -has been created for this purpose. It has all of the Lilypond -build dependencies in place, so that once installed, it is -ready to compile both Lilypond and the Documentation. -The @code{lilybuntu} remix is available for download here: - -@example -@uref{http://@/files.lilynet.net/@/lilybuntu.iso} -@end example - -We do not necessarily recommend any one virtualization tool, -however the @code{lilybuntu} remix is known to work well on -@uref{http://www.virtualbox.org/wiki/Downloads, Sun VirtualBox}, -which is a free download. Consult your virtualization software's -documentation for instructions on setting up the software and -for general instructions on installing a virtual machine. - -Steps to setting up @code{lilybuntu} in a virtual machine: - -@enumerate -@item Download the @code{lilybuntu} disk image. - -@item Install @code{lilybuntu}. You will use the @code{.iso} -file as the boot disk. It should not be necessary to burn it -to a DVD, but consult the documentation for your virtualization -software for specific instructions. If possible, use at least -the recommended amount of RAM for the virtual machine (384 MB on -VirtualBox), and use a dynamically expanding virtual hard drive. -A virtual hard drive with 6 GB will be enough to compile LilyPond, -but if you intend to build the docs and run the regression tests -the virtual hard drive should be at least 10 GB. -The Ubuntu installation should be straightforward, although in the -partitioning stage do not be afraid to select @qq{use entire disk,} -since this is only your @strong{virtual disk} and not your -machine's actual hard drive. - -@item After installation is complete, restart the virtual -machine. If you are using @strong{VirtualBox}, you may wish -to install the @qq{Guest Additions}, which while not essential for -compiling @code{Lilypond} will allow you to use the virtual machine -in full screen, Seamless mode (also known as Unity mode on other -virtualization platforms) and allow you to share clipboards between -the physical and virtual machine. From the @code{Devices} menu select -@code{Install Guest Additions...}, the @code{VBOXADDITIONS} CDROM device -will appear on the desktop. Open a @strong{terminal} session. -(@code{Applications > Accessories > Terminal}) and @code{cd} to the -top level of the CDROM. Run the @code{autorun.sh} script as superuser -(@code{sudo ./autorun.sh }), a console window will open while the -@qq{Guest Additions} are being installed. Once the script has -been finished, reboot your Virtual Machine to complete the installation -of the @qq{Guest Additions}. - -@item Open a @strong{terminal} session. -(@code{Applications > Accessories > Terminal}) - -@item Open @strong{Firefox} (there's an icon for it on the -panel at the top of the screen) and go to the online Lilypond -@uref{http://lilypond.org/doc/latest/Documentation/contributor/, -Contributor's Guide}. - -@item To retrieve the Lilypond source code from @code{git}, -copy-and-paste each command from the CG @qq{Main source code} -section into the terminal. (paste into the terminal with keystroke -@code{CTRL+SHIFT+V}) - -@item Prepare to build Lilypond by running the configuration script. -Type - -@example -./autogen.sh -@end example - -When it is finished you should be presented -with the three most common @code{make} options: - -@example -Type: - make all to build LilyPond - make install to install LilyPond - make help to see all possible targets - -Edit local.make for local Makefile overrides. -@end example - -@item First type @code{make all} to build Lilypond. This will take -a while. - -@item When Lilypond is finished building, build the documentation -by typing - -@example -make doc -@end example - -Depending on your system specs it could take from 30-60 minutes -to finish. - -@end enumerate - -At this point everything has been compiled. -You may install Lilypond using @code{make install}, or you may wish -to set up your system with concurrent stable and development -versions as described in the previous section. - - @node Build system @section Build system @@ -1233,7 +1519,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 macors +@subheading Version-specific texinfo macros @itemize @@ -1243,7 +1529,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 website.make, used on lilypond.org) +website (made with @file{website.make}, used on lilypond.org) @item not (?) used in the main docs?