1 INSTALL - compiling and installing GNU LilyPond
2 ***********************************************
6 1.1 Overview of compiling
8 1.2.1 Requirements for running LilyPond
9 1.2.2 Requirements for compiling LilyPond
15 1.2.3 Requirements for building documentation
16 1.3 Getting the source code
17 1.4 Configuring ‘make’
18 1.4.1 Running ‘./autogen.sh’
19 1.4.2 Running ‘../configure’
21 Checking build dependencies
22 Configuring target directories
23 1.5 Compiling LilyPond
25 1.5.2 Saving time with the ‘-j’ option
26 1.5.3 Compiling for multiple platforms
27 1.5.4 Useful ‘make’ variables
28 1.6 Post-compilation options
29 1.6.1 Installing LilyPond from a local build
30 1.6.2 Generating documentation
31 Documentation editor’s edit/compile cycle
32 Building documentation
33 Building a single document
34 Saving time with ‘CPU_COUNT’
36 Installing documentation
37 Building documentation without compiling
38 1.6.3 Testing LilyPond binary
44 Using lilypond python libraries
45 1.8 Concurrent stable and development versions
50 1.1 Overview of compiling
51 =========================
53 Compiling LilyPond from source is an involved process, and is only
54 recommended for developers and packagers. Typical program users are
55 instead encouraged to obtain the program from a package manager (on
56 Unix) or by downloading a precompiled binary configured for a specific
57 operating system. Pre-compiled binaries are available on the *note
58 (lilypond-web)Download:: page.
60 Compiling LilyPond from source is necessary if you want to build,
61 install, or test your own version of the program.
63 A successful compile can also be used to generate and install the
64 documentation, incorporating any changes you may have made. However, a
65 successful compile is not a requirement for generating the
66 documentation. The documentation can be built using a Git repository in
67 conjunction with a locally installed copy of the program. For more
68 information, see *note Building documentation without compiling::.
70 Attempts to compile LilyPond natively on Windows have been
71 unsuccessful, though a workaround is available (see *note
72 (lilypond-contributor)LilyDev::).
77 1.2.1 Requirements for running LilyPond
78 ---------------------------------------
80 This section contains the list of separate software packages that are
81 required to run LilyPond.
83 • DejaVu fonts (http://www.dejavu-fonts.org/) These are normally
86 • FontConfig (http://www.fontconfig.org/) Use version 2.4.0 or newer.
88 • Freetype (http://www.freetype.org/) Use version 2.1.10 or newer.
90 • Ghostscript (http://www.ghostscript.com) Use version 8.60 or newer.
92 • Guile (http://www.gnu.org/software/guile/guile.html) Use version
93 1.8.8. Version 2.x of Guile is not currently supported.
95 • Pango (http://www.pango.org/) User version 1.12 or newer.
97 • Python (http://www.python.org) Use version 2.4 or newer.
99 • International fonts. For example:
111 Debian based distributions:
121 These are normally installed by default and are required only to
122 create music with international text or lyrics.
124 1.2.2 Requirements for compiling LilyPond
125 -----------------------------------------
127 This section contains instructions on how to quickly and easily get all
128 the software packages required to build LilyPond.
130 Most of the more popular Linux distributions only require a few
131 simple commands to download all the software needed. For others, there
132 is an explicit list of all the individual packages (as well as where to
133 get them from) for those that are not already included in your
134 distributions’ own repositories.
139 The following instructions were tested on ‘Fedora’ versions 22 & 23 and
140 will download all the software required to both compile LilyPond and
141 build the documentation.
143 • Download and install all the LilyPond build-dependencies
144 (approximately 700MB);
146 sudo dnf builddep lilypond --nogpgcheck
148 • Download and install additional ‘build’ tools required for
151 sudo dnf install autoconf gcc-c++
153 • Download ‘texi2html 1.82’ directly from:
154 <http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz>;
156 ‘texi2html’ is only required if you intend to compile LilyPond’s
157 own documentation (e.g. to help with any document writing). The
158 version available in the Fedora repositories is too new and will
159 not work. Extract the files into an appropriate location and then
166 This should install ‘texi2html 1.82’ into ‘/usr/local/bin’, which
167 will normally take priority over ‘/usr/bin’ where the later,
168 pre-installed versions gets put. Now verify that your operating
169 system is able to see the correct version of ‘texi2html’.
173 • Although not ‘required’ to compile LilyPond, if you intend to
174 contribute to LilyPond (codebase or help improve the documentation)
175 then it is recommended that you also need to install ‘git’.
179 Also see *note (lilypond-contributor)Starting with Git::.
181 • To use the ‘lily-git.tcl’ GUI;
185 See *note (lilypond-contributor)lily-git::.
187 Note: By default, when building LilyPond’s documentation,
188 ‘pdfTeX’ is be used. However ligatures (fi, fl, ff etc.) may
189 not be printed in the PDF output. In this case XeTeX can be
190 used instead. Download and install the ‘texlive-xetex’
193 sudo dnf install texlive-xetex
195 The scripts used to build the LilyPond documentation will use
196 ‘XeTex’ instead of ‘pdfTex’ to generate the PDF documents if
197 it is available. No additional configuration is required.
202 The following instructions were tested on ‘Linux Mint 17.1’ and ‘LMDE -
203 Betsy’ and will download all the software required to both compile
204 LilyPond and build the documentation..
206 • Enable the _sources_ repository;
208 1. Using the _Software Sources_ GUI (located under
211 2. Select _Official Repositories_.
213 3. Check the _Enable source code repositories_ box under the
214 _Source Code_ section.
216 4. Click the _Update the cache_ button and when it has completed,
217 close the _Software Sources_ GUI.
219 • Download and install all the LilyPond build-dependencies
220 (approximately 200MB);
222 sudo apt-get build-dep lilypond
224 • Download and install additional ‘build’ tools required for
227 sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
229 • Although not ‘required’ to compile LilyPond, if you intend to
230 contribute to LilyPond (codebase or help improve the documentation)
231 then it is recommended that you also need to install ‘git’.
233 sudo apt-get install git
235 Also see *note (lilypond-contributor)Starting with Git::.
237 • To use the ‘lily-git.tcl’ GUI;
239 sudo apt-get install tk
241 Also see *note (lilypond-contributor)lily-git::.
243 Note: By default, when building LilyPond’s documentation,
244 ‘pdfTeX’ is be used. However ligatures (fi, fl, ff etc.) may
245 not be printed in the PDF output. In this case XeTeX can be
246 used instead. Download and install the ‘texlive-xetex’
249 sudo apt-get install texlive-xetex
251 The scripts used to build the LilyPond documentation will use
252 ‘XeTex’ instead of ‘pdfTex’ to generate the PDF documents if
253 it is available. No additional configuration is required.
258 The following instructions were tested on ‘OpenSUSE 13.2’ and will
259 download all the software required to both compile LilyPond and build
262 • Add the _sources_ repository;
264 sudo zypper addrepo -f \
265 "http://download.opensuse.org/source/distribution/13.2/repo/oss/" sources
267 • Download and install all the LilyPond build-dependencies
268 (approximately 680MB);
270 sudo zypper source-install lilypond
272 • Download and install additional ‘build’ tools required for
275 sudo zypper install make
277 • Although not ‘required’ to compile LilyPond, if you intend to
278 contribute to LilyPond (codebase or help improve the documentation)
279 then it is recommended that you also need to install ‘git’.
281 sudo zypper install git
283 Also see *note (lilypond-contributor)Starting with Git::.
285 • To use the ‘lily-git.tcl’ GUI;
287 sudo zypper install tk
289 Also see *note (lilypond-contributor)lily-git::.
291 Note: By default, when building LilyPond’s documentation,
292 ‘pdfTeX’ is be used. However ligatures (fi, fl, ff etc.) may
293 not be printed in the PDF output. In this case XeTeX can be
294 used instead. Download and install the ‘texlive-xetex’
297 sudo zypper install texlive-xetex
299 The scripts used to build the LilyPond documentation will use
300 ‘XeTex’ instead of ‘pdfTex’ to generate the PDF documents if
301 it is available. No additional configuration is required.
306 The following commands were tested on Ubuntu versions ‘14.04 LTS’,
307 ‘14.10’ and ‘15.04’ and will download all the software required to both
308 compile LilyPond and build the documentation.
310 • Download and install all the LilyPond build-dependencies
311 (approximately 200MB);
313 sudo apt-get build-dep lilypond
315 • Download and install additional ‘build’ tools required for
318 sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
320 • Although not ‘required’ to compile LilyPond, if you intend to
321 contribute to LilyPond (codebase or help improve the documentation)
322 then it is recommended that you also need to install ‘git’.
324 sudo apt-get install git
326 Also see *note (lilypond-contributor)Starting with Git::.
328 • To use the ‘lily-git.tcl’ GUI;
330 sudo apt-get install tk
332 Also see *note (lilypond-contributor)lily-git::.
334 Note: By default, when building LilyPond’s documentation,
335 ‘pdfTeX’ is be used. However ligatures (fi, fl, ff etc.) may
336 not be printed in the PDF output. In this case XeTeX can be
337 used instead. Download and install the ‘texlive-xetex’
340 sudo apt-get install texlive-xetex
342 The scripts used to build the LilyPond documentation will use
343 ‘XeTex’ instead of ‘pdfTex’ to generate the PDF documents if
344 it is available. No additional configuration is required.
349 The following individual software packages are required just to compile
352 • GNU Autoconf (http://www.gnu.org/software/autoconf)
354 • GNU Bison (http://www.gnu.org/software/bison/)
356 Use version ‘2.0’ or newer.
358 • GNU Compiler Collection (http://gcc.gnu.org/)
360 Use version ‘3.4’ or newer (‘4.x’ recommended).
362 • Flex (http://flex.sourceforge.net/)
364 • FontForge (http://fontforge.sf.net/)
366 Use version ‘20060125’ or newer (we recommend using at least
367 ‘20100501’); it must also be compiled with the ‘--enable-double’
368 switch, else this can lead to inaccurate intersection calculations
369 which end up with poorly-rendered glyphs in the output.
371 • GNU gettext (http://www.gnu.org/software/gettext/gettext.html)
373 Use version ‘0.17’ or newer.
375 • GNU Make (http://www.gnu.org/software/make/)
377 Use version ‘3.78’ or newer.
379 • MetaFont (http://metafont.tutorial.free.fr/)
381 The ‘mf-nowin’, ‘mf’, ‘mfw’ or ‘mfont’ binaries are usually
382 packaged along with TeX (http://www.latex-project.org/ftp.html).
384 • MetaPost (http://cm.bell-labs.com/who/hobby/MetaPost.html)
386 The ‘mpost’ binary is also usually packaged with TeX
387 (http://www.latex-project.org/ftp.html).
389 • Perl (http://www.perl.org/)
391 • Texinfo (http://www.gnu.org/software/texinfo/)
393 Use version ‘4.11’ or newer.
395 • Type 1 utilities (http://www.lcdf.org/~eddietwo/type/#t1utils)
397 Use version ‘1.33’ or newer.
399 • Cyrillic fonts (https://www.ctan.org/pkg/cyrillic?lang=en)
401 Often packaged in repositories as ‘texlive-lang-cyrillic’.
403 • TeX Gyre ‘OTF’ font packages. As of LilyPond version ‘2.19.26’,
404 the previous default serif, san serif and monospace fonts now use
405 Tex Gyre’s _Schola_, _Heros_ and _Cursor_ fonts respectively. Also
406 See *note (lilypond-notation)Fonts::.
408 Some distributions do not always provide ‘OTF’ font files in the
409 Tex Gyre packages from their repositories. Use the command
410 ‘fc-list | grep texgyre’ to list the fonts available to your system
411 and check that the appropriate ‘*.otf’ files are reported. If they
412 are not then download and manually extract the ‘OTF’ files to
413 either your local ‘~/.fonts/’ directory or use the ‘configure’
414 command and the ‘--with-texgyre-dir=/path_to_otf_files/’ option.
416 The following font families are required:
418 Schola (http://www.gust.org.pl/projects/e-foundry/tex-gyre/schola),
419 Heros (http://www.gust.org.pl/projects/e-foundry/tex-gyre/heros)
421 (http://www.gust.org.pl/projects/e-foundry/tex-gyre/cursor).
423 1.2.3 Requirements for building documentation
424 ---------------------------------------------
426 The entire set of documentation for the most current build of LilyPond
427 is available online at
428 <http://lilypond.org/doc/v2.19/Documentation/web/development>, but you
429 can also build them locally from the source code. This process requires
430 some additional tools and packages.
432 Note: If the instructions for one of the previously listed
433 Linux in the previous section (*note
434 (lilypond-contributor)Requirements for compiling LilyPond::)
435 have been used, then the following can be ignored as the
436 software should already be installed.
438 • Everything listed in *note Requirements for compiling LilyPond::
440 • ImageMagick (http://www.imagemagick.org/)
442 • Netpbm (http://netpbm.sourceforge.net/)
444 • gzip (http://gzip.org/)
446 • rsync (http://rsync.samba.org/)
448 • Texi2HTML (http://www.nongnu.org/texi2html/)
450 Use version ‘1.82’. Later versions will not work.
452 Download ‘texi2html 1.82’ directly from:
453 <http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz>;
455 Extract the files into an appropriate location and then run the
462 Now verify that your operating system is able to see the correct
463 version of ‘texi2html’.
467 • Fonts required to build the documentation in addition to those
468 required to run LilyPond:
476 texlive-fonts-recommended
479 Note: By default, when building LilyPond’s documentation,
480 ‘pdfTeX’ is be used. However ligatures (fi, fl, ff etc.) may
481 not be printed in the PDF output. In this case XeTeX can be
482 used instead. Download and install the ‘texlive-xetex’
483 package. The scripts used to build the LilyPond documentation
484 will use ‘XeTex’ instead of ‘pdfTex’ to generate the PDF
485 documents if it is available. No additional configuration is
488 1.3 Getting the source code
489 ===========================
491 Downloading the Git repository
492 ------------------------------
494 In general, developers compile LilyPond from within a local Git
495 repository. Setting up a local Git repository is explained in *note
496 (lilypond-contributor)Starting with Git::.
498 Downloading a source tarball
499 ----------------------------
501 Packagers are encouraged to use source tarballs for compiling.
503 The tarball for the latest stable release is available on the *note
504 (lilypond-web)Source:: page.
506 The latest source code snapshot
507 (http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot) is also
508 available as a tarball from the GNU Savannah Git server.
510 All tagged releases (including legacy stable versions and the most
511 recent development release) are available here:
513 <http://download.linuxaudio.org/lilypond/source/>
515 Download the tarball to your ‘~/src/’ directory, or some other
518 Note: Be careful where you unpack the tarball! Any
519 subdirectories of the current folder named ‘lilypond/’ or
520 ‘lilypond-X.Y.Z/’ (where X.Y.Z is the release number) will be
521 overwritten if there is a name clash with the tarball.
523 Unpack the tarball with this command:
525 tar -xzf lilypond-X.Y.Z.tar.gz
527 This creates a subdirectory within the current directory called
528 ‘lilypond-X.Y.Z/’. Once unpacked, the source files occupy about 40 MB
531 Windows users wanting to look at the source code may have to download
532 and install the free-software 7zip archiver (http://www.7-zip.org) to
535 1.4 Configuring ‘make’
536 ======================
538 1.4.1 Running ‘./autogen.sh’
539 ----------------------------
541 After you unpack the tarball (or download the Git repository), the
542 contents of your top source directory should be similar to the current
543 source tree listed at
544 <http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree>.
546 Next, you need to create the generated files; enter the following
547 command from your top source directory:
549 ./autogen.sh --noconfigure
551 This will generate a number of files and directories to aid
552 configuration, such as ‘configure’, ‘README.txt’, etc.
554 Next, create the build directory with:
559 We heavily recommend building lilypond inside a separate directory
562 1.4.2 Running ‘../configure’
563 ----------------------------
565 Configuration options
566 .....................
568 Note: make sure that you are in the ‘build/’ subdirectory of
571 The ‘../configure’ command (generated by ‘./autogen.sh’) provides
572 many options for configuring ‘make’. To see them all, run:
576 Checking build dependencies
577 ...........................
579 Note: make sure that you are in the ‘build/’ subdirectory of
582 When ‘../configure’ is run without any arguments, it will check to
583 make sure your system has everything required for compilation:
587 If any build dependency is missing, ‘../configure’ will return with:
589 ERROR: Please install required programs: FOO
591 The following message is issued if you are missing programs that are
592 only needed for building the documentation:
594 WARNING: Please consider installing optional programs: BAR
596 If you intend to build the documentation locally, you will need to
597 install or update these programs accordingly.
599 Note: ‘../configure’ may fail to issue warnings for certain
600 documentation build requirements that are not met. If you
601 experience problems when building the documentation, you may
602 need to do a manual check of *note Requirements for building
605 Configuring target directories
606 ..............................
608 Note: make sure that you are in the ‘build/’ subdirectory of
611 If you intend to use your local build to install a local copy of the
612 program, you will probably want to configure the installation directory.
613 Here are the relevant lines taken from the output of
614 ‘../configure --help’:
616 By default, ‘‘make install’’ will install all the files in
617 ‘/usr/local/bin’, ‘/usr/local/lib’ etc. You can specify an
618 installation prefix other than ‘/usr/local’ using ‘‘--prefix’’, for
619 instance ‘‘--prefix=$HOME’’.
621 A typical installation prefix is ‘$HOME/usr’:
623 ../configure --prefix=$HOME/usr
625 Note that if you plan to install a local build on a system where you
626 do not have root privileges, you will need to do something like this
627 anyway—‘make install’ will only succeed if the installation prefix
628 points to a directory where you have write permission (such as your home
629 directory). The installation directory will be automatically created if
632 The location of the ‘lilypond’ command installed by this process will
633 be ‘PREFIX/bin/lilypond’; you may want to add ‘PREFIX/bin/’ to your
634 ‘$PATH’ if it is not already included.
636 It is also possible to specify separate installation directories for
637 different types of program files. See the full output of
638 ‘../configure --help’ for more information.
640 If you encounter any problems, please see *note Problems::.
642 1.5 Compiling LilyPond
643 ======================
648 Note: make sure that you are in the ‘build/’ subdirectory of
651 LilyPond is compiled with the ‘make’ command. Assuming ‘make’ is
652 configured properly, you can simply run:
656 ‘make’ is short for ‘make all’. To view a list of ‘make’ targets,
661 TODO: Describe what ‘make’ actually does.
667 *note Generating documentation:: provides more info on the ‘make’
668 targets used to build the LilyPond documentation.
670 1.5.2 Saving time with the ‘-j’ option
671 --------------------------------------
673 If your system has multiple CPUs, you can speed up compilation by adding
674 ‘-jX’ to the ‘make’ command, where ‘X’ is one more than the number of
675 cores you have. For example, a typical Core2Duo machine would use:
679 If you get errors using the ‘-j’ option, and ‘make’ succeeds without
680 it, try lowering the ‘X’ value.
682 Because multiple jobs run in parallel when ‘-j’ is used, it can be
683 difficult to determine the source of an error when one occurs. In that
684 case, running ‘make’ without the ‘-j’ is advised.
686 1.5.3 Compiling for multiple platforms
687 --------------------------------------
689 If you want to build multiple versions of LilyPond with different
690 configuration settings, you can use the ‘--enable-config=CONF’ option of
691 ‘configure’. You should use ‘make conf=CONF’ to generate the output in
692 ‘out-CONF’. For example, suppose you want to build with and without
693 profiling, then use the following for the normal build
695 ./configure --prefix=$HOME/usr/ --enable-checking
698 and for the profiling version, specify a different configuration
700 ./configure --prefix=$HOME/usr/ --enable-profiling \
701 --enable-config=prof --disable-checking
704 If you wish to install a copy of the build with profiling, don’t
705 forget to use ‘conf=CONF’ when issuing ‘make install’:
707 make conf=prof install
713 *note Installing LilyPond from a local build::
715 1.5.4 Useful ‘make’ variables
716 -----------------------------
718 If a less verbose build output if desired, the variable ‘QUIET_BUILD’
719 may be set to ‘1’ on ‘make’ command line, or in ‘local.make’ at top of
722 1.6 Post-compilation options
723 ============================
725 1.6.1 Installing LilyPond from a local build
726 --------------------------------------------
728 If you configured ‘make’ to install your local build in a directory
729 where you normally have write permission (such as your home directory),
730 and you have compiled LilyPond by running ‘make’, you can install the
731 program in your target directory by running:
735 If instead, your installation directory is not one that you can
736 normally write to (such as the default ‘/usr/local/’, which typically is
737 only writeable by the superuser), you will need to temporarily become
738 the superuser when running ‘make install’:
746 If you don’t have superuser privileges, then you need to configure
747 the installation directory to one that you can write to, and then
748 re-install. See *note Configuring target directories::.
750 1.6.2 Generating documentation
751 ------------------------------
753 Documentation editor’s edit/compile cycle
754 .........................................
756 • Initial documentation build:
759 make [-jX CPU_COUNT=X] doc _## can take an hour or more_
760 make [-jX CPU_COUNT=X] doc-stage-1 _## to build only PDF documentation_
762 • Edit/compile cycle:
764 _## edit source files, then..._
766 make [-jX] _## needed if editing outside_
767 _## Documentation/, but useful anyway_
768 _## for finding Texinfo errors._
769 make [-jX CPU_COUNT=X] doc _## usually faster than initial build._
773 It is generally possible to remove the compiled documentation from
774 your system with ‘make doc-clean’, but this method is not 100%
775 guaranteed. Instead, if you want to be sure you have a clean
776 system, we recommend that you delete your ‘build/’ directory, and
777 begin compiling from scratch. Since the documentation compile
778 takes much longer than the non-documentation compile, this does not
779 increase the overall time by a great deal.
781 Building documentation
782 ......................
784 After a successful compile (using ‘make’), the documentation can be
789 or, to build only the PDF documentation and not the HTML,
793 Note: The first time you run ‘make doc’, the process can
794 easily take an hour or more with not much output on the
797 After this initial build, ‘make doc’ only makes changes to the
798 documentation where needed, so it may only take a minute or two to test
799 changes if the documentation is already built.
801 If ‘make doc’ succeeds, the HTML documentation tree is available in
802 ‘out-www/offline-root/’, and can be browsed locally. Various portions
803 of the documentation can be found by looking in ‘out/’ and ‘out-www’
804 subdirectories in other places in the source tree, but these are only
805 _portions_ of the docs. Please do not complain about anything which is
806 broken in those places; the only complete set of documentation is in
807 ‘out-www/offline-root/’ from the top of the source tree.
809 ‘make doc’ sends the output from most of the compilation to logfiles.
810 If the build fails for any reason, it should prompt you with the name of
811 a logfile which will provide information to help you work out why the
812 build failed. These logfiles are not deleted with ‘make doc-clean’. To
813 remove all the logfiles generated by the compilation process, use:
817 ‘make doc’ compiles the documents for all languages. To save some
818 compile time, the English language documents can be compiled on their
823 Similarly, it is possible to compile a subset of the translated
824 documentation by specifying their language codes on the command line.
825 For example, the French and German translations are compiled with:
827 make LANGS='de fr' doc
829 Note that this will also compile the English version.
831 Compilation of documentation in Info format with images can be done
832 separately by issuing:
836 An issue when switching branches between master and translation is the
837 appearance/disappearance of translated versions of some manuals. If you
838 see such a warning from make:
840 No rule to make target `X', needed by `Y'
842 Your best bet is to delete the file Y.dep and to try again.
844 Building a single document
845 ..........................
847 It’s possible to build a single document. For example, to rebuild only
848 ‘contributor.pdf’, do the following:
852 touch ../../Documentation/contributor.texi
853 make out=www out-www/contributor.pdf
855 If you are only working on a single document, test-building it in
856 this way can give substantial time savings - recreating
857 ‘contributor.pdf’, for example, takes a matter of seconds.
859 Saving time with ‘CPU_COUNT’
860 ............................
862 The most time consuming task for building the documentation is running
863 LilyPond to build images of music, and there cannot be several
864 simultaneously running ‘lilypond-book’ instances, so the ‘-j’ ‘make’
865 option does not significantly speed up the build process. To help speed
866 it up, the makefile variable ‘CPU_COUNT’ may be set in ‘local.make’ or
867 on the command line to the number of ‘.ly’ files that LilyPond should
868 process simultaneously, e.g. on a bi-processor or dual core machine:
870 make -j3 CPU_COUNT=3 doc
872 The recommended value of ‘CPU_COUNT’ is one plus the number of cores or
873 processors, but it is advisable to set it to a smaller value unless your
874 system has enough RAM to run that many simultaneous LilyPond instances.
875 Also, values for the ‘-j’ option that pose problems with ‘make’ are less
876 likely to pose problems with ‘make doc’ (this applies to both ‘-j’ and
877 ‘CPU_COUNT’). For example, with a quad-core processor, it is possible
878 for ‘make -j5 CPU_COUNT=5 doc’ to work consistently even if ‘make -j5’
884 To build the documentation with interactive searching, use:
886 make doc AJAX_SEARCH=1
888 This requires PHP, and you must view the docs via a http connection
889 (you cannot view them on your local filesystem).
891 Note: Due to potential security or load issues, this option is
892 not enabled in the official documentation builds. Enable at
895 Installing documentation
896 ........................
898 The HTML, PDF and if available Info files can be installed into the
899 standard documentation path by issuing
903 This also installs Info documentation with images if the installation
904 prefix is properly set; otherwise, instructions to complete proper
905 installation of Info documentation are printed on standard output.
907 To install the Info documentation separately, run:
911 Note that to get the images in Info documentation, ‘install-doc’ target
912 creates symbolic links to HTML and PDF installed documentation tree in
913 ‘PREFIX/share/info’, in order to save disk space, whereas ‘install-info’
914 copies images in ‘PREFIX/share/info’ subdirectories.
916 It is possible to build a documentation tree in
917 ‘out-www/online-root/’, with special processing, so it can be used on a
918 website with content negotiation for automatic language selection; this
919 can be achieved by issuing
921 make WEB_TARGETS=online doc
923 and both ‘offline’ and ‘online’ targets can be generated by issuing
925 make WEB_TARGETS="offline online" doc
927 Several targets are available to clean the documentation build and
928 help with maintaining documentation; an overview of these targets is
933 from every directory in the build tree. Most targets for documentation
934 maintenance are available from ‘Documentation/’; for more information,
935 see *note (lilypond-contributor)Documentation work::.
937 The makefile variable ‘QUIET_BUILD’ may be set to ‘1’ for a less
938 verbose build output, just like for building the programs.
940 Building documentation without compiling
941 ........................................
943 The documentation can be built locally without compiling LilyPond
944 binary, if LilyPond is already installed on your system.
946 From a fresh Git checkout, do
948 ./autogen.sh # ignore any warning messages
949 cp GNUmakefile.in GNUmakefile
950 make -C scripts && make -C python
951 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
953 Please note that this may break sometimes – for example, if a new
954 feature is added with a test file in input/regression, even the latest
955 development release of LilyPond will fail to build the docs.
957 You may build the manual without building all the ‘input/*’ stuff
958 (i.e. mostly regression tests): change directory, for example to
959 ‘Documentation/’, issue ‘make doc’, which will build documentation in a
960 subdirectory ‘out-www’ from the source files in current directory. In
961 this case, if you also want to browse the documentation in its
962 post-processed form, change back to top directory and issue
964 make out=www WWW-post
967 Known issues and warnings
968 .........................
970 You may also need to create a script for ‘pngtopnm’ and ‘pnmtopng’. On
971 GNU/Linux, I use this:
973 export LD_LIBRARY_PATH=/usr/lib
974 exec /usr/bin/pngtopnm "$@"
976 On MacOS X with fink, I use this:
978 export DYLD_LIBRARY_PATH=/sw/lib
979 exec /sw/bin/pngtopnm "$@"
981 On MacOS X with macports, you should use this:
983 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
984 exec /opt/local/bin/pngtopnm "$@"
986 1.6.3 Testing LilyPond binary
987 -----------------------------
989 LilyPond comes with an extensive suite that exercises the entire
990 program. This suite can be used to test that the binary has been built
993 The test suite can be executed with:
997 If the test suite completes successfully, the LilyPond binary has
1000 More information on the regression test suite is found at *note
1001 (lilypond-contributor)Regression tests::.
1006 For help and questions use <lilypond-user@gnu.org>. Send bug reports to
1007 <bug-lilypond@gnu.org>.
1009 Bugs that are not fault of LilyPond are documented here.
1011 Compiling on MacOS X
1012 --------------------
1014 Here are special instructions for compiling under MacOS X. These
1015 instructions assume that dependencies are installed using MacPorts.
1016 (http://www.macports.org/) The instructions have been tested using OS X
1019 First, install the relevant dependencies using MacPorts.
1021 Next, add the following to your relevant shell initialization files.
1022 This is ‘~/.profile’ by default. You should create this file if it does
1025 export PATH=/opt/local/bin:/opt/local/sbin:$PATH
1026 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
1028 Now you must edit the generated ‘config.make’ file. Change
1030 FLEXLEXER_FILE = /usr/include/FlexLexer.h
1034 FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
1036 At this point, you should verify that you have the appropriate fonts
1037 installed with your ghostscript installation. Check ‘ls
1038 /opt/local/share/ghostscript/fonts’ for: ’c0590*’ files (.pfb, .pfb and
1039 .afm). If you don’t have them, run the following commands to grab them
1040 from the ghostscript SVN server and install them in the appropriate
1043 svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
1044 sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
1045 rm -rf urw-fonts-1.07pre44
1047 Now run the ‘./configure’ script. To avoid complications with
1048 automatic font detection, add
1050 --with-fonts-dir=/opt/local/share/ghostscript/fonts
1055 Solaris7, ./configure
1057 ‘./configure’ needs a POSIX compliant shell. On Solaris7, ‘/bin/sh’
1058 is not yet POSIX compliant, but ‘/bin/ksh’ or bash is. Run configure
1061 CONFIG_SHELL=/bin/ksh ksh -c ./configure
1065 CONFIG_SHELL=/bin/bash bash -c ./configure
1070 To use system fonts, dejaview must be installed. With the default port,
1071 the fonts are installed in ‘usr/X11R6/lib/X11/fonts/dejavu’.
1073 Open the file ‘$LILYPONDBASE/usr/etc/fonts/local.conf’ and add the
1074 following line just after the ‘<fontconfig>’ line. (Adjust as necessary
1075 for your hierarchy.)
1077 <dir>/usr/X11R6/lib/X11/fonts</dir>
1082 On Mac OS X, all fonts are installed by default. However, finding all
1083 system fonts requires a bit of configuration; see this post
1084 (http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
1085 on the ‘lilypond-user’ mailing list.
1087 On Linux, international fonts are installed by different means on
1088 every distribution. We cannot list the exact commands or packages that
1089 are necessary, as each distribution is different, and the exact package
1090 names within each distribution changes. Here are some hints, though:
1094 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
1095 ttfonts-zh_CN fonts-ja fonts-hebrew
1099 apt-get install emacs-intl-fonts xfonts-intl-.* \
1100 fonts-ipafont-gothic fonts-ipafont-mincho \
1101 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
1103 Using lilypond python libraries
1104 -------------------------------
1106 If you want to use lilypond’s python libraries (either running certain
1107 build scripts manually, or using them in other programs), set
1108 ‘PYTHONPATH’ to ‘python/out’ in your build directory, or
1109 ‘.../usr/lib/lilypond/current/python’ in the installation directory
1112 1.8 Concurrent stable and development versions
1113 ==============================================
1115 It can be useful to have both the stable and the development versions of
1116 LilyPond available at once. One way to do this on GNU/Linux is to
1117 install the stable version using the precompiled binary, and run the
1118 development version from the source tree. After running ‘make all’ from
1119 the top directory of the LilyPond source files, there will be a binary
1120 called ‘lilypond’ in the ‘out’ directory:
1122 <PATH TO>/lilypond/out/bin/lilypond
1124 This binary can be run without actually doing the ‘make install’
1125 command. The advantage to this is that you can have all of the latest
1126 changes available after pulling from git and running ‘make all’, without
1127 having to uninstall the old version and reinstall the new.
1129 So, to use the stable version, install it as usual and use the normal
1134 To use the development version, create a link to the binary in the
1135 source tree by saving the following line in a file somewhere in your
1138 exec <PATH TO>/lilypond/out/bin/lilypond "$@"
1140 Save it as ‘Lilypond’ (with a capital L to distinguish it from the
1141 stable ‘lilypond’), and make it executable:
1145 Then you can invoke the development version this way:
1151 - other compilation tricks for developers
1156 We currently use make and stepmake, which is complicated and only used
1157 by us. Hopefully this will change in the future.
1159 Version-specific texinfo macros
1160 -------------------------------
1162 • made with ‘scripts/build/create-version-itexi.py’ and
1163 ‘scripts/build/create-weblinks-itexi.py’
1165 • used extensively in the ‘WEBSITE_ONLY_BUILD’ version of the website
1166 (made with ‘website.make’, used on lilypond.org)
1168 • not (?) used in the main docs?
1170 • the numbers in VERSION file: MINOR_VERSION should be 1 more than
1171 the last release, VERSION_DEVEL should be the last *online*
1172 release. Yes, VERSION_DEVEL is less than VERSION.