1 @c -*- coding: utf-8; mode: texinfo; -*-
4 @c DO NOT TRANSLATE THIS FILE
6 @c include any node/sections from the higher-level *texi file.
7 @c @n ode Compiling from source
8 @c @s ection Compiling from source
11 * Overview of compiling::
13 * Getting the source code::
15 * Compiling LilyPond::
16 * Post-compilation options::
18 * Concurrent stable and development versions::
23 @node Overview of compiling
24 @section Overview of compiling
26 Compiling LilyPond from source is an involved process, and is only
27 recommended for developers and packagers. Typical program users
28 are instead encouraged to obtain the program from a package
29 manager (on Unix) or by downloading a precompiled binary
30 configured for a specific operating system. Pre-compiled binaries
31 are available on the @rweb{Download} page.
33 Compiling LilyPond from source is necessary if you want to build,
34 install, or test your own version of the program.
36 A successful compile can also be used to generate and install the
37 documentation, incorporating any changes you may have made.
38 However, a successful compile is not a requirement for generating
39 the documentation. The documentation can be built using a Git
40 repository in conjunction with a locally installed copy of the
41 program. For more information, see @ref{Building documentation
44 Attempts to compile LilyPond natively on Windows have been
45 unsuccessful, though a workaround is available (see
54 * Requirements for running LilyPond::
55 * Requirements for compiling LilyPond::
56 * Requirements for building documentation::
60 @node Requirements for running LilyPond
61 @subsection Requirements for running LilyPond
63 This section contains the list of separate software packages that are
64 required to run LilyPond.
68 @item @uref{http://www.dejavu-fonts.org/, DejaVu fonts}
69 These are normally installed by default.
72 @uref{http://www.fontconfig.org/, FontConfig}
73 Use version 2.4.0 or newer.
76 @uref{http://www.freetype.org/, Freetype}
77 Use version 2.1.10 or newer.
80 @uref{http://www.ghostscript.com, Ghostscript}
81 Use version 8.60 or newer.
84 @uref{http://www.gnu.org/software/guile/guile.html, Guile}
85 Use version 1.8.8. Version 2.x of Guile is not currently supported.
88 @uref{http://www.pango.org/, Pango}
89 User version 1.12 or newer.
92 @uref{http://www.python.org, Python}
93 Use version 2.4 or newer.
96 International fonts. For example:
110 Debian based distributions:
122 These are normally installed by default and are required only to create
123 music with international text or lyrics.
128 @node Requirements for compiling LilyPond
129 @subsection Requirements for compiling LilyPond
131 This section contains instructions on how to quickly and easily get all
132 the software packages required to build LilyPond.
134 Most of the more popular Linux distributions only require a few simple
135 commands to download all the software needed. For others, there is an
136 explicit list of all the individual packages (as well as where to get
137 them from) for those that are not already included in your
138 distributions' own repositories.
141 I have tested all of the following four Linux Distributions listed here
142 Using a simple virtual machine and the appropriate ISO image file
143 downloaded from each distribution's own website. The instructions
144 documented were run immediately after the initial installation
145 (without any further additional configuration to the OS) and I made sure
146 that I was able to run the full set of make, make test-baseline, make
147 check and a full make doc. - James
160 @unnumberedsubsubsec Fedora
162 The following instructions were tested on @q{Fedora} versions 22 & 23
163 and will download all the software required to both compile LilyPond and
164 build the documentation.
169 Download and install all the LilyPond build-dependencies (approximately
173 sudo dnf builddep lilypond --nogpgcheck
177 Download and install additional @q{build} tools required for compiling;
180 sudo dnf install autoconf gcc-c++
184 Download @code{texi2html 1.82} directly from:
185 @uref{http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz};
187 @code{texi2html} is only required if you intend to compile LilyPond's
188 own documentation (e.g. to help with any document writing). The version
189 available in the Fedora repositories is too new and will not work.
190 Extract the files into an appropriate location and then run the
199 This should install @code{texi2html 1.82} into @code{/usr/local/bin},
200 which will normally take priority over @code{/usr/bin} where the
201 later, pre-installed versions gets put. Now verify that your operating
202 system is able to see the correct version of @code{texi2html}.
209 Although not @q{required} to compile LilyPond, if you intend to
210 contribute to LilyPond (codebase or help improve the documentation) then
211 it is recommended that you also need to install @code{git}.
217 Also see @rcontrib{Starting with Git}.
220 To use the @code{lily-git.tcl} GUI;
226 See @rcontrib{lily-git}.
230 @warning{By default, when building LilyPond's documentation,
231 @code{pdfTeX} is be used. However ligatures (fi, fl, ff etc.) may not
232 be printed in the PDF output. In this case XeTeX can be used instead.
233 Download and install the @code{texlive-xetex} package.
236 sudo dnf install texlive-xetex
239 The scripts used to build the LilyPond documentation will use
240 @code{XeTex} instead of @code{pdfTex} to generate the PDF documents if
241 it is available. No additional configuration is required.}
246 @unnumberedsubsubsec Linux Mint
248 The following instructions were tested on @q{Linux Mint 17.1} and
249 @q{LMDE - Betsy} and will download all the software required to both
250 compile LilyPond and build the documentation..
255 Enable the @emph{sources} repository;
260 Using the @emph{Software Sources} GUI (located under
261 @emph{Administration}).
264 Select @emph{Official Repositories}.
267 Check the @emph{Enable source code repositories} box under the
268 @emph{Source Code} section.
271 Click the @emph{Update the cache} button and when it has completed,
272 close the @emph{Software Sources} GUI.
277 Download and install all the LilyPond build-dependencies (approximately
281 sudo apt-get build-dep lilypond
285 Download and install additional @q{build} tools required for compiling;
288 sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
292 Although not @q{required} to compile LilyPond, if you intend to
293 contribute to LilyPond (codebase or help improve the documentation) then
294 it is recommended that you also need to install @code{git}.
297 sudo apt-get install git
300 Also see @rcontrib{Starting with Git}.
303 To use the @code{lily-git.tcl} GUI;
306 sudo apt-get install tk
309 Also see @rcontrib{lily-git}.
313 @warning{By default, when building LilyPond's documentation,
314 @code{pdfTeX} is be used. However ligatures (fi, fl, ff etc.) may not
315 be printed in the PDF output. In this case XeTeX can be used instead.
316 Download and install the @code{texlive-xetex} package.
319 sudo apt-get install texlive-xetex
322 The scripts used to build the LilyPond documentation will use
323 @code{XeTex} instead of @code{pdfTex} to generate the PDF documents if
324 it is available. No additional configuration is required.}
328 @unnumberedsubsubsec OpenSUSE
330 The following instructions were tested on @q{OpenSUSE 13.2} and will
331 download all the software required to both compile LilyPond and build
337 Add the @emph{sources} repository;
340 sudo zypper addrepo -f \
341 "http://download.opensuse.org/source/distribution/13.2/repo/oss/" sources
345 Download and install all the LilyPond build-dependencies (approximately
349 sudo zypper source-install lilypond
353 Download and install additional @q{build} tools required for compiling;
356 sudo zypper install make
360 Although not @q{required} to compile LilyPond, if you intend to
361 contribute to LilyPond (codebase or help improve the documentation) then
362 it is recommended that you also need to install @code{git}.
365 sudo zypper install git
368 Also see @rcontrib{Starting with Git}.
371 To use the @code{lily-git.tcl} GUI;
374 sudo zypper install tk
377 Also see @rcontrib{lily-git}.
381 @warning{By default, when building LilyPond's documentation,
382 @code{pdfTeX} is be used. However ligatures (fi, fl, ff etc.) may not
383 be printed in the PDF output. In this case XeTeX can be used instead.
384 Download and install the @code{texlive-xetex} package.
387 sudo zypper install texlive-xetex
390 The scripts used to build the LilyPond documentation will use
391 @code{XeTex} instead of @code{pdfTex} to generate the PDF documents if
392 it is available. No additional configuration is required.}
395 @unnumberedsubsubsec Ubuntu
397 The following commands were tested on Ubuntu versions @code{14.04 LTS},
398 @code{14.10} and @code{15.04} and will download all the software
399 required to both compile LilyPond and build the documentation.
404 Download and install all the LilyPond build-dependencies (approximately
408 sudo apt-get build-dep lilypond
412 Download and install additional @q{build} tools required for compiling;
415 sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
419 Although not @q{required} to compile LilyPond, if you intend to
420 contribute to LilyPond (codebase or help improve the documentation) then
421 it is recommended that you also need to install @code{git}.
424 sudo apt-get install git
427 Also see @rcontrib{Starting with Git}.
430 To use the @code{lily-git.tcl} GUI;
433 sudo apt-get install tk
436 Also see @rcontrib{lily-git}.
440 @warning{By default, when building LilyPond's documentation,
441 @code{pdfTeX} is be used. However ligatures (fi, fl, ff etc.) may not
442 be printed in the PDF output. In this case XeTeX can be used instead.
443 Download and install the @code{texlive-xetex} package.
446 sudo apt-get install texlive-xetex
449 The scripts used to build the LilyPond documentation will use
450 @code{XeTex} instead of @code{pdfTex} to generate the PDF documents if
451 it is available. No additional configuration is required.}
455 @unnumberedsubsubsec Other
457 The following individual software packages are required just to compile
463 @uref{http://www.gnu.org/software/autoconf, GNU Autoconf}
466 @uref{http://www.gnu.org/software/bison/, GNU Bison}
468 Use version @code{2.0} or newer.
471 @uref{http://gcc.gnu.org/, GNU Compiler Collection}
473 Use version @code{3.4} or newer (@code{4.x} recommended).
476 @uref{http://flex.sourceforge.net/, Flex}
479 @uref{http://fontforge.sf.net/, FontForge}
481 Use version @code{20060125} or newer (we recommend using at least
482 @code{20100501}); it must also be compiled with the
483 @option{--enable-double} switch, else this can lead to inaccurate
484 intersection calculations which end up with poorly-rendered glyphs in
488 @uref{http://www.gnu.org/software/gettext/gettext.html, GNU gettext}
490 Use version @code{0.17} or newer.
493 @uref{http://www.gnu.org/software/make/, GNU Make}
495 Use version @code{3.78} or newer.
498 @uref{http://metafont.tutorial.free.fr/, MetaFont}
500 The @code{mf-nowin}, @code{mf}, @code{mfw} or @code{mfont} binaries are
501 usually packaged along with
502 @uref{http://www.latex-project.org/ftp.html, @TeX{}}.
505 @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html, MetaPost}
507 The @code{mpost} binary is also usually packaged with
508 @uref{http://www.latex-project.org/ftp.html, @TeX{}}.
511 @uref{http://www.perl.org/, Perl}
514 @uref{http://www.gnu.org/software/texinfo/, Texinfo}
516 Use version @code{4.11} or newer.
519 @uref{http://www.lcdf.org/~eddietwo/type/#t1utils, Type 1 utilities}
521 Use version @code{1.33} or newer.
524 @uref{https://www.ctan.org/pkg/cyrillic?lang=en, Cyrillic fonts}
526 Often packaged in repositories as @code{texlive-lang-cyrillic}.
529 TeX Gyre @q{OTF} font packages. As of LilyPond version @code{2.19.26},
530 the previous default serif, san serif and monospace fonts now use Tex
531 Gyre's @emph{Schola}, @emph{Heros} and @emph{Cursor} fonts respectively.
532 Also See @ruser{Fonts}.
534 Some distributions do not always provide @q{OTF} font files in the Tex
535 Gyre packages from their repositories. Use the command
536 @code{fc-list | grep texgyre} to list the fonts available to your system
537 and check that the appropriate @code{*.otf} files are reported. If they
538 are not then download and manually extract the @q{OTF} files to either
539 your local @code{~/.fonts/} directory or use the
540 @code{configure} command and the
541 @code{--with-texgyre-dir=/path_to_otf_files/} option.
543 The following font families are required:
545 @uref{http://www.gust.org.pl/projects/e-foundry/tex-gyre/schola, Schola},
546 @uref{http://www.gust.org.pl/projects/e-foundry/tex-gyre/heros, Heros}
548 @uref{http://www.gust.org.pl/projects/e-foundry/tex-gyre/cursor, Cursor}.
554 @node Requirements for building documentation
555 @subsection Requirements for building documentation
557 The entire set of documentation for the most current build of LilyPond
558 is available online at
559 @uref{http://lilypond.org/doc/v2.19/Documentation/web/development}, but
560 you can also build them locally from the source code. This process
561 requires some additional tools and packages.
563 @warning{If the instructions for one of the previously listed Linux
564 in the previous section (@rcontrib{Requirements for compiling LilyPond})
565 have been used, then the following can be ignored as the software should
566 already be installed.}
571 Everything listed in @ref{Requirements for compiling LilyPond}
574 @uref{http://www.imagemagick.org/, ImageMagick}
577 @uref{http://netpbm.sourceforge.net/, Netpbm}
580 @uref{http://gzip.org/, gzip}
583 @uref{http://rsync.samba.org/, rsync}
586 @uref{http://www.nongnu.org/texi2html/, Texi2HTML}
588 Use version @code{1.82}. Later versions will not work.
590 Download @code{texi2html 1.82} directly from:
591 @uref{http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz};
593 Extract the files into an appropriate location and then run the
602 Now verify that your operating system is able to see the correct version
610 Fonts required to build the documentation in addition to those required
620 texlive-fonts-recommended
626 @warning{By default, when building LilyPond's documentation,
627 @code{pdfTeX} is be used. However ligatures (fi, fl, ff etc.) may not
628 be printed in the PDF output. In this case XeTeX can be used instead.
629 Download and install the @code{texlive-xetex} package. The scripts used
630 to build the LilyPond documentation will use @code{XeTex} instead of
631 @code{pdfTex} to generate the PDF documents if it is available. No
632 additional configuration is required.}
635 @node Getting the source code
636 @section Getting the source code
639 @subheading Downloading the Git repository
641 In general, developers compile LilyPond from within a local Git
642 repository. Setting up a local Git repository is explained in
643 @rcontrib{Starting with Git}.
646 @subheading Downloading a source tarball
648 Packagers are encouraged to use source tarballs for compiling.
650 The tarball for the latest stable release is available on the
655 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot, source code snapshot}
656 is also available as a tarball from the GNU Savannah Git server.
659 All tagged releases (including legacy stable
660 versions and the most recent development release) are available
664 @uref{http://download.linuxaudio.org/lilypond/source/}
667 Download the tarball to your @file{~/src/} directory, or some
668 other appropriate place.
670 @warning{Be careful where you unpack the tarball! Any
671 subdirectories of the current folder named @file{lilypond/} or
672 @file{lilypond-@var{x.y.z}/} (where @var{x.y.z} is the release
673 number) will be overwritten if there is a name clash with the
676 Unpack the tarball with this command:
679 tar -xzf lilypond-@var{x.y.z}.tar.gz
682 This creates a subdirectory within the current directory called
683 @file{lilypond-@var{x.y.z}/}. Once unpacked, the source files
684 occupy about 40 MB of disk space.
686 Windows users wanting to look at the source code may have to
687 download and install the free-software
688 @uref{http://www.7-zip.org, 7zip archiver} to extract the tarball.
691 @node Configuring make
692 @section Configuring @command{make}
696 * Running ./autogen.sh::
697 * Running ../configure::
701 @node Running ./autogen.sh
702 @subsection Running @command{./autogen.sh}
704 After you unpack the tarball (or download the Git repository), the
705 contents of your top source directory should be similar to the
706 current source tree listed at
707 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree}.
709 Next, you need to create the generated files; enter the following
710 command from your top source directory:
713 ./autogen.sh --noconfigure
716 This will generate a number of files and directories to aid
717 configuration, such as @file{configure}, @file{README.txt}, etc.
719 Next, create the build directory with:
726 We heavily recommend building lilypond inside a separate directory
730 @node Running ../configure
731 @subsection Running @command{../configure}
735 * Configuration options::
736 * Checking build dependencies::
737 * Configuring target directories::
741 @node Configuration options
742 @unnumberedsubsubsec Configuration options
744 @warning{make sure that you are in the @file{build/} subdirectory
745 of your source tree.}
747 The @command{../configure} command (generated by
748 @command{./autogen.sh}) provides many options for configuring
749 @command{make}. To see them all, run:
756 @node Checking build dependencies
757 @unnumberedsubsubsec Checking build dependencies
759 @warning{make sure that you are in the @file{build/} subdirectory
760 of your source tree.}
762 When @command{../configure} is run without any arguments, it will
763 check to make sure your system has everything required for
770 If any build dependency is missing, @command{../configure} will
774 ERROR: Please install required programs: @var{foo}
777 The following message is issued if you are missing programs that
778 are only needed for building the documentation:
781 WARNING: Please consider installing optional programs: @var{bar}
784 If you intend to build the documentation locally, you will need to
785 install or update these programs accordingly.
787 @warning{@command{../configure} may fail to issue warnings for
788 certain documentation build requirements that are not met. If you
789 experience problems when building the documentation, you may need
790 to do a manual check of @ref{Requirements for building
794 @node Configuring target directories
795 @unnumberedsubsubsec Configuring target directories
797 @warning{make sure that you are in the @file{build/} subdirectory
798 of your source tree.}
800 If you intend to use your local build to install a local copy of
801 the program, you will probably want to configure the installation
802 directory. Here are the relevant lines taken from the output of
803 @command{../configure@tie{}--help}:
806 By default, `@command{make@tie{}install}' will install all the
807 files in @file{/usr/local/bin}, @file{/usr/local/lib} etc. You
808 can specify an installation prefix other than @file{/usr/local}
809 using `@option{--prefix}', for instance `@option{--prefix=$HOME}'.
812 A typical installation prefix is @file{$HOME/usr}:
815 ../configure --prefix=$HOME/usr
818 Note that if you plan to install a local build on a system where
819 you do not have root privileges, you will need to do something
820 like this anyway---@command{make@tie{}install} will only succeed
821 if the installation prefix points to a directory where you have
822 write permission (such as your home directory). The installation
823 directory will be automatically created if necessary.
825 The location of the @command{lilypond} command installed by this
826 process will be @file{@var{prefix}/bin/lilypond}; you may want to
827 add @file{@var{prefix}/bin/} to your @code{$PATH} if it is not
830 It is also possible to specify separate installation directories
831 for different types of program files. See the full output of
832 @command{../configure@tie{}--help} for more information.
834 If you encounter any problems, please see @ref{Problems}.
837 @node Compiling LilyPond
838 @section Compiling LilyPond
843 * Saving time with the -j option::
844 * Compiling for multiple platforms::
845 * Useful make variables::
850 @subsection Using @command{make}
852 @warning{make sure that you are in the @file{build/} subdirectory
853 of your source tree.}
855 LilyPond is compiled with the @command{make} command. Assuming
856 @command{make} is configured properly, you can simply run:
862 @samp{make} is short for @samp{make all}. To view a list of @command{make}
869 TODO: Describe what @command{make} actually does.
872 @ref{Generating documentation} provides more info on the @command{make} targets
873 used to build the LilyPond documentation.
876 @node Saving time with the -j option
877 @subsection Saving time with the @option{-j} option
879 If your system has multiple CPUs, you can speed up compilation by
880 adding @samp{-j@var{X}} to the @command{make} command, where
881 @samp{@var{X}} is one more than the number of cores you have. For
882 example, a typical Core2Duo machine would use:
888 If you get errors using the @option{-j} option, and @samp{make}
889 succeeds without it, try lowering the @code{@var{X}} value.
891 Because multiple jobs run in parallel when @option{-j} is used, it can
892 be difficult to determine the source of an error when one occurs. In
893 that case, running @samp{make} without the @option{-j} is advised.
895 @node Compiling for multiple platforms
896 @subsection Compiling for multiple platforms
898 If you want to build multiple versions of LilyPond with different
899 configuration settings, you can use the
900 @option{--enable-config=@var{conf}} option of @command{configure}.
901 You should use @code{make@tie{}conf=@var{conf}} to generate the
902 output in @file{out-@var{conf}}. For example, suppose you want to
903 build with and without profiling, then use the following for the
907 ./configure --prefix=$HOME/usr/ --enable-checking
911 and for the profiling version, specify a different configuration
914 ./configure --prefix=$HOME/usr/ --enable-profiling \
915 --enable-config=prof --disable-checking
919 If you wish to install a copy of the build with profiling, don't
920 forget to use @code{conf=@var{CONF}} when issuing
921 @command{make@tie{}install}:
924 make conf=prof install
929 @ref{Installing LilyPond from a local build}
932 @node Useful make variables
933 @subsection Useful @command{make} variables
935 If a less verbose build output if desired, the variable
936 @code{QUIET_BUILD} may be set to @code{1} on @command{make}
937 command line, or in @file{local.make} at top of the build tree.
940 @node Post-compilation options
941 @section Post-compilation options
945 * Installing LilyPond from a local build::
946 * Generating documentation::
947 * Testing LilyPond binary::
951 @node Installing LilyPond from a local build
952 @subsection Installing LilyPond from a local build
954 If you configured @command{make} to install your local build in a
955 directory where you normally have write permission (such as your
956 home directory), and you have compiled LilyPond by running
957 @command{make}, you can install the program in your target
958 directory by running:
964 If instead, your installation directory is not one that you can
965 normally write to (such as the default @file{/usr/local/}, which
966 typically is only writeable by the superuser), you will need to
967 temporarily become the superuser when running
968 @command{make@tie{}install}:
981 If you don't have superuser privileges, then you need to configure
982 the installation directory to one that you can write to, and then
983 re-install. See @ref{Configuring target directories}.
986 @node Generating documentation
987 @subsection Generating documentation
991 * Documentation editor's edit/compile cycle::
992 * Building documentation::
993 * Building a single document::
994 * Saving time with CPU_COUNT::
996 * Installing documentation::
997 * Building documentation without compiling::
1001 @node Documentation editor's edit/compile cycle
1002 @unnumberedsubsubsec Documentation editor's edit/compile cycle
1006 Initial documentation build:
1010 make [-j@var{X} CPU_COUNT=@var{X}] doc @emph{## can take an hour or more}
1011 make [-j@var{X} CPU_COUNT=@var{X}] doc-stage-1 @emph{## to build only PDF documentation}
1018 @emph{## edit source files, then@dots{}}
1020 make [-j@var{X}] @emph{## needed if editing outside}
1021 @emph{## Documentation/, but useful anyway}
1022 @emph{## for finding Texinfo errors.}
1023 make [-j@var{X} CPU_COUNT=@var{X}] doc @emph{## usually faster than initial build.}
1029 It is generally possible to remove the compiled documentation from
1031 with @samp{make@tie{}doc-clean}, but this method is not 100%
1032 guaranteed. Instead, if you want to be sure you have a clean
1033 system, we recommend that you delete your
1034 @file{build/} directory, and begin compiling from scratch. Since
1035 the documentation compile takes much longer than the
1036 non-documentation compile, this does not increase the overall time
1041 @node Building documentation
1042 @unnumberedsubsubsec Building documentation
1044 After a successful compile (using @command{make}), the
1045 documentation can be built by issuing:
1051 or, to build only the PDF documentation and not the HTML,
1057 @warning{The first time you run @command{make@tie{}doc}, the
1058 process can easily take an hour or more with not much output
1059 on the command line.}
1061 After this initial build, @command{make@tie{}doc} only makes
1062 changes to the documentation where needed, so it may only take
1063 a minute or two to test changes if the documentation is already
1066 If @command{make@tie{}doc} succeeds, the HTML documentation tree
1067 is available in @file{out-www/offline-root/}, and can be browsed
1068 locally. Various portions of the documentation can be found by
1069 looking in @file{out/} and @file{out-www} subdirectories in other
1070 places in the source tree, but these are only @emph{portions} of
1071 the docs. Please do not complain about anything which is broken
1072 in those places; the only complete set of documentation is in
1073 @file{out-www/offline-root/} from the top of the source tree.
1075 @command{make@tie{}doc} sends the output from most of the
1076 compilation to logfiles. If the build fails for any reason, it
1077 should prompt you with the name of a logfile which will provide
1078 information to help you work out why the build failed. These
1079 logfiles are not deleted with @command{make@tie{}doc-clean}. To
1080 remove all the logfiles generated by the compilation process, use:
1086 @code{make@tie{}doc} compiles the documents for all languages. To
1087 save some compile time, the English language documents can be
1088 compiled on their own with:
1094 @noindent Similarly, it is possible to compile a subset of the
1095 translated documentation by specifying their language codes on the
1096 command line. For example, the French and German translations are
1100 make LANGS='de fr' doc
1103 @noindent Note that this will also compile the English version.
1105 Compilation of documentation in Info format with images can be
1106 done separately by issuing:
1113 An issue when switching branches between master and translation
1114 is the appearance/disappearance of translated versions of some manuals.
1115 If you see such a warning from make:
1118 No rule to make target `X', needed by `Y'
1122 Your best bet is to delete the file Y.dep and to try again.
1124 @node Building a single document
1125 @unnumberedsubsubsec Building a single document
1126 It's possible to build a single document. For example, to rebuild
1127 only @file{contributor.pdf}, do the following:
1132 touch ../../Documentation/contributor.texi
1133 make out=www out-www/contributor.pdf
1136 If you are only working on a single document, test-building it in
1137 this way can give substantial time savings - recreating
1138 @file{contributor.pdf}, for example, takes a matter of seconds.
1140 @node Saving time with CPU_COUNT
1141 @unnumberedsubsubsec Saving time with @code{CPU_COUNT}
1143 The most time consuming task for building the documentation is
1144 running LilyPond to build images of music, and there cannot be
1145 several simultaneously running @command{lilypond-book} instances,
1146 so the @option{-j} @command{make} option does not significantly
1147 speed up the build process. To help speed it up, the makefile
1148 variable @option{CPU_COUNT} may be set in @file{local.make} or on
1149 the command line to the number of @code{.ly} files that LilyPond
1150 should process simultaneously, e.g. on a bi-processor or dual core
1154 make -j3 CPU_COUNT=3 doc
1158 The recommended value of @option{CPU_COUNT} is one plus the number
1159 of cores or processors, but it is advisable to set it to a smaller
1160 value unless your system has enough RAM to run that many
1161 simultaneous LilyPond instances. Also, values for the @option{-j}
1162 option that pose problems with @samp{make} are less likely to pose
1163 problems with @samp{make doc} (this applies to both @option{-j}
1164 and @option{CPU_COUNT}). For example, with a quad-core processor,
1165 it is possible for @samp{make -j5 CPU_COUNT=5 doc} to work
1166 consistently even if @samp{make -j5} rarely succeeds.
1170 @unnumberedsubsubsec AJAX search
1172 To build the documentation with interactive searching, use:
1175 make doc AJAX_SEARCH=1
1178 This requires PHP, and you must view the docs via a http
1179 connection (you cannot view them on your local filesystem).
1181 @warning{Due to potential security or load issues, this option is
1182 not enabled in the official documentation builds. Enable at your
1186 @node Installing documentation
1187 @unnumberedsubsubsec Installing documentation
1189 The HTML, PDF and if available Info files can be installed into
1190 the standard documentation path by issuing
1197 This also installs Info documentation with images if the
1198 installation prefix is properly set; otherwise, instructions to
1199 complete proper installation of Info documentation are printed on
1202 To install the Info documentation separately, run:
1209 Note that to get the images in Info documentation, @code{install-doc}
1210 target creates symbolic links to HTML and PDF installed documentation
1211 tree in @file{@var{prefix}/share/info}, in order to save disk space,
1212 whereas @code{install-info} copies images in
1213 @file{@var{prefix}/share/info} subdirectories.
1215 It is possible to build a documentation tree in
1216 @file{out-www/online-root/}, with special processing, so it can be
1217 used on a website with content negotiation for automatic language
1218 selection; this can be achieved by issuing
1221 make WEB_TARGETS=online doc
1225 and both @q{offline} and @q{online} targets can be generated by issuing
1228 make WEB_TARGETS="offline online" doc
1231 Several targets are available to clean the documentation build and
1232 help with maintaining documentation; an overview of these targets is
1240 from every directory in the build tree. Most targets for
1241 documentation maintenance are available from
1242 @file{Documentation/}; for more information, see
1243 @rcontrib{Documentation work}.
1245 The makefile variable @code{QUIET_BUILD} may be set to @code{1}
1246 for a less verbose build output, just like for building the
1250 @node Building documentation without compiling
1251 @unnumberedsubsubsec Building documentation without compiling
1254 The documentation can be built locally without compiling LilyPond
1255 binary, if LilyPond is already installed on your system.
1257 From a fresh Git checkout, do
1260 ./autogen.sh # ignore any warning messages
1261 cp GNUmakefile.in GNUmakefile
1262 make -C scripts && make -C python
1263 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
1266 Please note that this may break sometimes -- for example, if a new
1267 feature is added with a test file in input/regression, even the latest
1268 development release of LilyPond will fail to build the docs.
1270 You may build the manual without building all the @file{input/*} stuff
1271 (i.e. mostly regression tests): change directory, for example to
1272 @file{Documentation/}, issue @code{make doc}, which will build
1273 documentation in a subdirectory @file{out-www} from the source files in
1274 current directory. In this case, if you also want to browse the
1275 documentation in its post-processed form, change back to top directory
1279 make out=www WWW-post
1284 You may also need to create a script for @command{pngtopnm} and
1285 @code{pnmtopng}. On GNU/Linux, I use this:
1288 export LD_LIBRARY_PATH=/usr/lib
1289 exec /usr/bin/pngtopnm "$@"
1292 On MacOS X with fink, I use this:
1295 export DYLD_LIBRARY_PATH=/sw/lib
1296 exec /sw/bin/pngtopnm "$@"
1299 On MacOS X with macports, you should use this:
1302 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
1303 exec /opt/local/bin/pngtopnm "$@"
1307 @node Testing LilyPond binary
1308 @subsection Testing LilyPond binary
1311 LilyPond comes with an extensive suite that exercises the entire
1312 program. This suite can be used to test that the binary has
1313 been built correctly.
1315 The test suite can be executed with:
1321 If the test suite completes successfully, the LilyPond binary
1324 More information on the regression test suite is found at
1325 @rcontrib{Regression tests}.
1330 For help and questions use @email{lilypond-user@@gnu.org}. Send
1331 bug reports to @email{bug-lilypond@@gnu.org}.
1333 Bugs that are not fault of LilyPond are documented here.
1336 @unnumberedsubsec Compiling on MacOS@tie{}X
1338 Here are special instructions for compiling under MacOS@tie{}X.
1339 These instructions assume that dependencies are installed using
1340 @uref{http://www.macports.org/, MacPorts.} The instructions have
1341 been tested using OS X 10.5 (Leopard).
1343 First, install the relevant dependencies using MacPorts.
1345 Next, add the following to your relevant shell initialization
1346 files. This is @code{~/.profile} by default. You should create
1347 this file if it does not exist.
1350 export PATH=/opt/local/bin:/opt/local/sbin:$PATH
1351 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
1354 Now you must edit the generated @file{config.make} file. Change
1357 FLEXLEXER_FILE = /usr/include/FlexLexer.h
1364 FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
1367 At this point, you should verify that you have the appropriate
1368 fonts installed with your ghostscript installation. Check @code{ls
1369 /opt/local/share/ghostscript/fonts} for: 'c0590*' files (.pfb,
1370 .pfb and .afm). If you don't have them, run the following
1371 commands to grab them from the ghostscript SVN server and install
1372 them in the appropriate location:
1375 svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
1376 sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
1377 rm -rf urw-fonts-1.07pre44
1380 Now run the @code{./configure} script. To avoid complications with
1381 automatic font detection, add
1384 --with-fonts-dir=/opt/local/share/ghostscript/fonts
1388 @unnumberedsubsec Solaris
1390 Solaris7, ./configure
1392 @file{./configure} needs a POSIX compliant shell. On Solaris7,
1393 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
1394 is. Run configure like
1397 CONFIG_SHELL=/bin/ksh ksh -c ./configure
1404 CONFIG_SHELL=/bin/bash bash -c ./configure
1407 @unnumberedsubsec FreeBSD
1409 To use system fonts, dejaview must be installed. With the default
1410 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
1412 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
1413 following line just after the @code{<fontconfig>} line. (Adjust as necessary
1414 for your hierarchy.)
1417 <dir>/usr/X11R6/lib/X11/fonts</dir>
1421 @unnumberedsubsec International fonts
1423 On Mac OS X, all fonts are installed by default. However, finding all
1424 system fonts requires a bit of configuration; see
1425 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
1426 this post} on the @code{lilypond-user} mailing list.
1428 On Linux, international fonts are installed by different means on
1429 every distribution. We cannot list the exact commands or packages
1430 that are necessary, as each distribution is different, and the exact
1431 package names within each distribution changes. Here are some
1437 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
1438 ttfonts-zh_CN fonts-ja fonts-hebrew
1442 apt-get install emacs-intl-fonts xfonts-intl-.* \
1443 fonts-ipafont-gothic fonts-ipafont-mincho \
1444 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
1448 @unnumberedsubsec Using lilypond python libraries
1450 If you want to use lilypond's python libraries (either running
1451 certain build scripts manually, or using them in other programs),
1452 set @code{PYTHONPATH} to @file{python/out} in your build
1453 directory, or @file{@dots{}/usr/lib/lilypond/current/python} in the
1454 installation directory structure.
1459 @node Concurrent stable and development versions
1460 @section Concurrent stable and development versions
1463 It can be useful to have both the stable and the development versions
1464 of LilyPond available at once. One way to do this on GNU/Linux is to
1465 install the stable version using the precompiled binary, and run the
1466 development version from the source tree. After running @command{make
1467 all} from the top directory of the LilyPond source files, there will
1468 be a binary called @code{lilypond} in the @code{out} directory:
1471 <@var{path to}>/lilypond/out/bin/lilypond
1474 This binary can be run without actually doing the @code{make
1475 install} command. The advantage to this is that you can have all
1476 of the latest changes available after pulling from git and running
1477 @code{make all}, without having to uninstall the old version and
1480 So, to use the stable version, install it as usual and use the
1487 To use the development version, create a link to the binary in the
1488 source tree by saving the following line in a file somewhere in your
1492 exec <@var{path to}>/lilypond/out/bin/lilypond "$@@"
1495 Save it as @code{Lilypond} (with a capital L to distinguish it
1496 from the stable @code{lilypond}), and make it executable:
1502 Then you can invoke the development version this way:
1511 - other compilation tricks for developers
1515 @section Build system
1518 We currently use make and stepmake, which is complicated and only
1519 used by us. Hopefully this will change in the future.
1522 @subheading Version-specific texinfo macros
1527 made with @command{scripts/build/create-version-itexi.py} and@*
1528 @command{scripts/build/create-weblinks-itexi.py}
1531 used extensively in the @code{WEBSITE_ONLY_BUILD} version of the
1532 website (made with @file{website.make}, used on lilypond.org)
1535 not (?) used in the main docs?
1538 the numbers in VERSION file: MINOR_VERSION should be 1 more than
1539 the last release, VERSION_DEVEL should be the last @strong{online}
1540 release. Yes, VERSION_DEVEL is less than VERSION.