1 INSTALL - compiling and installing GNU LilyPond
2 ***********************************************
7 INSTALL - compiling and installing GNU LilyPond
10 Requirements for running LilyPond
11 Requirements for compiling LilyPond
12 Requirements for building documentation
13 Getting the source code
15 Running `./autogen.sh'
16 Running `../configure'
18 Checking build dependencies
19 Configuring target directories
22 Saving time with the `-j' option
23 Compiling for multiple platforms
24 Useful `make' variables
25 Post-compilation options
26 Installing LilyPond from a local build
27 Generating documentation
28 Documentation editor's edit/compile cycle
29 Building documentation
30 Building a single document
31 Saving time with `CPU_COUNT'
33 Installing documentation
34 Building documentation without compiling
35 Testing LilyPond binary
42 Using lilypond python libraries
43 Concurrent stable and development versions
50 Compiling LilyPond from source is an involved process, and is only
51 recommended for developers and packagers. Typical program users are
52 instead encouraged to obtain the program from a package manager (on
53 Unix) or by downloading a precompiled binary configured for a specific
54 operating system. Pre-compiled binaries are available on the *note
55 Download: (lilypond-web)Download. page.
57 Compiling LilyPond from source is necessary if you want to build,
58 install, or test your own version of the program.
60 A successful compile can also be used to generate and install the
61 documentation, incorporating any changes you may have made. However, a
62 successful compile is not a requirement for generating the
63 documentation. The documentation can be built using a Git repository
64 in conjunction with a locally installed copy of the program. For more
65 information, see *note Building documentation without compiling::.
67 Attempts to compile LilyPond natively on Windows have been
68 unsuccessful, though a workaround is available (see *note LilyDev:
69 (lilypond-contributor)LilyDev.).
74 Requirements for running LilyPond
75 ---------------------------------
77 Running LilyPond requires proper installation of the following software:
79 * DejaVu fonts (http://www.dejavu-fonts.org/) (normally installed by
82 * FontConfig (http://www.fontconfig.org/) (2.4.0 or newer)
84 * Freetype (http://www.freetype.org/) (2.1.10 or newer)
86 * Ghostscript (http://www.ghostscript.com) (8.60 or newer)
88 * Guile (http://www.gnu.org/software/guile/guile.html) (1.8.2 or
91 * Pango (http://www.pango.org/) (1.12 or newer)
93 * Python (http://www.python.org) (2.4 or newer)
95 International fonts are required to create music with international
98 Requirements for compiling LilyPond
99 -----------------------------------
101 Below is a full list of packages needed to build LilyPond. However,
102 for most common distributions there is an easy way of installing most
103 all build dependencies in one go:
106 --------------------------------------------------------------------------
107 Debian, Ubuntu `sudo apt-get build-dep lilypond'
108 Fedora, RHEL `sudo yum-builddep lilypond'
109 openSUSE, SLED `sudo zypper --build-deps-only
110 source-install lilypond'
112 * Everything listed in *note Requirements for running LilyPond::
114 * Development packages for the above items (which should include
115 header files and libraries).
120 fontconfig-devel-VERSION
121 freetype-devel-VERSION
133 * Flex (http://flex.sourceforge.net/)
135 * FontForge (http://fontforge.sf.net/) (20060125 or newer; 20100501
136 or newer is recommended; must be compiled with `--enable-double'.
137 Failure to do so can lead to poor intersection calculations and
138 poorly-rendered glyphs.)
140 * GNU Bison (http://www.gnu.org/software/bison/)
142 * GNU Compiler Collection (http://gcc.gnu.org/) (3.4 or newer, 4.X
145 * GNU gettext (http://www.gnu.org/software/gettext/gettext.html)
148 * GNU Make (http://www.gnu.org/software/make/) (3.78 or newer)
150 * MetaFont (http://metafont.tutorial.free.fr/) (mf-nowin, mf, mfw or
151 mfont binaries), usually packaged with TeX
152 (http://www.latex-project.org/ftp.html).
154 * MetaPost (http://cm.bell-labs.com/who/hobby/MetaPost.html) (mpost
155 binary), usually packaged with TeX
156 (http://www.latex-project.org/ftp.html).
158 * Perl (http://www.perl.org/)
160 * Texinfo (http://www.gnu.org/software/texinfo/) (4.11 or newer)
162 * Type 1 utilities (http://www.lcdf.org/~eddietwo/type/#t1utils)
163 (1.33 or newer recommended)
165 Requirements for building documentation
166 ---------------------------------------
168 You can view the documentation online at
169 `http://www.lilypond.org/doc/', but you can also build it locally.
170 This process requires some additional tools and packages:
172 * Everything listed in *note Requirements for compiling LilyPond::
174 * ImageMagick (http://www.imagemagick.org/)
176 * Netpbm (http://netpbm.sourceforge.net/)
178 * gzip (http://gzip.org/)
180 * rsync (http://rsync.samba.org/)
182 * Texi2HTML (http://www.nongnu.org/texi2html/) (1.82)
184 * International fonts
206 Getting the source code
207 =======================
209 Downloading the Git repository
210 ------------------------------
212 In general, developers compile LilyPond from within a local Git
213 repository. Setting up a local Git repository is explained in *note
214 Starting with Git: (lilypond-contributor)Starting with Git.
216 Downloading a source tarball
217 ----------------------------
219 Packagers are encouraged to use source tarballs for compiling.
221 The tarball for the latest stable release is available on the *note
222 Source: (lilypond-web)Source. page.
224 The latest source code snapshot
225 (http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot) is also
226 available as a tarball from the GNU Savannah Git server.
228 All tagged releases (including legacy stable versions and the most
229 recent development release) are available here:
231 `http://download.linuxaudio.org/lilypond/source/'
233 Download the tarball to your `~/src/' directory, or some other
236 Note: Be careful where you unpack the tarball! Any
237 subdirectories of the current folder named `lilypond/' or
238 `lilypond-X.Y.Z/' (where X.Y.Z is the release number) will be
239 overwritten if there is a name clash with the tarball.
241 Unpack the tarball with this command:
243 tar -xzf lilypond-X.Y.Z.tar.gz
245 This creates a subdirectory within the current directory called
246 `lilypond-X.Y.Z/'. Once unpacked, the source files occupy about 40 MB
249 Windows users wanting to look at the source code may have to
250 download and install the free-software 7zip archiver
251 (http://www.7-zip.org) to extract the tarball.
256 Running `./autogen.sh'
257 ----------------------
259 After you unpack the tarball (or download the Git repository), the
260 contents of your top source directory should be similar to the current
261 source tree listed at
262 `http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree'.
264 Next, you need to create the generated files; enter the following
265 command from your top source directory:
267 ./autogen.sh --noconfigure
269 This will generate a number of files and directories to aid
270 configuration, such as `configure', `README.txt', etc.
272 Next, create the build directory with:
277 We heavily recommend building lilypond inside a separate directory
280 Running `../configure'
281 ----------------------
283 Configuration options
284 .....................
286 Note: make sure that you are in the `build/' subdirectory of
289 The `../configure' command (generated by `./autogen.sh') provides many
290 options for configuring `make'. To see them all, run:
294 Checking build dependencies
295 ...........................
297 Note: make sure that you are in the `build/' subdirectory of
300 When `../configure' is run without any arguments, it will check to make
301 sure your system has everything required for compilation:
305 If any build dependency is missing, `../configure' will return with:
307 ERROR: Please install required programs: FOO
309 The following message is issued if you are missing programs that are
310 only needed for building the documentation:
312 WARNING: Please consider installing optional programs: BAR
314 If you intend to build the documentation locally, you will need to
315 install or update these programs accordingly.
317 Note: `../configure' may fail to issue warnings for certain
318 documentation build requirements that are not met. If you
319 experience problems when building the documentation, you may
320 need to do a manual check of *note Requirements for building
323 Configuring target directories
324 ..............................
326 Note: make sure that you are in the `build/' subdirectory of
329 If you intend to use your local build to install a local copy of the
330 program, you will probably want to configure the installation
331 directory. Here are the relevant lines taken from the output of
332 `../configure --help':
334 By default, ``make install'' will install all the files in
335 `/usr/local/bin', `/usr/local/lib' etc. You can specify an
336 installation prefix other than `/usr/local' using ``--prefix'',
337 for instance ``--prefix=$HOME''.
339 A typical installation prefix is `$HOME/usr':
341 ../configure --prefix=$HOME/usr
343 Note that if you plan to install a local build on a system where you
344 do not have root privileges, you will need to do something like this
345 anyway--`make install' will only succeed if the installation prefix
346 points to a directory where you have write permission (such as your
347 home directory). The installation directory will be automatically
348 created if necessary.
350 The location of the `lilypond' command installed by this process
351 will be `PREFIX/bin/lilypond'; you may want to add `PREFIX/bin/' to
352 your `$PATH' if it is not already included.
354 It is also possible to specify separate installation directories for
355 different types of program files. See the full output of
356 `../configure --help' for more information.
358 If you encounter any problems, please see *note Problems::.
366 Note: make sure that you are in the `build/' subdirectory of
369 LilyPond is compiled with the `make' command. Assuming `make' is
370 configured properly, you can simply run:
374 `make' is short for `make all'. To view a list of `make' targets,
379 TODO: Describe what `make' actually does.
388 *note Generating documentation:: provides more info on the `make'
389 targets used to build the LilyPond documentation.
391 Saving time with the `-j' option
392 --------------------------------
394 If your system has multiple CPUs, you can speed up compilation by
395 adding `-jX' to the `make' command, where `X' is one more than the
396 number of cores you have. For example, a typical Core2Duo machine
401 If you get errors using the `-j' option, and `make' succeeds without
402 it, try lowering the `X' value.
404 Because multiple jobs run in parallel when `-j' is used, it can be
405 difficult to determine the source of an error when one occurs. In that
406 case, running `make' without the `-j' is advised.
408 Compiling for multiple platforms
409 --------------------------------
411 If you want to build multiple versions of LilyPond with different
412 configuration settings, you can use the `--enable-config=CONF' option
413 of `configure'. You should use `make conf=CONF' to generate the output
414 in `out-CONF'. For example, suppose you want to build with and without
415 profiling, then use the following for the normal build
417 ./configure --prefix=$HOME/usr/ --enable-checking
420 and for the profiling version, specify a different configuration
422 ./configure --prefix=$HOME/usr/ --enable-profiling \
423 --enable-config=prof --disable-checking
426 If you wish to install a copy of the build with profiling, don't
427 forget to use `conf=CONF' when issuing `make install':
429 make conf=prof install
437 *note Installing LilyPond from a local build::
439 Useful `make' variables
440 -----------------------
442 If a less verbose build output if desired, the variable `QUIET_BUILD'
443 may be set to `1' on `make' command line, or in `local.make' at top of
446 Post-compilation options
447 ========================
449 Installing LilyPond from a local build
450 --------------------------------------
452 If you configured `make' to install your local build in a directory
453 where you normally have write permission (such as your home directory),
454 and you have compiled LilyPond by running `make', you can install the
455 program in your target directory by running:
459 If instead, your installation directory is not one that you can
460 normally write to (such as the default `/usr/local/', which typically
461 is only writeable by the superuser), you will need to temporarily
462 become the superuser when running `make install':
470 If you don't have superuser privileges, then you need to configure
471 the installation directory to one that you can write to, and then
472 re-install. See *note Configuring target directories::.
474 Generating documentation
475 ------------------------
477 Documentation editor's edit/compile cycle
478 .........................................
480 * Initial documentation build:
483 make [-jX CPU_COUNT=X] doc _## can take an hour or more_
484 make [-jX CPU_COUNT=X] doc-stage-1 _## to build only PDF documentation_
486 * Edit/compile cycle:
488 _## edit source files, then..._
490 make [-jX] _## needed if editing outside_
491 _## Documentation/, but useful anyway_
492 _## for finding Texinfo errors._
493 make [-jX CPU_COUNT=X] doc _## usually faster than initial build._
497 It is generally possible to remove the compiled documentation from
498 your system with `make doc-clean', but this method is not 100%
499 guaranteed. Instead, if you want to be sure you have a clean
500 system, we recommend that you delete your `build/' directory, and
501 begin compiling from scratch. Since the documentation compile
502 takes much longer than the non-documentation compile, this does
503 not increase the overall time by a great deal.
506 Building documentation
507 ......................
509 After a successful compile (using `make'), the documentation can be
514 or, to build only the PDF documentation and not the HTML,
518 Note: The first time you run `make doc', the process can
519 easily take an hour or more with not much output on the
522 After this initial build, `make doc' only makes changes to the
523 documentation where needed, so it may only take a minute or two to test
524 changes if the documentation is already built.
526 If `make doc' succeeds, the HTML documentation tree is available in
527 `out-www/offline-root/', and can be browsed locally. Various portions
528 of the documentation can be found by looking in `out/' and `out-www'
529 subdirectories in other places in the source tree, but these are only
530 _portions_ of the docs. Please do not complain about anything which is
531 broken in those places; the only complete set of documentation is in
532 `out-www/offline-root/' from the top of the source tree.
534 `make doc' sends the output from most of the compilation to
535 logfiles. If the build fails for any reason, it should prompt you with
536 the name of a logfile which will provide information to help you work
537 out why the build failed. These logfiles are not deleted with
538 `make doc-clean'. To remove all the logfiles generated by the
539 compilation process, use:
543 `make doc' compiles the documents for all languages. To save some
544 compile time, the English language documents can be compiled on their
549 Similarly, it is possible to compile a subset of the translated
550 documentation by specifying their language codes on the command line.
551 For example, the French and German translations are compiled with:
553 make LANGS='de fr' doc
555 Note that this will also compile the English version.
557 Compilation of documentation in Info format with images can be done
558 separately by issuing:
562 An issue when switching branches between master and translation is the
563 appearance/disappearance of translated versions of some manuals. If
564 you see such a warning from make:
566 No rule to make target `X', needed by `Y'
568 Your best bet is to delete the file Y.dep and to try again.
570 Building a single document
571 ..........................
573 It's possible to build a single document. For example, to rebuild only
574 `contributor.pdf', do the following:
578 touch ../../Documentation/contributor.texi
579 make out=www out-www/contributor.pdf
581 If you are only working on a single document, test-building it in
582 this way can give substantial time savings - recreating
583 `contributor.pdf', for example, takes a matter of seconds.
585 Saving time with `CPU_COUNT'
586 ............................
588 The most time consuming task for building the documentation is running
589 LilyPond to build images of music, and there cannot be several
590 simultaneously running `lilypond-book' instances, so the `-j' `make'
591 option does not significantly speed up the build process. To help
592 speed it up, the makefile variable `CPU_COUNT' may be set in
593 `local.make' or on the command line to the number of `.ly' files that
594 LilyPond should process simultaneously, e.g. on a bi-processor or dual
597 make -j3 CPU_COUNT=3 doc
599 The recommended value of `CPU_COUNT' is one plus the number of cores or
600 processors, but it is advisable to set it to a smaller value unless
601 your system has enough RAM to run that many simultaneous LilyPond
602 instances. Also, values for the `-j' option that pose problems with
603 `make' are less likely to pose problems with `make doc' (this applies
604 to both `-j' and `CPU_COUNT'). For example, with a quad-core processor,
605 it is possible for `make -j5 CPU_COUNT=5 doc' to work consistently even
606 if `make -j5' rarely succeeds.
611 To build the documentation with interactive searching, use:
613 make doc AJAX_SEARCH=1
615 This requires PHP, and you must view the docs via a http connection
616 (you cannot view them on your local filesystem).
618 Note: Due to potential security or load issues, this option is
619 not enabled in the official documentation builds. Enable at
622 Installing documentation
623 ........................
625 The HTML, PDF and if available Info files can be installed into the
626 standard documentation path by issuing
630 This also installs Info documentation with images if the installation
631 prefix is properly set; otherwise, instructions to complete proper
632 installation of Info documentation are printed on standard output.
634 To install the Info documentation separately, run:
638 Note that to get the images in Info documentation, `install-doc' target
639 creates symbolic links to HTML and PDF installed documentation tree in
640 `PREFIX/share/info', in order to save disk space, whereas
641 `install-info' copies images in `PREFIX/share/info' subdirectories.
643 It is possible to build a documentation tree in
644 `out-www/online-root/', with special processing, so it can be used on a
645 website with content negotiation for automatic language selection; this
646 can be achieved by issuing
648 make WEB_TARGETS=online doc
650 and both `offline' and `online' targets can be generated by issuing
652 make WEB_TARGETS="offline online" doc
654 Several targets are available to clean the documentation build and
655 help with maintaining documentation; an overview of these targets is
660 from every directory in the build tree. Most targets for documentation
661 maintenance are available from `Documentation/'; for more information,
662 see *note Documentation work: (lilypond-contributor)Documentation work.
664 The makefile variable `QUIET_BUILD' may be set to `1' for a less
665 verbose build output, just like for building the programs.
667 Building documentation without compiling
668 ........................................
670 The documentation can be built locally without compiling LilyPond
671 binary, if LilyPond is already installed on your system.
673 From a fresh Git checkout, do
675 ./autogen.sh # ignore any warning messages
676 cp GNUmakefile.in GNUmakefile
677 make -C scripts && make -C python
678 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
680 Please note that this may break sometimes - for example, if a new
681 feature is added with a test file in input/regression, even the latest
682 development release of LilyPond will fail to build the docs.
684 You may build the manual without building all the `input/*' stuff
685 (i.e. mostly regression tests): change directory, for example to
686 `Documentation/', issue `make doc', which will build documentation in a
687 subdirectory `out-www' from the source files in current directory. In
688 this case, if you also want to browse the documentation in its
689 post-processed form, change back to top directory and issue
691 make out=www WWW-post
694 Known issues and warnings
695 .........................
697 You may also need to create a script for `pngtopnm' and `pnmtopng'. On
698 GNU/Linux, I use this:
700 export LD_LIBRARY_PATH=/usr/lib
701 exec /usr/bin/pngtopnm "$@"
703 On MacOS X with fink, I use this:
705 export DYLD_LIBRARY_PATH=/sw/lib
706 exec /sw/bin/pngtopnm "$@"
708 On MacOS X with macports, you should use this:
710 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
711 exec /opt/local/bin/pngtopnm "$@"
713 Testing LilyPond binary
714 -----------------------
716 LilyPond comes with an extensive suite that exercises the entire
717 program. This suite can be used to test that the binary has been built
720 The test suite can be executed with:
724 If the test suite completes successfully, the LilyPond binary has
727 More information on the regression test suite is found at *note
728 Regression tests: (lilypond-contributor)Regression tests.
733 For help and questions use <lilypond-user@gnu.org>. Send bug reports
734 to <bug-lilypond@gnu.org>.
736 Bugs that are not fault of LilyPond are documented here.
741 There is a bug in bison-1.875: compilation fails with "parse error
742 before `goto'" in line 4922 due to a bug in bison. To fix, please
743 recompile bison 1.875 with the following fix
745 $ cd lily; make out/parser.cc
746 $ vi +4919 out/parser.cc
747 # append a semicolon to the line containing "__attribute__ ((__unused__))
754 Here are special instructions for compiling under MacOS X. These
755 instructions assume that dependencies are installed using MacPorts.
756 (http://www.macports.org/) The instructions have been tested using OS X
759 First, install the relevant dependencies using MacPorts.
761 Next, add the following to your relevant shell initialization files.
762 This is `~/.profile' by default. You should create this file if it
765 export PATH=/opt/local/bin:/opt/local/sbin:$PATH
766 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
768 Now you must edit the generated `config.make' file. Change
770 FLEXLEXER_FILE = /usr/include/FlexLexer.h
774 FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
776 At this point, you should verify that you have the appropriate fonts
777 installed with your ghostscript installation. Check `ls
778 /opt/local/share/ghostscript/fonts' for: 'c0590*' files (.pfb, .pfb and
779 .afm). If you don't have them, run the following commands to grab them
780 from the ghostscript SVN server and install them in the appropriate
783 svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
784 sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
785 rm -rf urw-fonts-1.07pre44
787 Now run the `./configure' script. To avoid complications with
788 automatic font detection, add
790 --with-ncsb-dir=/opt/local/share/ghostscript/fonts
795 Solaris7, ./configure
797 `./configure' needs a POSIX compliant shell. On Solaris7, `/bin/sh'
798 is not yet POSIX compliant, but `/bin/ksh' or bash is. Run configure
801 CONFIG_SHELL=/bin/ksh ksh -c ./configure
805 CONFIG_SHELL=/bin/bash bash -c ./configure
810 To use system fonts, dejaview must be installed. With the default
811 port, the fonts are installed in `usr/X11R6/lib/X11/fonts/dejavu'.
813 Open the file `$LILYPONDBASE/usr/etc/fonts/local.conf' and add the
814 following line just after the `<fontconfig>' line. (Adjust as necessary
817 <dir>/usr/X11R6/lib/X11/fonts</dir>
822 On Mac OS X, all fonts are installed by default. However, finding all
823 system fonts requires a bit of configuration; see this post
824 (http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
825 on the `lilypond-user' mailing list.
827 On Linux, international fonts are installed by different means on
828 every distribution. We cannot list the exact commands or packages that
829 are necessary, as each distribution is different, and the exact package
830 names within each distribution changes. Here are some hints, though:
834 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
835 ttfonts-zh_CN fonts-ja fonts-hebrew
839 apt-get install emacs-intl-fonts xfonts-intl-.* \
840 ttf-kochi-gothic ttf-kochi-mincho \
841 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
843 Using lilypond python libraries
844 ...............................
846 If you want to use lilypond's python libraries (either running certain
847 build scripts manually, or using them in other programs), set
848 `PYTHONPATH' to `python/out' in your build directory, or
849 `.../usr/lib/lilypond/current/python' in the installation directory
852 Concurrent stable and development versions
853 ==========================================
855 It can be useful to have both the stable and the development versions
856 of Lilypond available at once. One way to do this on GNU/Linux is to
857 install the stable version using the precompiled binary, and run the
858 development version from the source tree. After running `make all'
859 from the top directory of the Lilypond source files, there will be a
860 binary called `lilypond' in the `out' directory:
862 <PATH TO>/lilypond/out/bin/lilypond
864 This binary can be run without actually doing the `make install'
865 command. The advantage to this is that you can have all of the latest
866 changes available after pulling from git and running `make all',
867 without having to uninstall the old version and reinstall the new.
869 So, to use the stable version, install it as usual and use the
874 To use the development version, create a link to the binary in the
875 source tree by saving the following line in a file somewhere in your
878 exec <PATH TO>/lilypond/out/bin/lilypond "$@"
880 Save it as `Lilypond' (with a capital L to distinguish it from the
881 stable `lilypond'), and make it executable:
885 Then you can invoke the development version this way:
891 - other compilation tricks for developers
896 We currently use make and stepmake, which is complicated and only used
897 by us. Hopefully this will change in the future.
899 Version-specific texinfo macros
900 ...............................
902 * made with `scripts/build/create-version-itexi.py' and
903 `scripts/build/create-weblinks-itexi.py'
905 * used extensively in the `WEBSITE_ONLY_BUILD' version of the
906 website (made with `website.make', used on lilypond.org)
908 * not (?) used in the main docs?
910 * the numbers in VERSION file: MINOR_VERSION should be 1 more than
911 the last release, VERSION_DEVEL should be the last *online*
912 release. Yes, VERSION_DEVEL is less than VERSION.