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 22} and include all
163 the software to both compile LilyPond and build the documenation.
168 Download and install all the LilyPond build-dependencies (approximately
172 sudo dnf builddep lilypond --nogpgcheck
176 Download and install additional @q{build} tools required for compiling;
179 sudo dnf install autoconf gcc-c++
183 Download @code{texi2html 1.82} directly from:
184 @uref{http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz};
186 @code{texi2html} is only required if you intend to compile LilyPond's
187 own documentation (e.g. to help with any document writing). The version
188 available in the Fedora repositories is too new and will not work.
189 Extract the files into an appropriate location and then run the
198 This should install @code{texi2html 1.82} into @code{/usr/local/bin},
199 which will normally take priority over @code{/usr/bin} where the
200 later, pre-installed versions gets put. Now verify that your operating
201 system is able to see the correct version of @code{texi2html}.
208 Although not @q{required} to compile LilyPond, if you intend to
209 contribute to LilyPond (codebase or help improve the documentation) then
210 it is recommended that you also need to install @code{git}.
216 Also see @ruser{Starting with Git}.
219 To use the @code{lily-git.tcl} GUI;
225 See @ruser{lily-git}.
232 @unnumberedsubsubsec Linux Mint
234 The following instructions were tested on @q{Linux Mint 17.1} and
235 @q{LMDE - Betsy} and include all the software to both compile LilyPond
236 and build the documenation.
241 Enable the @emph{sources} repository;
246 Using the @emph{Software Sources} GUI (located under
247 @emph{Administration}).
250 Select @emph{Official Repositories}.
253 Check the @emph{Enable source code repositories} box under the
254 @emph{Source Code} section.
257 Click the @emph{Update the cache} button and when it has completed,
258 close the @emph{Software Sources} GUI.
263 Download and install all the LilyPond build-dependencies (approximately
267 sudo apt-get build-dep lilypond
271 Download and install additional @q{build} tools required for compiling;
274 sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
278 Although not @q{required} to compile LilyPond, if you intend to
279 contribute to LilyPond (codebase or help improve the documentation) then
280 it is recommended that you also need to install @code{git}.
283 sudo apt-get install git
286 Also see @ruser{Starting with Git}.
289 To use the @code{lily-git.tcl} GUI;
292 sudo apt-get install tk
295 Also see @ruser{lily-git}.
301 @unnumberedsubsubsec OpenSUSE
303 The following instructions were tested on @q{OpenSUSE 13.2} and include
304 all the software to both compile LilyPond and build the documenation.
309 Add the @emph{sources} repository;
312 sudo zypper addrepo -f \
313 "http://download.opensuse.org/source/distribution/13.2/repo/oss/" sources
317 Download and install all the LilyPond build-dependencies (approximately
321 sudo zypper source-install lilypond
325 Download and install additional @q{build} tools required for compiling;
328 sudo zypper install make
332 Although not @q{required} to compile LilyPond, if you intend to
333 contribute to LilyPond (codebase or help improve the documentation) then
334 it is recommended that you also need to install @code{git}.
337 sudo apt-get install git
340 Also see @ruser{Starting with Git}.
343 To use the @code{lily-git.tcl} GUI;
346 sudo zypper install tk
349 Also see @ruser{lily-git}.
356 @unnumberedsubsubsec Ubuntu
358 The following commands were tested on Ubuntu versions @code{14.04 LTS},
359 @code{14.10} and @code{15.04} and include all the software to both
360 compile LilyPond and build the documenation.
365 Download and install all the LilyPond build-dependencies (approximately
369 sudo apt-get build-dep lilypond
373 Download and install additional @q{build} tools required for compiling;
376 sudo apt-get install autoconf fonts-texgyre texlive-land-cyrillic
380 Although not @q{required} to compile LilyPond, if you intend to
381 contribute to LilyPond (codebase or help improve the documentation) then
382 it is recommended that you also need to install @code{git}.
385 sudo apt-get install git
388 Also see @ruser{Starting with Git}.
391 To use the @code{lily-git.tcl} GUI;
394 sudo apt-get install tk
397 Also see @ruser{lily-git}.
403 @unnumberedsubsubsec Other
405 The following individual software packages are required just to compile
411 @uref{http://www.gnu.org/software/autoconf, GNU Autoconf}
414 @uref{http://www.gnu.org/software/bison/, GNU Bison}
416 Use version @code{2.0} or newer.
419 @uref{http://gcc.gnu.org/, GNU Compiler Collection}
421 Use version @code{3.4} or newer (@code{4.x} recommended).
424 @uref{http://flex.sourceforge.net/, Flex}
427 @uref{http://fontforge.sf.net/, FontForge}
429 Use version @code{20060125} or newer (we recommend using at least
430 @code{20100501}); it must also be compiled with the
431 @option{--enable-double} switch, else this can lead to inaccurate
432 intersection calculations which end up with poorly-rendered glyphs in
436 @uref{http://www.gnu.org/software/gettext/gettext.html, GNU gettext}
438 Use version @code{0.17} or newer.
441 @uref{http://www.gnu.org/software/make/, GNU Make}
443 Use version @code{3.78} or newer.
446 @uref{http://metafont.tutorial.free.fr/, MetaFont}
448 The @code{mf-nowin}, @code{mf}, @code{mfw} or @code{mfont} binaries are
449 usually packaged along with
450 @uref{http://www.latex-project.org/ftp.html, @TeX{}}.
453 @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html, MetaPost}
455 The @code{mpost} binary is also usually packaged with
456 @uref{http://www.latex-project.org/ftp.html, @TeX{}}.
459 @uref{http://www.perl.org/, Perl}
462 @uref{http://www.gnu.org/software/texinfo/, Texinfo}
464 Use version @code{4.11} or newer.
467 @uref{http://www.lcdf.org/~eddietwo/type/#t1utils, Type 1 utilities}
469 Use version @code{1.33} or newer.
472 @uref{https://www.ctan.org/pkg/cyrillic?lang=en, Cyrillic fonts}
474 Often packaged in repositories as @code{texlive-lang-cyrillic}.
477 TeX Gyre @q{OTF} font packages. As of LilyPond version @code{2.19.26},
478 the previous default serif, san serif and monospace fonts now use Tex
479 Gyre's @emph{Schola}, @emph{Heros} and @emph{Cursor} fonts respectively.
480 Also See @ruser{Fonts}.
482 Some distributions do not always provide @q{OTF} font files in the Tex
483 Gyre packages from their repositories. Use the command
484 @code{fc-list | grep texgyre} to list the fonts available to your system
485 and check that the appropriate @code{*.otf} files are reported. If they
486 are not then download and manually extract the @q{OTF} files to either
487 your local @code{~/.fonts/} directory or use the
488 @code{configure} command and the
489 @code{--with-texgyre-dir=/path_to_otf_files/} option.
491 The following font families are required:
493 @uref{http://www.gust.org.pl/projects/e-foundry/tex-gyre/schola, Schola},
494 @uref{http://www.gust.org.pl/projects/e-foundry/tex-gyre/heros, Heros}
496 @uref{http://www.gust.org.pl/projects/e-foundry/tex-gyre/cursor, Cursor}.
502 @node Requirements for building documentation
503 @subsection Requirements for building documentation
505 The entire set of documentation for the most current build of LilyPond
506 is available online at
507 @uref{http://lilypond.org/doc/v2.19/Documentation/web/development}, but
508 you can also build them locally from the source code. This process
509 requires some additional tools and packages.
511 @warning{If you have used the instructions for one of the Linux
512 distributions explicitly listed in the previous section
513 (@rcontrib{Requirements for compiling LilyPond}) then the following can
514 be ignored as the software should already be installed.}
519 Everything listed in @ref{Requirements for compiling LilyPond}
522 @uref{http://www.imagemagick.org/, ImageMagick}
525 @uref{http://netpbm.sourceforge.net/, Netpbm}
528 @uref{http://gzip.org/, gzip}
531 @uref{http://rsync.samba.org/, rsync}
534 @uref{http://www.nongnu.org/texi2html/, Texi2HTML}
536 Use version @code{1.82}. Later versions will not work.
538 Download @code{texi2html 1.82} directly from:
539 @uref{http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz};
541 Extract the files into an appropriate location and then run the
550 Now verify that your operating system is able to see the correct version
558 Fonts required to build the documentation in addition to those required
568 texlive-fonts-recommended
576 @node Getting the source code
577 @section Getting the source code
580 @subheading Downloading the Git repository
582 In general, developers compile LilyPond from within a local Git
583 repository. Setting up a local Git repository is explained in
584 @rcontrib{Starting with Git}.
587 @subheading Downloading a source tarball
589 Packagers are encouraged to use source tarballs for compiling.
591 The tarball for the latest stable release is available on the
596 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot, source code snapshot}
597 is also available as a tarball from the GNU Savannah Git server.
600 All tagged releases (including legacy stable
601 versions and the most recent development release) are available
605 @uref{http://download.linuxaudio.org/lilypond/source/}
608 Download the tarball to your @file{~/src/} directory, or some
609 other appropriate place.
611 @warning{Be careful where you unpack the tarball! Any
612 subdirectories of the current folder named @file{lilypond/} or
613 @file{lilypond-@var{x.y.z}/} (where @var{x.y.z} is the release
614 number) will be overwritten if there is a name clash with the
617 Unpack the tarball with this command:
620 tar -xzf lilypond-@var{x.y.z}.tar.gz
623 This creates a subdirectory within the current directory called
624 @file{lilypond-@var{x.y.z}/}. Once unpacked, the source files
625 occupy about 40 MB of disk space.
627 Windows users wanting to look at the source code may have to
628 download and install the free-software
629 @uref{http://www.7-zip.org, 7zip archiver} to extract the tarball.
632 @node Configuring make
633 @section Configuring @command{make}
637 * Running ./autogen.sh::
638 * Running ../configure::
642 @node Running ./autogen.sh
643 @subsection Running @command{./autogen.sh}
645 After you unpack the tarball (or download the Git repository), the
646 contents of your top source directory should be similar to the
647 current source tree listed at
648 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree}.
650 Next, you need to create the generated files; enter the following
651 command from your top source directory:
654 ./autogen.sh --noconfigure
657 This will generate a number of files and directories to aid
658 configuration, such as @file{configure}, @file{README.txt}, etc.
660 Next, create the build directory with:
667 We heavily recommend building lilypond inside a separate directory
671 @node Running ../configure
672 @subsection Running @command{../configure}
676 * Configuration options::
677 * Checking build dependencies::
678 * Configuring target directories::
682 @node Configuration options
683 @unnumberedsubsubsec Configuration options
685 @warning{make sure that you are in the @file{build/} subdirectory
686 of your source tree.}
688 The @command{../configure} command (generated by
689 @command{./autogen.sh}) provides many options for configuring
690 @command{make}. To see them all, run:
697 @node Checking build dependencies
698 @unnumberedsubsubsec Checking build dependencies
700 @warning{make sure that you are in the @file{build/} subdirectory
701 of your source tree.}
703 When @command{../configure} is run without any arguments, it will
704 check to make sure your system has everything required for
711 If any build dependency is missing, @command{../configure} will
715 ERROR: Please install required programs: @var{foo}
718 The following message is issued if you are missing programs that
719 are only needed for building the documentation:
722 WARNING: Please consider installing optional programs: @var{bar}
725 If you intend to build the documentation locally, you will need to
726 install or update these programs accordingly.
728 @warning{@command{../configure} may fail to issue warnings for
729 certain documentation build requirements that are not met. If you
730 experience problems when building the documentation, you may need
731 to do a manual check of @ref{Requirements for building
735 @node Configuring target directories
736 @unnumberedsubsubsec Configuring target directories
738 @warning{make sure that you are in the @file{build/} subdirectory
739 of your source tree.}
741 If you intend to use your local build to install a local copy of
742 the program, you will probably want to configure the installation
743 directory. Here are the relevant lines taken from the output of
744 @command{../configure@tie{}--help}:
747 By default, `@command{make@tie{}install}' will install all the
748 files in @file{/usr/local/bin}, @file{/usr/local/lib} etc. You
749 can specify an installation prefix other than @file{/usr/local}
750 using `@option{--prefix}', for instance `@option{--prefix=$HOME}'.
753 A typical installation prefix is @file{$HOME/usr}:
756 ../configure --prefix=$HOME/usr
759 Note that if you plan to install a local build on a system where
760 you do not have root privileges, you will need to do something
761 like this anyway---@command{make@tie{}install} will only succeed
762 if the installation prefix points to a directory where you have
763 write permission (such as your home directory). The installation
764 directory will be automatically created if necessary.
766 The location of the @command{lilypond} command installed by this
767 process will be @file{@var{prefix}/bin/lilypond}; you may want to
768 add @file{@var{prefix}/bin/} to your @code{$PATH} if it is not
771 It is also possible to specify separate installation directories
772 for different types of program files. See the full output of
773 @command{../configure@tie{}--help} for more information.
775 If you encounter any problems, please see @ref{Problems}.
778 @node Compiling LilyPond
779 @section Compiling LilyPond
784 * Saving time with the -j option::
785 * Compiling for multiple platforms::
786 * Useful make variables::
791 @subsection Using @command{make}
793 @warning{make sure that you are in the @file{build/} subdirectory
794 of your source tree.}
796 LilyPond is compiled with the @command{make} command. Assuming
797 @command{make} is configured properly, you can simply run:
803 @samp{make} is short for @samp{make all}. To view a list of @command{make}
810 TODO: Describe what @command{make} actually does.
813 @ref{Generating documentation} provides more info on the @command{make} targets
814 used to build the LilyPond documentation.
817 @node Saving time with the -j option
818 @subsection Saving time with the @option{-j} option
820 If your system has multiple CPUs, you can speed up compilation by
821 adding @samp{-j@var{X}} to the @command{make} command, where
822 @samp{@var{X}} is one more than the number of cores you have. For
823 example, a typical Core2Duo machine would use:
829 If you get errors using the @option{-j} option, and @samp{make}
830 succeeds without it, try lowering the @code{@var{X}} value.
832 Because multiple jobs run in parallel when @option{-j} is used, it can
833 be difficult to determine the source of an error when one occurs. In
834 that case, running @samp{make} without the @option{-j} is advised.
836 @node Compiling for multiple platforms
837 @subsection Compiling for multiple platforms
839 If you want to build multiple versions of LilyPond with different
840 configuration settings, you can use the
841 @option{--enable-config=@var{conf}} option of @command{configure}.
842 You should use @code{make@tie{}conf=@var{conf}} to generate the
843 output in @file{out-@var{conf}}. For example, suppose you want to
844 build with and without profiling, then use the following for the
848 ./configure --prefix=$HOME/usr/ --enable-checking
852 and for the profiling version, specify a different configuration
855 ./configure --prefix=$HOME/usr/ --enable-profiling \
856 --enable-config=prof --disable-checking
860 If you wish to install a copy of the build with profiling, don't
861 forget to use @code{conf=@var{CONF}} when issuing
862 @command{make@tie{}install}:
865 make conf=prof install
870 @ref{Installing LilyPond from a local build}
873 @node Useful make variables
874 @subsection Useful @command{make} variables
876 If a less verbose build output if desired, the variable
877 @code{QUIET_BUILD} may be set to @code{1} on @command{make}
878 command line, or in @file{local.make} at top of the build tree.
881 @node Post-compilation options
882 @section Post-compilation options
886 * Installing LilyPond from a local build::
887 * Generating documentation::
888 * Testing LilyPond binary::
892 @node Installing LilyPond from a local build
893 @subsection Installing LilyPond from a local build
895 If you configured @command{make} to install your local build in a
896 directory where you normally have write permission (such as your
897 home directory), and you have compiled LilyPond by running
898 @command{make}, you can install the program in your target
899 directory by running:
905 If instead, your installation directory is not one that you can
906 normally write to (such as the default @file{/usr/local/}, which
907 typically is only writeable by the superuser), you will need to
908 temporarily become the superuser when running
909 @command{make@tie{}install}:
922 If you don't have superuser privileges, then you need to configure
923 the installation directory to one that you can write to, and then
924 re-install. See @ref{Configuring target directories}.
927 @node Generating documentation
928 @subsection Generating documentation
932 * Documentation editor's edit/compile cycle::
933 * Building documentation::
934 * Building a single document::
935 * Saving time with CPU_COUNT::
937 * Installing documentation::
938 * Building documentation without compiling::
942 @node Documentation editor's edit/compile cycle
943 @unnumberedsubsubsec Documentation editor's edit/compile cycle
947 Initial documentation build:
951 make [-j@var{X} CPU_COUNT=@var{X}] doc @emph{## can take an hour or more}
952 make [-j@var{X} CPU_COUNT=@var{X}] doc-stage-1 @emph{## to build only PDF documentation}
959 @emph{## edit source files, then@dots{}}
961 make [-j@var{X}] @emph{## needed if editing outside}
962 @emph{## Documentation/, but useful anyway}
963 @emph{## for finding Texinfo errors.}
964 make [-j@var{X} CPU_COUNT=@var{X}] doc @emph{## usually faster than initial build.}
970 It is generally possible to remove the compiled documentation from
972 with @samp{make@tie{}doc-clean}, but this method is not 100%
973 guaranteed. Instead, if you want to be sure you have a clean
974 system, we recommend that you delete your
975 @file{build/} directory, and begin compiling from scratch. Since
976 the documentation compile takes much longer than the
977 non-documentation compile, this does not increase the overall time
982 @node Building documentation
983 @unnumberedsubsubsec Building documentation
985 After a successful compile (using @command{make}), the
986 documentation can be built by issuing:
992 or, to build only the PDF documentation and not the HTML,
998 @warning{The first time you run @command{make@tie{}doc}, the
999 process can easily take an hour or more with not much output
1000 on the command line.}
1002 After this initial build, @command{make@tie{}doc} only makes
1003 changes to the documentation where needed, so it may only take
1004 a minute or two to test changes if the documentation is already
1007 If @command{make@tie{}doc} succeeds, the HTML documentation tree
1008 is available in @file{out-www/offline-root/}, and can be browsed
1009 locally. Various portions of the documentation can be found by
1010 looking in @file{out/} and @file{out-www} subdirectories in other
1011 places in the source tree, but these are only @emph{portions} of
1012 the docs. Please do not complain about anything which is broken
1013 in those places; the only complete set of documentation is in
1014 @file{out-www/offline-root/} from the top of the source tree.
1016 @command{make@tie{}doc} sends the output from most of the
1017 compilation to logfiles. If the build fails for any reason, it
1018 should prompt you with the name of a logfile which will provide
1019 information to help you work out why the build failed. These
1020 logfiles are not deleted with @command{make@tie{}doc-clean}. To
1021 remove all the logfiles generated by the compilation process, use:
1027 @code{make@tie{}doc} compiles the documents for all languages. To
1028 save some compile time, the English language documents can be
1029 compiled on their own with:
1035 @noindent Similarly, it is possible to compile a subset of the
1036 translated documentation by specifying their language codes on the
1037 command line. For example, the French and German translations are
1041 make LANGS='de fr' doc
1044 @noindent Note that this will also compile the English version.
1046 Compilation of documentation in Info format with images can be
1047 done separately by issuing:
1054 An issue when switching branches between master and translation
1055 is the appearance/disappearance of translated versions of some manuals.
1056 If you see such a warning from make:
1059 No rule to make target `X', needed by `Y'
1063 Your best bet is to delete the file Y.dep and to try again.
1065 @node Building a single document
1066 @unnumberedsubsubsec Building a single document
1067 It's possible to build a single document. For example, to rebuild
1068 only @file{contributor.pdf}, do the following:
1073 touch ../../Documentation/contributor.texi
1074 make out=www out-www/contributor.pdf
1077 If you are only working on a single document, test-building it in
1078 this way can give substantial time savings - recreating
1079 @file{contributor.pdf}, for example, takes a matter of seconds.
1081 @node Saving time with CPU_COUNT
1082 @unnumberedsubsubsec Saving time with @code{CPU_COUNT}
1084 The most time consuming task for building the documentation is
1085 running LilyPond to build images of music, and there cannot be
1086 several simultaneously running @command{lilypond-book} instances,
1087 so the @option{-j} @command{make} option does not significantly
1088 speed up the build process. To help speed it up, the makefile
1089 variable @option{CPU_COUNT} may be set in @file{local.make} or on
1090 the command line to the number of @code{.ly} files that LilyPond
1091 should process simultaneously, e.g. on a bi-processor or dual core
1095 make -j3 CPU_COUNT=3 doc
1099 The recommended value of @option{CPU_COUNT} is one plus the number
1100 of cores or processors, but it is advisable to set it to a smaller
1101 value unless your system has enough RAM to run that many
1102 simultaneous LilyPond instances. Also, values for the @option{-j}
1103 option that pose problems with @samp{make} are less likely to pose
1104 problems with @samp{make doc} (this applies to both @option{-j}
1105 and @option{CPU_COUNT}). For example, with a quad-core processor,
1106 it is possible for @samp{make -j5 CPU_COUNT=5 doc} to work
1107 consistently even if @samp{make -j5} rarely succeeds.
1111 @unnumberedsubsubsec AJAX search
1113 To build the documentation with interactive searching, use:
1116 make doc AJAX_SEARCH=1
1119 This requires PHP, and you must view the docs via a http
1120 connection (you cannot view them on your local filesystem).
1122 @warning{Due to potential security or load issues, this option is
1123 not enabled in the official documentation builds. Enable at your
1127 @node Installing documentation
1128 @unnumberedsubsubsec Installing documentation
1130 The HTML, PDF and if available Info files can be installed into
1131 the standard documentation path by issuing
1138 This also installs Info documentation with images if the
1139 installation prefix is properly set; otherwise, instructions to
1140 complete proper installation of Info documentation are printed on
1143 To install the Info documentation separately, run:
1150 Note that to get the images in Info documentation, @code{install-doc}
1151 target creates symbolic links to HTML and PDF installed documentation
1152 tree in @file{@var{prefix}/share/info}, in order to save disk space,
1153 whereas @code{install-info} copies images in
1154 @file{@var{prefix}/share/info} subdirectories.
1156 It is possible to build a documentation tree in
1157 @file{out-www/online-root/}, with special processing, so it can be
1158 used on a website with content negotiation for automatic language
1159 selection; this can be achieved by issuing
1162 make WEB_TARGETS=online doc
1166 and both @q{offline} and @q{online} targets can be generated by issuing
1169 make WEB_TARGETS="offline online" doc
1172 Several targets are available to clean the documentation build and
1173 help with maintaining documentation; an overview of these targets is
1181 from every directory in the build tree. Most targets for
1182 documentation maintenance are available from
1183 @file{Documentation/}; for more information, see
1184 @rcontrib{Documentation work}.
1186 The makefile variable @code{QUIET_BUILD} may be set to @code{1}
1187 for a less verbose build output, just like for building the
1191 @node Building documentation without compiling
1192 @unnumberedsubsubsec Building documentation without compiling
1195 The documentation can be built locally without compiling LilyPond
1196 binary, if LilyPond is already installed on your system.
1198 From a fresh Git checkout, do
1201 ./autogen.sh # ignore any warning messages
1202 cp GNUmakefile.in GNUmakefile
1203 make -C scripts && make -C python
1204 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
1207 Please note that this may break sometimes -- for example, if a new
1208 feature is added with a test file in input/regression, even the latest
1209 development release of LilyPond will fail to build the docs.
1211 You may build the manual without building all the @file{input/*} stuff
1212 (i.e. mostly regression tests): change directory, for example to
1213 @file{Documentation/}, issue @code{make doc}, which will build
1214 documentation in a subdirectory @file{out-www} from the source files in
1215 current directory. In this case, if you also want to browse the
1216 documentation in its post-processed form, change back to top directory
1220 make out=www WWW-post
1225 You may also need to create a script for @command{pngtopnm} and
1226 @code{pnmtopng}. On GNU/Linux, I use this:
1229 export LD_LIBRARY_PATH=/usr/lib
1230 exec /usr/bin/pngtopnm "$@"
1233 On MacOS X with fink, I use this:
1236 export DYLD_LIBRARY_PATH=/sw/lib
1237 exec /sw/bin/pngtopnm "$@"
1240 On MacOS X with macports, you should use this:
1243 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
1244 exec /opt/local/bin/pngtopnm "$@"
1248 @node Testing LilyPond binary
1249 @subsection Testing LilyPond binary
1252 LilyPond comes with an extensive suite that exercises the entire
1253 program. This suite can be used to test that the binary has
1254 been built correctly.
1256 The test suite can be executed with:
1262 If the test suite completes successfully, the LilyPond binary
1265 More information on the regression test suite is found at
1266 @rcontrib{Regression tests}.
1271 For help and questions use @email{lilypond-user@@gnu.org}. Send
1272 bug reports to @email{bug-lilypond@@gnu.org}.
1274 Bugs that are not fault of LilyPond are documented here.
1277 @unnumberedsubsec Compiling on MacOS@tie{}X
1279 Here are special instructions for compiling under MacOS@tie{}X.
1280 These instructions assume that dependencies are installed using
1281 @uref{http://www.macports.org/, MacPorts.} The instructions have
1282 been tested using OS X 10.5 (Leopard).
1284 First, install the relevant dependencies using MacPorts.
1286 Next, add the following to your relevant shell initialization
1287 files. This is @code{~/.profile} by default. You should create
1288 this file if it does not exist.
1291 export PATH=/opt/local/bin:/opt/local/sbin:$PATH
1292 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
1295 Now you must edit the generated @file{config.make} file. Change
1298 FLEXLEXER_FILE = /usr/include/FlexLexer.h
1305 FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
1308 At this point, you should verify that you have the appropriate
1309 fonts installed with your ghostscript installation. Check @code{ls
1310 /opt/local/share/ghostscript/fonts} for: 'c0590*' files (.pfb,
1311 .pfb and .afm). If you don't have them, run the following
1312 commands to grab them from the ghostscript SVN server and install
1313 them in the appropriate location:
1316 svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
1317 sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
1318 rm -rf urw-fonts-1.07pre44
1321 Now run the @code{./configure} script. To avoid complications with
1322 automatic font detection, add
1325 --with-fonts-dir=/opt/local/share/ghostscript/fonts
1329 @unnumberedsubsec Solaris
1331 Solaris7, ./configure
1333 @file{./configure} needs a POSIX compliant shell. On Solaris7,
1334 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
1335 is. Run configure like
1338 CONFIG_SHELL=/bin/ksh ksh -c ./configure
1345 CONFIG_SHELL=/bin/bash bash -c ./configure
1348 @unnumberedsubsec FreeBSD
1350 To use system fonts, dejaview must be installed. With the default
1351 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
1353 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
1354 following line just after the @code{<fontconfig>} line. (Adjust as necessary
1355 for your hierarchy.)
1358 <dir>/usr/X11R6/lib/X11/fonts</dir>
1362 @unnumberedsubsec International fonts
1364 On Mac OS X, all fonts are installed by default. However, finding all
1365 system fonts requires a bit of configuration; see
1366 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
1367 this post} on the @code{lilypond-user} mailing list.
1369 On Linux, international fonts are installed by different means on
1370 every distribution. We cannot list the exact commands or packages
1371 that are necessary, as each distribution is different, and the exact
1372 package names within each distribution changes. Here are some
1378 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
1379 ttfonts-zh_CN fonts-ja fonts-hebrew
1383 apt-get install emacs-intl-fonts xfonts-intl-.* \
1384 fonts-ipafont-gothic fonts-ipafont-mincho \
1385 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
1389 @unnumberedsubsec Using lilypond python libraries
1391 If you want to use lilypond's python libraries (either running
1392 certain build scripts manually, or using them in other programs),
1393 set @code{PYTHONPATH} to @file{python/out} in your build
1394 directory, or @file{@dots{}/usr/lib/lilypond/current/python} in the
1395 installation directory structure.
1400 @node Concurrent stable and development versions
1401 @section Concurrent stable and development versions
1404 It can be useful to have both the stable and the development versions
1405 of Lilypond available at once. One way to do this on GNU/Linux is to
1406 install the stable version using the precompiled binary, and run the
1407 development version from the source tree. After running @command{make
1408 all} from the top directory of the Lilypond source files, there will
1409 be a binary called @code{lilypond} in the @code{out} directory:
1412 <@var{path to}>/lilypond/out/bin/lilypond
1415 This binary can be run without actually doing the @code{make
1416 install} command. The advantage to this is that you can have all
1417 of the latest changes available after pulling from git and running
1418 @code{make all}, without having to uninstall the old version and
1421 So, to use the stable version, install it as usual and use the
1428 To use the development version, create a link to the binary in the
1429 source tree by saving the following line in a file somewhere in your
1433 exec <@var{path to}>/lilypond/out/bin/lilypond "$@@"
1436 Save it as @code{Lilypond} (with a capital L to distinguish it
1437 from the stable @code{lilypond}), and make it executable:
1443 Then you can invoke the development version this way:
1452 - other compilation tricks for developers
1456 @section Build system
1459 We currently use make and stepmake, which is complicated and only
1460 used by us. Hopefully this will change in the future.
1463 @subheading Version-specific texinfo macros
1468 made with @command{scripts/build/create-version-itexi.py} and@*
1469 @command{scripts/build/create-weblinks-itexi.py}
1472 used extensively in the @code{WEBSITE_ONLY_BUILD} version of the
1473 website (made with @file{website.make}, used on lilypond.org)
1476 not (?) used in the main docs?
1479 the numbers in VERSION file: MINOR_VERSION should be 1 more than
1480 the last release, VERSION_DEVEL should be the last @strong{online}
1481 release. Yes, VERSION_DEVEL is less than VERSION.