1 INSTALL - compiling and installing GNU LilyPond
2 ***********************************************
7 INSTALL - compiling and installing GNU LilyPond
9 1.1 Overview of compiling
11 1.2.1 Requirements for running LilyPond
12 1.2.2 Requirements for compiling LilyPond
18 1.2.3 Requirements for building documentation
19 1.3 Getting the source code
20 1.4 Configuring `make'
21 1.4.1 Running `./autogen.sh'
22 1.4.2 Running `../configure'
24 Checking build dependencies
25 Configuring target directories
26 1.5 Compiling LilyPond
28 1.5.2 Saving time with the `-j' option
29 1.5.3 Compiling for multiple platforms
30 1.5.4 Useful `make' variables
31 1.6 Post-compilation options
32 1.6.1 Installing LilyPond from a local build
33 1.6.2 Generating documentation
34 Documentation editor's edit/compile cycle
35 Building documentation
36 Building a single document
37 Saving time with `CPU_COUNT'
39 Installing documentation
40 Building documentation without compiling
41 1.6.3 Testing LilyPond binary
47 Using lilypond python libraries
48 1.8 Concurrent stable and development versions
55 1.1 Overview of compiling
56 =========================
58 Compiling LilyPond from source is an involved process, and is only
59 recommended for developers and packagers. Typical program users are
60 instead encouraged to obtain the program from a package manager (on
61 Unix) or by downloading a precompiled binary configured for a specific
62 operating system. Pre-compiled binaries are available on the *note
63 Download: (lilypond-web)Download. page.
65 Compiling LilyPond from source is necessary if you want to build,
66 install, or test your own version of the program.
68 A successful compile can also be used to generate and install the
69 documentation, incorporating any changes you may have made. However, a
70 successful compile is not a requirement for generating the
71 documentation. The documentation can be built using a Git repository
72 in conjunction with a locally installed copy of the program. For more
73 information, see *note Building documentation without compiling::.
75 Attempts to compile LilyPond natively on Windows have been
76 unsuccessful, though a workaround is available (see *note LilyDev:
77 (lilypond-contributor)LilyDev.).
82 1.2.1 Requirements for running LilyPond
83 ---------------------------------------
85 This section contains the list of separate software packages that are
86 required to run LilyPond.
88 * DejaVu fonts (http://www.dejavu-fonts.org/) These are normally
91 * FontConfig (http://www.fontconfig.org/) Use version 2.4.0 or newer.
93 * Freetype (http://www.freetype.org/) Use version 2.1.10 or newer.
95 * Ghostscript (http://www.ghostscript.com) Use version 8.60 or newer.
97 * Guile (http://www.gnu.org/software/guile/guile.html) Use version
98 1.8.8. Version 2.x of Guile is not currently supported.
100 * Pango (http://www.pango.org/) User version 1.12 or newer.
102 * Python (http://www.python.org) Use version 2.4 or newer.
104 * International fonts. For example:
116 Debian based distributions:
126 These are normally installed by default and are required only to
127 create music with international text or lyrics.
130 1.2.2 Requirements for compiling LilyPond
131 -----------------------------------------
133 This section contains instructions on how to quickly and easily get all
134 the software packages required to build LilyPond.
136 Most of the more popular Linux distributions only require a few
137 simple commands to download all the software needed. For others, there
138 is an explicit list of all the individual packages (as well as where to
139 get them from) for those that are not already included in your
140 distributions' own repositories.
145 The following instructions were tested on `Fedora' versions 22 & 23 and
146 will download all the software required to both compile LilyPond and
147 build the documentation.
149 * Download and install all the LilyPond build-dependencies
150 (approximately 700MB);
152 sudo dnf builddep lilypond --nogpgcheck
154 * Download and install additional `build' tools required for
157 sudo dnf install autoconf gcc-c++
159 * Download `texi2html 1.82' directly from:
160 `http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz';
162 `texi2html' is only required if you intend to compile LilyPond's
163 own documentation (e.g. to help with any document writing). The
164 version available in the Fedora repositories is too new and will
165 not work. Extract the files into an appropriate location and then
172 This should install `texi2html 1.82' into `/usr/local/bin', which
173 will normally take priority over `/usr/bin' where the later,
174 pre-installed versions gets put. Now verify that your operating
175 system is able to see the correct version of `texi2html'.
179 * Although not `required' to compile LilyPond, if you intend to
180 contribute to LilyPond (codebase or help improve the
181 documentation) then it is recommended that you also need to
186 Also see *note Starting with Git: (lilypond-notation)Starting with
189 * To use the `lily-git.tcl' GUI;
193 See *note lily-git: (lilypond-notation)lily-git.
196 Note: By default, when building LilyPond's documentation,
197 `pdfTeX' is be used. However ligatures (fi, fl, ff etc.) may
198 not be printed in the PDF output. In this case XeTeX can be
199 used instead. Download and install the `texlive-xetex'
202 sudo dnf install texlive-xetex
204 The scripts used to build the LilyPond documentation will use
205 `XeTex' instead of `pdfTex' to generate the PDF documents if
206 it is available. No additional configuration is required.
211 The following instructions were tested on `Linux Mint 17.1' and `LMDE -
212 Betsy' and will download all the software required to both compile
213 LilyPond and build the documentation..
215 * Enable the _sources_ repository;
217 1. Using the _Software Sources_ GUI (located under
220 2. Select _Official Repositories_.
222 3. Check the _Enable source code repositories_ box under the
223 _Source Code_ section.
225 4. Click the _Update the cache_ button and when it has completed,
226 close the _Software Sources_ GUI.
229 * Download and install all the LilyPond build-dependencies
230 (approximately 200MB);
232 sudo apt-get build-dep lilypond
234 * Download and install additional `build' tools required for
237 sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
239 * Although not `required' to compile LilyPond, if you intend to
240 contribute to LilyPond (codebase or help improve the
241 documentation) then it is recommended that you also need to
244 sudo apt-get install git
246 Also see *note Starting with Git: (lilypond-notation)Starting with
249 * To use the `lily-git.tcl' GUI;
251 sudo apt-get install tk
253 Also see *note lily-git: (lilypond-notation)lily-git.
256 Note: By default, when building LilyPond's documentation,
257 `pdfTeX' is be used. However ligatures (fi, fl, ff etc.) may
258 not be printed in the PDF output. In this case XeTeX can be
259 used instead. Download and install the `texlive-xetex'
262 sudo apt-get install texlive-xetex
264 The scripts used to build the LilyPond documentation will use
265 `XeTex' instead of `pdfTex' to generate the PDF documents if
266 it is available. No additional configuration is required.
271 The following instructions were tested on `OpenSUSE 13.2' and will
272 download all the software required to both compile LilyPond and build
275 * Add the _sources_ repository;
277 sudo zypper addrepo -f \
278 "http://download.opensuse.org/source/distribution/13.2/repo/oss/" sources
280 * Download and install all the LilyPond build-dependencies
281 (approximately 680MB);
283 sudo zypper source-install lilypond
285 * Download and install additional `build' tools required for
288 sudo zypper install make
290 * Although not `required' to compile LilyPond, if you intend to
291 contribute to LilyPond (codebase or help improve the
292 documentation) then it is recommended that you also need to
295 sudo zypper install git
297 Also see *note Starting with Git: (lilypond-notation)Starting with
300 * To use the `lily-git.tcl' GUI;
302 sudo zypper install tk
304 Also see *note lily-git: (lilypond-notation)lily-git.
307 Note: By default, when building LilyPond's documentation,
308 `pdfTeX' is be used. However ligatures (fi, fl, ff etc.) may
309 not be printed in the PDF output. In this case XeTeX can be
310 used instead. Download and install the `texlive-xetex'
313 sudo zypper install texlive-xetex
315 The scripts used to build the LilyPond documentation will use
316 `XeTex' instead of `pdfTex' to generate the PDF documents if
317 it is available. No additional configuration is required.
322 The following commands were tested on Ubuntu versions `14.04 LTS',
323 `14.10' and `15.04' and will download all the software required to both
324 compile LilyPond and build the documentation.
326 * Download and install all the LilyPond build-dependencies
327 (approximately 200MB);
329 sudo apt-get build-dep lilypond
331 * Download and install additional `build' tools required for
334 sudo apt-get install autoconf fonts-texgyre texlive-lang-cyrillic
336 * Although not `required' to compile LilyPond, if you intend to
337 contribute to LilyPond (codebase or help improve the
338 documentation) then it is recommended that you also need to
341 sudo apt-get install git
343 Also see *note Starting with Git: (lilypond-notation)Starting with
346 * To use the `lily-git.tcl' GUI;
348 sudo apt-get install tk
350 Also see *note lily-git: (lilypond-notation)lily-git.
353 Note: By default, when building LilyPond's documentation,
354 `pdfTeX' is be used. However ligatures (fi, fl, ff etc.) may
355 not be printed in the PDF output. In this case XeTeX can be
356 used instead. Download and install the `texlive-xetex'
359 sudo apt-get install texlive-xetex
361 The scripts used to build the LilyPond documentation will use
362 `XeTex' instead of `pdfTex' to generate the PDF documents if
363 it is available. No additional configuration is required.
368 The following individual software packages are required just to compile
371 * GNU Autoconf (http://www.gnu.org/software/autoconf)
373 * GNU Bison (http://www.gnu.org/software/bison/)
375 Use version `2.0' or newer.
377 * GNU Compiler Collection (http://gcc.gnu.org/)
379 Use version `3.4' or newer (`4.x' recommended).
381 * Flex (http://flex.sourceforge.net/)
383 * FontForge (http://fontforge.sf.net/)
385 Use version `20060125' or newer (we recommend using at least
386 `20100501'); it must also be compiled with the `--enable-double'
387 switch, else this can lead to inaccurate intersection calculations
388 which end up with poorly-rendered glyphs in the output.
390 * GNU gettext (http://www.gnu.org/software/gettext/gettext.html)
392 Use version `0.17' or newer.
394 * GNU Make (http://www.gnu.org/software/make/)
396 Use version `3.78' or newer.
398 * MetaFont (http://metafont.tutorial.free.fr/)
400 The `mf-nowin', `mf', `mfw' or `mfont' binaries are usually
401 packaged along with TeX (http://www.latex-project.org/ftp.html).
403 * MetaPost (http://cm.bell-labs.com/who/hobby/MetaPost.html)
405 The `mpost' binary is also usually packaged with TeX
406 (http://www.latex-project.org/ftp.html).
408 * Perl (http://www.perl.org/)
410 * Texinfo (http://www.gnu.org/software/texinfo/)
412 Use version `4.11' or newer.
414 * Type 1 utilities (http://www.lcdf.org/~eddietwo/type/#t1utils)
416 Use version `1.33' or newer.
418 * Cyrillic fonts (https://www.ctan.org/pkg/cyrillic?lang=en)
420 Often packaged in repositories as `texlive-lang-cyrillic'.
422 * TeX Gyre `OTF' font packages. As of LilyPond version `2.19.26',
423 the previous default serif, san serif and monospace fonts now use
424 Tex Gyre's _Schola_, _Heros_ and _Cursor_ fonts respectively.
425 Also See *note Fonts: (lilypond-notation)Fonts.
427 Some distributions do not always provide `OTF' font files in the
428 Tex Gyre packages from their repositories. Use the command
429 `fc-list | grep texgyre' to list the fonts available to your system
430 and check that the appropriate `*.otf' files are reported. If they
431 are not then download and manually extract the `OTF' files to
432 either your local `~/.fonts/' directory or use the `configure'
433 command and the `--with-texgyre-dir=/path_to_otf_files/' option.
435 The following font families are required:
437 Schola (http://www.gust.org.pl/projects/e-foundry/tex-gyre/schola),
438 Heros (http://www.gust.org.pl/projects/e-foundry/tex-gyre/heros)
440 (http://www.gust.org.pl/projects/e-foundry/tex-gyre/cursor).
443 1.2.3 Requirements for building documentation
444 ---------------------------------------------
446 The entire set of documentation for the most current build of LilyPond
447 is available online at
448 `http://lilypond.org/doc/v2.19/Documentation/web/development', but you
449 can also build them locally from the source code. This process
450 requires some additional tools and packages.
452 Note: If the instructions for one of the previously listed
453 Linux in the previous section (*note Requirements for
454 compiling LilyPond: (lilypond-contributor)Requirements for
455 compiling LilyPond.) have been used, then the following can
456 be ignored as the software should already be installed.
458 * Everything listed in *note Requirements for compiling LilyPond::
460 * ImageMagick (http://www.imagemagick.org/)
462 * Netpbm (http://netpbm.sourceforge.net/)
464 * gzip (http://gzip.org/)
466 * rsync (http://rsync.samba.org/)
468 * Texi2HTML (http://www.nongnu.org/texi2html/)
470 Use version `1.82'. Later versions will not work.
472 Download `texi2html 1.82' directly from:
473 `http://download.savannah.gnu.org/releases/texi2html/texi2html-1.82.tar.gz';
475 Extract the files into an appropriate location and then run the
482 Now verify that your operating system is able to see the correct
483 version of `texi2html'.
487 * Fonts required to build the documentation in addition to those
488 required to run LilyPond:
496 texlive-fonts-recommended
500 Note: By default, when building LilyPond's documentation,
501 `pdfTeX' is be used. However ligatures (fi, fl, ff etc.) may
502 not be printed in the PDF output. In this case XeTeX can be
503 used instead. Download and install the `texlive-xetex'
504 package. The scripts used to build the LilyPond documentation
505 will use `XeTex' instead of `pdfTex' to generate the PDF
506 documents if it is available. No additional configuration is
509 1.3 Getting the source code
510 ===========================
512 Downloading the Git repository
513 ------------------------------
515 In general, developers compile LilyPond from within a local Git
516 repository. Setting up a local Git repository is explained in *note
517 Starting with Git: (lilypond-contributor)Starting with Git.
519 Downloading a source tarball
520 ----------------------------
522 Packagers are encouraged to use source tarballs for compiling.
524 The tarball for the latest stable release is available on the *note
525 Source: (lilypond-web)Source. page.
527 The latest source code snapshot
528 (http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot) is also
529 available as a tarball from the GNU Savannah Git server.
531 All tagged releases (including legacy stable versions and the most
532 recent development release) are available here:
534 `http://download.linuxaudio.org/lilypond/source/'
536 Download the tarball to your `~/src/' directory, or some other
539 Note: Be careful where you unpack the tarball! Any
540 subdirectories of the current folder named `lilypond/' or
541 `lilypond-X.Y.Z/' (where X.Y.Z is the release number) will be
542 overwritten if there is a name clash with the tarball.
544 Unpack the tarball with this command:
546 tar -xzf lilypond-X.Y.Z.tar.gz
548 This creates a subdirectory within the current directory called
549 `lilypond-X.Y.Z/'. Once unpacked, the source files occupy about 40 MB
552 Windows users wanting to look at the source code may have to
553 download and install the free-software 7zip archiver
554 (http://www.7-zip.org) to extract the tarball.
556 1.4 Configuring `make'
557 ======================
559 1.4.1 Running `./autogen.sh'
560 ----------------------------
562 After you unpack the tarball (or download the Git repository), the
563 contents of your top source directory should be similar to the current
564 source tree listed at
565 `http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree'.
567 Next, you need to create the generated files; enter the following
568 command from your top source directory:
570 ./autogen.sh --noconfigure
572 This will generate a number of files and directories to aid
573 configuration, such as `configure', `README.txt', etc.
575 Next, create the build directory with:
580 We heavily recommend building lilypond inside a separate directory
583 1.4.2 Running `../configure'
584 ----------------------------
586 Configuration options
587 .....................
589 Note: make sure that you are in the `build/' subdirectory of
592 The `../configure' command (generated by `./autogen.sh') provides many
593 options for configuring `make'. To see them all, run:
597 Checking build dependencies
598 ...........................
600 Note: make sure that you are in the `build/' subdirectory of
603 When `../configure' is run without any arguments, it will check to make
604 sure your system has everything required for compilation:
608 If any build dependency is missing, `../configure' will return with:
610 ERROR: Please install required programs: FOO
612 The following message is issued if you are missing programs that are
613 only needed for building the documentation:
615 WARNING: Please consider installing optional programs: BAR
617 If you intend to build the documentation locally, you will need to
618 install or update these programs accordingly.
620 Note: `../configure' may fail to issue warnings for certain
621 documentation build requirements that are not met. If you
622 experience problems when building the documentation, you may
623 need to do a manual check of *note Requirements for building
626 Configuring target directories
627 ..............................
629 Note: make sure that you are in the `build/' subdirectory of
632 If you intend to use your local build to install a local copy of the
633 program, you will probably want to configure the installation
634 directory. Here are the relevant lines taken from the output of
635 `../configure --help':
637 By default, ``make install'' will install all the files in
638 `/usr/local/bin', `/usr/local/lib' etc. You can specify an
639 installation prefix other than `/usr/local' using ``--prefix'',
640 for instance ``--prefix=$HOME''.
642 A typical installation prefix is `$HOME/usr':
644 ../configure --prefix=$HOME/usr
646 Note that if you plan to install a local build on a system where you
647 do not have root privileges, you will need to do something like this
648 anyway--`make install' will only succeed if the installation prefix
649 points to a directory where you have write permission (such as your
650 home directory). The installation directory will be automatically
651 created if necessary.
653 The location of the `lilypond' command installed by this process
654 will be `PREFIX/bin/lilypond'; you may want to add `PREFIX/bin/' to
655 your `$PATH' if it is not already included.
657 It is also possible to specify separate installation directories for
658 different types of program files. See the full output of
659 `../configure --help' for more information.
661 If you encounter any problems, please see *note Problems::.
663 1.5 Compiling LilyPond
664 ======================
669 Note: make sure that you are in the `build/' subdirectory of
672 LilyPond is compiled with the `make' command. Assuming `make' is
673 configured properly, you can simply run:
677 `make' is short for `make all'. To view a list of `make' targets,
682 TODO: Describe what `make' actually does.
691 *note Generating documentation:: provides more info on the `make'
692 targets used to build the LilyPond documentation.
694 1.5.2 Saving time with the `-j' option
695 --------------------------------------
697 If your system has multiple CPUs, you can speed up compilation by
698 adding `-jX' to the `make' command, where `X' is one more than the
699 number of cores you have. For example, a typical Core2Duo machine
704 If you get errors using the `-j' option, and `make' succeeds without
705 it, try lowering the `X' value.
707 Because multiple jobs run in parallel when `-j' is used, it can be
708 difficult to determine the source of an error when one occurs. In that
709 case, running `make' without the `-j' is advised.
711 1.5.3 Compiling for multiple platforms
712 --------------------------------------
714 If you want to build multiple versions of LilyPond with different
715 configuration settings, you can use the `--enable-config=CONF' option
716 of `configure'. You should use `make conf=CONF' to generate the output
717 in `out-CONF'. For example, suppose you want to build with and without
718 profiling, then use the following for the normal build
720 ./configure --prefix=$HOME/usr/ --enable-checking
723 and for the profiling version, specify a different configuration
725 ./configure --prefix=$HOME/usr/ --enable-profiling \
726 --enable-config=prof --disable-checking
729 If you wish to install a copy of the build with profiling, don't
730 forget to use `conf=CONF' when issuing `make install':
732 make conf=prof install
740 *note Installing LilyPond from a local build::
742 1.5.4 Useful `make' variables
743 -----------------------------
745 If a less verbose build output if desired, the variable `QUIET_BUILD'
746 may be set to `1' on `make' command line, or in `local.make' at top of
749 1.6 Post-compilation options
750 ============================
752 1.6.1 Installing LilyPond from a local build
753 --------------------------------------------
755 If you configured `make' to install your local build in a directory
756 where you normally have write permission (such as your home directory),
757 and you have compiled LilyPond by running `make', you can install the
758 program in your target directory by running:
762 If instead, your installation directory is not one that you can
763 normally write to (such as the default `/usr/local/', which typically
764 is only writeable by the superuser), you will need to temporarily
765 become the superuser when running `make install':
773 If you don't have superuser privileges, then you need to configure
774 the installation directory to one that you can write to, and then
775 re-install. See *note Configuring target directories::.
777 1.6.2 Generating documentation
778 ------------------------------
780 Documentation editor's edit/compile cycle
781 .........................................
783 * Initial documentation build:
786 make [-jX CPU_COUNT=X] doc _## can take an hour or more_
787 make [-jX CPU_COUNT=X] doc-stage-1 _## to build only PDF documentation_
789 * Edit/compile cycle:
791 _## edit source files, then..._
793 make [-jX] _## needed if editing outside_
794 _## Documentation/, but useful anyway_
795 _## for finding Texinfo errors._
796 make [-jX CPU_COUNT=X] doc _## usually faster than initial build._
800 It is generally possible to remove the compiled documentation from
801 your system with `make doc-clean', but this method is not 100%
802 guaranteed. Instead, if you want to be sure you have a clean
803 system, we recommend that you delete your `build/' directory, and
804 begin compiling from scratch. Since the documentation compile
805 takes much longer than the non-documentation compile, this does
806 not increase the overall time by a great deal.
809 Building documentation
810 ......................
812 After a successful compile (using `make'), the documentation can be
817 or, to build only the PDF documentation and not the HTML,
821 Note: The first time you run `make doc', the process can
822 easily take an hour or more with not much output on the
825 After this initial build, `make doc' only makes changes to the
826 documentation where needed, so it may only take a minute or two to test
827 changes if the documentation is already built.
829 If `make doc' succeeds, the HTML documentation tree is available in
830 `out-www/offline-root/', and can be browsed locally. Various portions
831 of the documentation can be found by looking in `out/' and `out-www'
832 subdirectories in other places in the source tree, but these are only
833 _portions_ of the docs. Please do not complain about anything which is
834 broken in those places; the only complete set of documentation is in
835 `out-www/offline-root/' from the top of the source tree.
837 `make doc' sends the output from most of the compilation to
838 logfiles. If the build fails for any reason, it should prompt you with
839 the name of a logfile which will provide information to help you work
840 out why the build failed. These logfiles are not deleted with
841 `make doc-clean'. To remove all the logfiles generated by the
842 compilation process, use:
846 `make doc' compiles the documents for all languages. To save some
847 compile time, the English language documents can be compiled on their
852 Similarly, it is possible to compile a subset of the translated
853 documentation by specifying their language codes on the command line.
854 For example, the French and German translations are compiled with:
856 make LANGS='de fr' doc
858 Note that this will also compile the English version.
860 Compilation of documentation in Info format with images can be done
861 separately by issuing:
865 An issue when switching branches between master and translation is the
866 appearance/disappearance of translated versions of some manuals. If
867 you see such a warning from make:
869 No rule to make target `X', needed by `Y'
871 Your best bet is to delete the file Y.dep and to try again.
873 Building a single document
874 ..........................
876 It's possible to build a single document. For example, to rebuild only
877 `contributor.pdf', do the following:
881 touch ../../Documentation/contributor.texi
882 make out=www out-www/contributor.pdf
884 If you are only working on a single document, test-building it in
885 this way can give substantial time savings - recreating
886 `contributor.pdf', for example, takes a matter of seconds.
888 Saving time with `CPU_COUNT'
889 ............................
891 The most time consuming task for building the documentation is running
892 LilyPond to build images of music, and there cannot be several
893 simultaneously running `lilypond-book' instances, so the `-j' `make'
894 option does not significantly speed up the build process. To help
895 speed it up, the makefile variable `CPU_COUNT' may be set in
896 `local.make' or on the command line to the number of `.ly' files that
897 LilyPond should process simultaneously, e.g. on a bi-processor or dual
900 make -j3 CPU_COUNT=3 doc
902 The recommended value of `CPU_COUNT' is one plus the number of cores or
903 processors, but it is advisable to set it to a smaller value unless
904 your system has enough RAM to run that many simultaneous LilyPond
905 instances. Also, values for the `-j' option that pose problems with
906 `make' are less likely to pose problems with `make doc' (this applies
907 to both `-j' and `CPU_COUNT'). For example, with a quad-core processor,
908 it is possible for `make -j5 CPU_COUNT=5 doc' to work consistently even
909 if `make -j5' rarely succeeds.
914 To build the documentation with interactive searching, use:
916 make doc AJAX_SEARCH=1
918 This requires PHP, and you must view the docs via a http connection
919 (you cannot view them on your local filesystem).
921 Note: Due to potential security or load issues, this option is
922 not enabled in the official documentation builds. Enable at
925 Installing documentation
926 ........................
928 The HTML, PDF and if available Info files can be installed into the
929 standard documentation path by issuing
933 This also installs Info documentation with images if the installation
934 prefix is properly set; otherwise, instructions to complete proper
935 installation of Info documentation are printed on standard output.
937 To install the Info documentation separately, run:
941 Note that to get the images in Info documentation, `install-doc' target
942 creates symbolic links to HTML and PDF installed documentation tree in
943 `PREFIX/share/info', in order to save disk space, whereas
944 `install-info' copies images in `PREFIX/share/info' subdirectories.
946 It is possible to build a documentation tree in
947 `out-www/online-root/', with special processing, so it can be used on a
948 website with content negotiation for automatic language selection; this
949 can be achieved by issuing
951 make WEB_TARGETS=online doc
953 and both `offline' and `online' targets can be generated by issuing
955 make WEB_TARGETS="offline online" doc
957 Several targets are available to clean the documentation build and
958 help with maintaining documentation; an overview of these targets is
963 from every directory in the build tree. Most targets for documentation
964 maintenance are available from `Documentation/'; for more information,
965 see *note Documentation work: (lilypond-contributor)Documentation work.
967 The makefile variable `QUIET_BUILD' may be set to `1' for a less
968 verbose build output, just like for building the programs.
970 Building documentation without compiling
971 ........................................
973 The documentation can be built locally without compiling LilyPond
974 binary, if LilyPond is already installed on your system.
976 From a fresh Git checkout, do
978 ./autogen.sh # ignore any warning messages
979 cp GNUmakefile.in GNUmakefile
980 make -C scripts && make -C python
981 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
983 Please note that this may break sometimes - for example, if a new
984 feature is added with a test file in input/regression, even the latest
985 development release of LilyPond will fail to build the docs.
987 You may build the manual without building all the `input/*' stuff
988 (i.e. mostly regression tests): change directory, for example to
989 `Documentation/', issue `make doc', which will build documentation in a
990 subdirectory `out-www' from the source files in current directory. In
991 this case, if you also want to browse the documentation in its
992 post-processed form, change back to top directory and issue
994 make out=www WWW-post
997 Known issues and warnings
998 .........................
1000 You may also need to create a script for `pngtopnm' and `pnmtopng'. On
1001 GNU/Linux, I use this:
1003 export LD_LIBRARY_PATH=/usr/lib
1004 exec /usr/bin/pngtopnm "$@"
1006 On MacOS X with fink, I use this:
1008 export DYLD_LIBRARY_PATH=/sw/lib
1009 exec /sw/bin/pngtopnm "$@"
1011 On MacOS X with macports, you should use this:
1013 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
1014 exec /opt/local/bin/pngtopnm "$@"
1016 1.6.3 Testing LilyPond binary
1017 -----------------------------
1019 LilyPond comes with an extensive suite that exercises the entire
1020 program. This suite can be used to test that the binary has been built
1023 The test suite can be executed with:
1027 If the test suite completes successfully, the LilyPond binary has
1030 More information on the regression test suite is found at *note
1031 Regression tests: (lilypond-contributor)Regression tests.
1036 For help and questions use <lilypond-user@gnu.org>. Send bug reports
1037 to <bug-lilypond@gnu.org>.
1039 Bugs that are not fault of LilyPond are documented here.
1041 Compiling on MacOS X
1042 --------------------
1044 Here are special instructions for compiling under MacOS X. These
1045 instructions assume that dependencies are installed using MacPorts.
1046 (http://www.macports.org/) The instructions have been tested using OS X
1049 First, install the relevant dependencies using MacPorts.
1051 Next, add the following to your relevant shell initialization files.
1052 This is `~/.profile' by default. You should create this file if it
1055 export PATH=/opt/local/bin:/opt/local/sbin:$PATH
1056 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
1058 Now you must edit the generated `config.make' file. Change
1060 FLEXLEXER_FILE = /usr/include/FlexLexer.h
1064 FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
1066 At this point, you should verify that you have the appropriate fonts
1067 installed with your ghostscript installation. Check `ls
1068 /opt/local/share/ghostscript/fonts' for: 'c0590*' files (.pfb, .pfb and
1069 .afm). If you don't have them, run the following commands to grab them
1070 from the ghostscript SVN server and install them in the appropriate
1073 svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
1074 sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
1075 rm -rf urw-fonts-1.07pre44
1077 Now run the `./configure' script. To avoid complications with
1078 automatic font detection, add
1080 --with-fonts-dir=/opt/local/share/ghostscript/fonts
1085 Solaris7, ./configure
1087 `./configure' needs a POSIX compliant shell. On Solaris7, `/bin/sh'
1088 is not yet POSIX compliant, but `/bin/ksh' or bash is. Run configure
1091 CONFIG_SHELL=/bin/ksh ksh -c ./configure
1095 CONFIG_SHELL=/bin/bash bash -c ./configure
1100 To use system fonts, dejaview must be installed. With the default
1101 port, the fonts are installed in `usr/X11R6/lib/X11/fonts/dejavu'.
1103 Open the file `$LILYPONDBASE/usr/etc/fonts/local.conf' and add the
1104 following line just after the `<fontconfig>' line. (Adjust as necessary
1105 for your hierarchy.)
1107 <dir>/usr/X11R6/lib/X11/fonts</dir>
1112 On Mac OS X, all fonts are installed by default. However, finding all
1113 system fonts requires a bit of configuration; see this post
1114 (http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
1115 on the `lilypond-user' mailing list.
1117 On Linux, international fonts are installed by different means on
1118 every distribution. We cannot list the exact commands or packages that
1119 are necessary, as each distribution is different, and the exact package
1120 names within each distribution changes. Here are some hints, though:
1124 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
1125 ttfonts-zh_CN fonts-ja fonts-hebrew
1129 apt-get install emacs-intl-fonts xfonts-intl-.* \
1130 fonts-ipafont-gothic fonts-ipafont-mincho \
1131 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
1133 Using lilypond python libraries
1134 -------------------------------
1136 If you want to use lilypond's python libraries (either running certain
1137 build scripts manually, or using them in other programs), set
1138 `PYTHONPATH' to `python/out' in your build directory, or
1139 `.../usr/lib/lilypond/current/python' in the installation directory
1142 1.8 Concurrent stable and development versions
1143 ==============================================
1145 It can be useful to have both the stable and the development versions
1146 of Lilypond available at once. One way to do this on GNU/Linux is to
1147 install the stable version using the precompiled binary, and run the
1148 development version from the source tree. After running `make all'
1149 from the top directory of the Lilypond source files, there will be a
1150 binary called `lilypond' in the `out' directory:
1152 <PATH TO>/lilypond/out/bin/lilypond
1154 This binary can be run without actually doing the `make install'
1155 command. The advantage to this is that you can have all of the latest
1156 changes available after pulling from git and running `make all',
1157 without having to uninstall the old version and reinstall the new.
1159 So, to use the stable version, install it as usual and use the
1164 To use the development version, create a link to the binary in the
1165 source tree by saving the following line in a file somewhere in your
1168 exec <PATH TO>/lilypond/out/bin/lilypond "$@"
1170 Save it as `Lilypond' (with a capital L to distinguish it from the
1171 stable `lilypond'), and make it executable:
1175 Then you can invoke the development version this way:
1181 - other compilation tricks for developers
1186 We currently use make and stepmake, which is complicated and only used
1187 by us. Hopefully this will change in the future.
1189 Version-specific texinfo macros
1190 -------------------------------
1192 * made with `scripts/build/create-version-itexi.py' and
1193 `scripts/build/create-weblinks-itexi.py'
1195 * used extensively in the `WEBSITE_ONLY_BUILD' version of the
1196 website (made with `website.make', used on lilypond.org)
1198 * not (?) used in the main docs?
1200 * the numbers in VERSION file: MINOR_VERSION should be 1 more than
1201 the last release, VERSION_DEVEL should be the last *online*
1202 release. Yes, VERSION_DEVEL is less than VERSION.