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 Saving time with `CPU_COUNT'
32 Installing documentation
33 Building documentation without compiling
34 Testing LilyPond binary
41 Using lilypond python libraries
42 Concurrent stable and development versions
49 Compiling LilyPond from source is an involved process, and is only
50 recommended for developers and packagers. Typical program users are
51 instead encouraged to obtain the program from a package manager (on
52 Unix) or by downloading a precompiled binary configured for a specific
53 operating system. Pre-compiled binaries are available on the *note
54 Download: (lilypond-web)Download. page.
56 Compiling LilyPond from source is necessary if you want to build,
57 install, or test your own version of the program.
59 A successful compile can also be used to generate and install the
60 documentation, incorporating any changes you may have made. However, a
61 successful compile is not a requirement for generating the
62 documentation. The documentation can be built using a Git repository
63 in conjunction with a locally installed copy of the program. For more
64 information, see *note Building documentation without compiling::.
66 Attempts to compile LilyPond natively on Windows have been
67 unsuccessful, though a workaround is available (see *note Lilydev:
68 (lilypond-contributor)Lilydev.).
73 Requirements for running LilyPond
74 ---------------------------------
76 Running LilyPond requires proper installation of the following software:
78 * DejaVu fonts (http://www.dejavu-fonts.org/) (normally installed by
81 * FontConfig (http://www.fontconfig.org/) (2.4.0 or newer)
83 * Freetype (http://www.freetype.org/) (2.1.10 or newer)
85 * Ghostscript (http://www.ghostscript.com) (8.60 or newer)
87 * Guile (http://www.gnu.org/software/guile/guile.html) (1.8.2 or
90 * Pango (http://www.pango.org/) (1.12 or newer)
92 * Python (http://www.python.org) (2.4 or newer)
94 International fonts are required to create music with international
97 Requirements for compiling LilyPond
98 -----------------------------------
100 Below is a full list of packages needed to build LilyPond. However,
101 for most common distributions there is an easy way of installing most
102 all build dependencies in one go:
105 --------------------------------------------------------------------------
106 Debian, Ubuntu `sudo apt-get build-dep lilypond'
107 Fedora, RHEL `sudo yum-builddep lilypond'
108 openSUSE, SLED `sudo zypper --build-deps-only
109 source-install lilypond'
111 * Everything listed in *note Requirements for running LilyPond::
113 * Development packages for the above items (which should include
114 header files and libraries).
119 fontconfig-devel-VERSION
120 freetype-devel-VERSION
132 * Flex (http://flex.sourceforge.net/)
134 * FontForge (http://fontforge.sf.net/) (20060125 or newer; 20100501
135 or newer is recommended; must be compiled with `--enable-double'.
136 Failure to do so can lead to poor intersection calculations and
137 poorly-rendered glyphs.)
139 * GNU Bison (http://www.gnu.org/software/bison/)
141 * GNU Compiler Collection (http://gcc.gnu.org/) (3.4 or newer, 4.X
144 * GNU gettext (http://www.gnu.org/software/gettext/gettext.html)
147 * GNU Make (http://www.gnu.org/software/make/) (3.78 or newer)
149 * MetaFont (http://metafont.tutorial.free.fr/) (mf-nowin, mf, mfw or
150 mfont binaries), usually packaged with TeX
151 (http://www.latex-project.org/ftp.html).
153 * MetaPost (http://cm.bell-labs.com/who/hobby/MetaPost.html) (mpost
154 binary), usually packaged with TeX
155 (http://www.latex-project.org/ftp.html).
157 * Perl (http://www.perl.org/)
159 * Texinfo (http://www.gnu.org/software/texinfo/) (4.11 or newer)
161 * Type 1 utilities (http://www.lcdf.org/~eddietwo/type/#t1utils)
162 (1.33 or newer recommended)
164 Requirements for building documentation
165 ---------------------------------------
167 You can view the documentation online at
168 `http://www.lilypond.org/doc/', but you can also build it locally.
169 This process requires some additional tools and packages:
171 * Everything listed in *note Requirements for compiling LilyPond::
173 * ImageMagick (http://www.imagemagick.org/)
175 * Netpbm (http://netpbm.sourceforge.net/)
177 * gzip (http://gzip.org/)
179 * rsync (http://rsync.samba.org/)
181 * Texi2HTML (http://www.nongnu.org/texi2html/) (1.82)
183 * International fonts
205 Getting the source code
206 =======================
208 Downloading the Git repository
209 ------------------------------
211 In general, developers compile LilyPond from within a local Git
212 repository. Setting up a local Git repository is explained in *note
213 Starting with Git: (lilypond-contributor)Starting with Git.
215 Downloading a source tarball
216 ----------------------------
218 Packagers are encouraged to use source tarballs for compiling.
220 The tarball for the latest stable release is available on the *note
221 Source: (lilypond-web)Source. page.
223 The latest source code snapshot
224 (http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot) is also
225 available as a tarball from the GNU Savannah Git server.
227 All tagged releases (including legacy stable versions and the most
228 recent development release) are available here:
230 `http://download.linuxaudio.org/lilypond/source/'
232 Download the tarball to your `~/src/' directory, or some other
235 Note: Be careful where you unpack the tarball! Any
236 subdirectories of the current folder named `lilypond/' or
237 `lilypond-X.Y.Z/' (where X.Y.Z is the release number) will be
238 overwritten if there is a name clash with the tarball.
240 Unpack the tarball with this command:
242 tar -xzf lilypond-X.Y.Z.tar.gz
244 This creates a subdirectory within the current directory called
245 `lilypond-X.Y.Z/'. Once unpacked, the source files occupy about 40 MB
248 Windows users wanting to look at the source code may have to
249 download and install the free-software 7zip archiver
250 (http://www.7-zip.org) to extract the tarball.
255 Running `./autogen.sh'
256 ----------------------
258 After you unpack the tarball (or download the Git repository), the
259 contents of your top source directory should be similar to the current
260 source tree listed at
261 `http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree'.
263 Next, you need to create the generated files; enter the following
264 command from your top source directory:
266 ./autogen.sh --noconfigure
268 This will generate a number of files and directories to aid
269 configuration, such as `configure', `README.txt', etc.
271 Next, create the build directory with:
276 We heavily recommend building lilypond inside a separate directory
279 Running `../configure'
280 ----------------------
282 Configuration options
283 .....................
285 Note: make sure that you are in the `build/' subdirectory of
288 The `../configure' command (generated by `./autogen.sh') provides many
289 options for configuring `make'. To see them all, run:
293 Checking build dependencies
294 ...........................
296 Note: make sure that you are in the `build/' subdirectory of
299 When `../configure' is run without any arguments, it will check to make
300 sure your system has everything required for compilation:
304 If any build dependency is missing, `../configure' will return with:
306 ERROR: Please install required programs: FOO
308 The following message is issued if you are missing programs that are
309 only needed for building the documentation:
311 WARNING: Please consider installing optional programs: BAR
313 If you intend to build the documentation locally, you will need to
314 install or update these programs accordingly.
316 Note: `../configure' may fail to issue warnings for certain
317 documentation build requirements that are not met. If you
318 experience problems when building the documentation, you may
319 need to do a manual check of *note Requirements for building
322 Configuring target directories
323 ..............................
325 Note: make sure that you are in the `build/' subdirectory of
328 If you intend to use your local build to install a local copy of the
329 program, you will probably want to configure the installation
330 directory. Here are the relevant lines taken from the output of
331 `../configure --help':
333 By default, ``make install'' will install all the files in
334 `/usr/local/bin', `/usr/local/lib' etc. You can specify an
335 installation prefix other than `/usr/local' using ``--prefix'',
336 for instance ``--prefix=$HOME''.
338 A typical installation prefix is `$HOME/usr':
340 ../configure --prefix=$HOME/usr
342 Note that if you plan to install a local build on a system where you
343 do not have root privileges, you will need to do something like this
344 anyway--`make install' will only succeed if the installation prefix
345 points to a directory where you have write permission (such as your
346 home directory). The installation directory will be automatically
347 created if necessary.
349 The location of the `lilypond' command installed by this process
350 will be `PREFIX/bin/lilypond'; you may want to add `PREFIX/bin/' to
351 your `$PATH' if it is not already included.
353 It is also possible to specify separate installation directories for
354 different types of program files. See the full output of
355 `../configure --help' for more information.
357 If you encounter any problems, please see *note Problems::.
365 Note: make sure that you are in the `build/' subdirectory of
368 LilyPond is compiled with the `make' command. Assuming `make' is
369 configured properly, you can simply run:
373 `make' is short for `make all'. To view a list of `make' targets,
378 TODO: Describe what `make' actually does.
380 Saving time with the `-j' option
381 --------------------------------
383 If your system has multiple CPUs, you can speed up compilation by
384 adding `-jX' to the `make' command, where `X' is one more than the
385 number of cores you have. For example, a typical Core2Duo machine
390 If you get errors using the `-j' option, and `make' succeeds without
391 it, try lowering the `X' value.
393 Because multiple jobs run in parallel when `-j' is used, it can be
394 difficult to determine the source of an error when one occurs. In that
395 case, running `make' without the `-j' is advised.
397 Compiling for multiple platforms
398 --------------------------------
400 If you want to build multiple versions of LilyPond with different
401 configuration settings, you can use the `--enable-config=CONF' option
402 of `configure'. You should use `make conf=CONF' to generate the output
403 in `out-CONF'. For example, suppose you want to build with and without
404 profiling, then use the following for the normal build
406 ./configure --prefix=$HOME/usr/ --enable-checking
409 and for the profiling version, specify a different configuration
411 ./configure --prefix=$HOME/usr/ --enable-profiling \
412 --enable-config=prof --disable-checking
415 If you wish to install a copy of the build with profiling, don't
416 forget to use `conf=CONF' when issuing `make install':
418 make conf=prof install
426 *note Installing LilyPond from a local build::
428 Useful `make' variables
429 -----------------------
431 If a less verbose build output if desired, the variable `QUIET_BUILD'
432 may be set to `1' on `make' command line, or in `local.make' at top of
435 Post-compilation options
436 ========================
438 Installing LilyPond from a local build
439 --------------------------------------
441 If you configured `make' to install your local build in a directory
442 where you normally have write permission (such as your home directory),
443 and you have compiled LilyPond by running `make', you can install the
444 program in your target directory by running:
448 If instead, your installation directory is not one that you can
449 normally write to (such as the default `/usr/local/', which typically
450 is only writeable by the superuser), you will need to temporarily
451 become the superuser when running `make install':
459 If you don't have superuser privileges, then you need to configure
460 the installation directory to one that you can write to, and then
461 re-install. See *note Configuring target directories::.
463 Generating documentation
464 ------------------------
466 Documentation editor's edit/compile cycle
467 .........................................
469 * Initial documentation build:
472 make [-jX CPU_COUNT=X] doc _## can take an hour or more_
474 * Edit/compile cycle:
476 _## edit source files, then..._
478 make [-jX] _## needed if editing outside_
479 _## Documentation/, but useful anyway_
480 _## for finding Texinfo errors._
481 touch Documentation/*te?? _## bug workaround_
482 make [-jX CPU_COUNT=X] doc _## usually faster than initial build._
486 In some cases, it is possible to clean the compiled documentation
487 with `make doc-clean', but this method is not guaranteed to fix
488 everything. Instead, we recommend that you delete your `build/'
489 directory, and begin compiling from scratch. Since the
490 documentation compile takes much longer than the non-documentation
491 compile, this does not increase the overall time by a great deal.
494 Building documentation
495 ......................
497 After a successful compile (using `make'), the documentation can be
502 The first time you run `make doc', the process can easily take an
503 hour or more. After that, `make doc' only makes changes to the
504 pre-built documentation where needed, so it may only take a minute or
505 two to test changes if the documentation is already built.
507 If `make doc' succeeds, the HTML documentation tree is available in
508 `out-www/offline-root/', and can be browsed locally. Various portions
509 of the documentation can be found by looking in `out/' and `out-www'
510 subdirectories in other places in the source tree, but these are only
511 _portions_ of the docs. Please do not complain about anything which is
512 broken in those places; the only complete set of documentation is in
513 `out-www/offline-root/' from the top of the source tree.
515 Compilation of documentation in Info format with images can be done
516 separately by issuing:
521 Known issues and warnings
522 .........................
524 If source files have changed since the last documentation build, output
525 files that need to be rebuilt are normally rebuilt, even if you do not
526 run `make doc-clean' first. However, build dependencies in the
527 documentation are so complex that some newly-edited files may not be
528 rebuilt as they should be; a workaround is to `touch' the top source
529 file for any manual you've edited. For example, if you make changes to
530 a file in `notation/', do:
532 touch Documentation/notation.tely
534 The top sources possibly affected by this are:
536 Documentation/extend.texi
537 Documentation/changes.tely
538 Documentation/contributor.texi
539 Documentation/essay.tely
540 Documentation/extending.tely
541 Documentation/learning.tely
542 Documentation/notation.tely
543 Documentation/snippets.tely
544 Documentation/usage.tely
545 Documentation/web.texi
547 You can `touch' all of them at once with:
549 touch Documentation/*te??
551 However, this will rebuild all of the manuals indiscriminately--it is
552 more efficient to `touch' only the affected files.
554 Saving time with `CPU_COUNT'
555 ............................
557 The most time consuming task for building the documentation is running
558 LilyPond to build images of music, and there cannot be several
559 simultaneously running `lilypond-book' instances, so the `-j' `make'
560 option does not significantly speed up the build process. To help
561 speed it up, the makefile variable `CPU_COUNT' may be set in
562 `local.make' or on the command line to the number of `.ly' files that
563 LilyPond should process simultaneously, e.g. on a bi-processor or dual
566 make -j3 CPU_COUNT=3 doc
568 The recommended value of `CPU_COUNT' is one plus the number of cores or
569 processors, but it is advisable to set it to a smaller value unless
570 your system has enough RAM to run that many simultaneous LilyPond
571 instances. Also, values for the `-j' option that pose problems with
572 `make' are less likely to pose problems with `make doc' (this applies
573 to both `-j' and `CPU_COUNT'). For example, with a quad-core processor,
574 it is possible for `make -j5 CPU_COUNT=5 doc' to work consistently even
575 if `make -j5' rarely succeeds.
580 To build the documentation with interactive searching, use:
582 make doc AJAX_SEARCH=1
584 This requires PHP, and you must view the docs via a http connection
585 (you cannot view them on your local filesystem).
587 Note: Due to potential security or load issues, this option is
588 not enabled in the official documentation builds. Enable at
591 Installing documentation
592 ........................
594 The HTML, PDF and if available Info files can be installed into the
595 standard documentation path by issuing
599 This also installs Info documentation with images if the installation
600 prefix is properly set; otherwise, instructions to complete proper
601 installation of Info documentation are printed on standard output.
603 To install the Info documentation separately, run:
607 Note that to get the images in Info documentation, `install-doc' target
608 creates symbolic links to HTML and PDF installed documentation tree in
609 `PREFIX/share/info', in order to save disk space, whereas
610 `install-info' copies images in `PREFIX/share/info' subdirectories.
612 It is possible to build a documentation tree in
613 `out-www/online-root/', with special processing, so it can be used on a
614 website with content negotiation for automatic language selection; this
615 can be achieved by issuing
617 make WEB_TARGETS=online doc
619 and both `offline' and `online' targets can be generated by issuing
621 make WEB_TARGETS="offline online" doc
623 Several targets are available to clean the documentation build and
624 help with maintaining documentation; an overview of these targets is
629 from every directory in the build tree. Most targets for documentation
630 maintenance are available from `Documentation/'; for more information,
631 see *note Documentation work: (lilypond-contributor)Documentation work.
633 The makefile variable `QUIET_BUILD' may be set to `1' for a less
634 verbose build output, just like for building the programs.
636 Building documentation without compiling
637 ........................................
639 The documentation can be built locally without compiling LilyPond
640 binary, if LilyPond is already installed on your system.
642 From a fresh Git checkout, do
644 ./autogen.sh # ignore any warning messages
645 cp GNUmakefile.in GNUmakefile
646 make -C scripts && make -C python
647 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
649 Please note that this may break sometimes - for example, if a new
650 feature is added with a test file in input/regression, even the latest
651 development release of LilyPond will fail to build the docs.
653 You may build the manual without building all the `input/*' stuff
654 (i.e. mostly regression tests): change directory, for example to
655 `Documentation/', issue `make doc', which will build documentation in a
656 subdirectory `out-www' from the source files in current directory. In
657 this case, if you also want to browse the documentation in its
658 post-processed form, change back to top directory and issue
660 make out=www WWW-post
663 Known issues and warnings
664 .........................
666 You may also need to create a script for `pngtopnm' and `pnmtopng'. On
667 GNU/Linux, I use this:
669 export LD_LIBRARY_PATH=/usr/lib
670 exec /usr/bin/pngtopnm "$@"
672 On MacOS X with fink, I use this:
674 export DYLD_LIBRARY_PATH=/sw/lib
675 exec /sw/bin/pngtopnm "$@"
677 On MacOS X with macports, you should use this:
679 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
680 exec /opt/local/bin/pngtopnm "$@"
682 Testing LilyPond binary
683 -----------------------
685 LilyPond comes with an extensive suite that exercises the entire
686 program. This suite can be used to test that the binary has been built
689 The test suite can be executed with:
693 If the test suite completes successfully, the LilyPond binary has
696 More information on the regression test suite is found at *note
697 Regression tests: (lilypond-contributor)Regression tests.
702 For help and questions use <lilypond-user@gnu.org>. Send bug reports
703 to <bug-lilypond@gnu.org>.
705 Bugs that are not fault of LilyPond are documented here.
710 There is a bug in bison-1.875: compilation fails with "parse error
711 before `goto'" in line 4922 due to a bug in bison. To fix, please
712 recompile bison 1.875 with the following fix
714 $ cd lily; make out/parser.cc
715 $ vi +4919 out/parser.cc
716 # append a semicolon to the line containing "__attribute__ ((__unused__))
723 Here are special instructions for compiling under MacOS X. These
724 instructions assume that dependencies are installed using MacPorts.
725 (http://www.macports.org/) The instructions have been tested using OS X
728 First, install the relevant dependencies using MacPorts.
730 Next, add the following to your relevant shell initialization files.
731 This is `~/.profile' by default. You should create this file if it
734 export PATH=/opt/local/bin:/opt/local/sbin:$PATH
735 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
737 Now you must edit the generated `config.make' file. Change
739 FLEXLEXER_FILE = /usr/include/FlexLexer.h
743 FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
745 At this point, you should verify that you have the appropriate fonts
746 installed with your ghostscript installation. Check `ls
747 /opt/local/share/ghostscript/fonts' for: 'c0590*' files (.pfb, .pfb and
748 .afm). If you don't have them, run the following commands to grab them
749 from the ghostscript SVN server and install them in the appropriate
752 svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
753 sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
754 rm -rf urw-fonts-1.07pre44
756 Now run the `./configure' script. To avoid complications with
757 automatic font detection, add
759 --with-ncsb-dir=/opt/local/share/ghostscript/fonts
764 Solaris7, ./configure
766 `./configure' needs a POSIX compliant shell. On Solaris7, `/bin/sh'
767 is not yet POSIX compliant, but `/bin/ksh' or bash is. Run configure
770 CONFIG_SHELL=/bin/ksh ksh -c ./configure
774 CONFIG_SHELL=/bin/bash bash -c ./configure
779 To use system fonts, dejaview must be installed. With the default
780 port, the fonts are installed in `usr/X11R6/lib/X11/fonts/dejavu'.
782 Open the file `$LILYPONDBASE/usr/etc/fonts/local.conf' and add the
783 following line just after the `<fontconfig>' line. (Adjust as necessary
786 <dir>/usr/X11R6/lib/X11/fonts</dir>
791 On Mac OS X, all fonts are installed by default. However, finding all
792 system fonts requires a bit of configuration; see this post
793 (http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
794 on the `lilypond-user' mailing list.
796 On Linux, international fonts are installed by different means on
797 every distribution. We cannot list the exact commands or packages that
798 are necessary, as each distribution is different, and the exact package
799 names within each distribution changes. Here are some hints, though:
803 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
804 ttfonts-zh_CN fonts-ja fonts-hebrew
808 apt-get install emacs-intl-fonts xfonts-intl-.* \
809 ttf-kochi-gothic ttf-kochi-mincho \
810 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
812 Using lilypond python libraries
813 ...............................
815 If you want to use lilypond's python libraries (either running certain
816 build scripts manually, or using them in other programs), set
817 `PYTHONPATH' to `python/out' in your build directory, or
818 `.../usr/lib/lilypond/current/python' in the installation directory
821 Concurrent stable and development versions
822 ==========================================
824 It can be useful to have both the stable and the development versions
825 of Lilypond available at once. One way to do this on GNU/Linux is to
826 install the stable version using the precompiled binary, and run the
827 development version from the source tree. After running `make all'
828 from the top directory of the Lilypond source files, there will be a
829 binary called `lilypond' in the `out' directory:
831 <PATH TO>/lilypond/out/bin/lilypond
833 This binary can be run without actually doing the `make install'
834 command. The advantage to this is that you can have all of the latest
835 changes available after pulling from git and running `make all',
836 without having to uninstall the old version and reinstall the new.
838 So, to use the stable version, install it as usual and use the
843 To use the development version, create a link to the binary in the
844 source tree by saving the following line in a file somewhere in your
847 exec <PATH TO>/lilypond/out/bin/lilypond "$@"
849 Save it as `Lilypond' (with a capital L to distinguish it from the
850 stable `lilypond'), and make it executable:
854 Then you can invoke the development version this way:
860 - other compilation tricks for developers
865 We currently use make and stepmake, which is complicated and only used
866 by us. Hopefully this will change in the future.
868 Version-specific texinfo macros
869 ...............................
871 * made with `scripts/build/create-version-itexi.py' and
872 `scripts/build/create-weblinks-itexi.py'
874 * used extensively in the `WEBSITE_ONLY_BUILD' version of the
875 website (made with `website.make', used on lilypond.org)
877 * not (?) used in the main docs?
879 * the numbers in VERSION file: MINOR_VERSION should be 1 more than
880 the last release, VERSION_DEVEL should be the last *online*
881 release. Yes, VERSION_DEVEL is less than VERSION.