1 INSTALL - compiling and installing GNU LilyPond
2 ***********************************************
7 INSTALL - compiling and installing GNU LilyPond
11 Downloading source code
15 Requirements for building documentation
18 Compiling for multiple platforms
19 Compiling outside the source tree
20 Useful `make' variables
21 Building documentation
22 Commands for building documentation
23 Building documentation without compiling LilyPond
32 There are two sets of releases for LilyPond: stable releases, and
33 unstable development releases. Stable versions have an even-numbered
34 `minor' version number (i.e. 2.8, 2.10, 2.12, etc). Development
35 versions have an odd-numbered `minor' version number (i.e. 2.7, 2.9,
38 Building LilyPond is a very involved process, so we *highly*
39 recommend using the precompiled binaries.
47 Check out `http://lilypond.org/web/install/' for up to date information
48 on binary packages for your platform. If your operating system is not
49 covered on that general page, please see the complete list at
50 `http://download.linuxaudio.org/lilypond/binaries/'
52 We currently create binaries for
54 darwin-ppc - MacOS X powerpc
55 darwin-x86 - MacOS X intel
56 freebsd-64 - FreeBSD 6.x, x86_64
57 freebsd-x86 - FreeBSD 4.x, x86
58 linux-64 - Any GNU/Linux distribution, x86_64
59 linux-ppc - Any GNU/Linux distribution, powerpc
60 linux-x86 - Any GNU/Linux distribution, x86
64 Known issues and warnings
65 .........................
67 If you have MacOS 10.3 or 10.4 and you would like to use Python scripts
68 such as `convert-ly' and `lilypond-book', see *note Setup for MacOS X:
69 (lilypond-program)Setup for MacOS X.
74 Downloading source code
75 -----------------------
79 * tarballs from `http://lilypond.org/download/' by HTTP.
81 * tarballs from `http://download.linuxaudio.org/lilypond/' by HTTP.
83 * GIT from git.sv.gnu.org
84 (http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary)
86 git clone git://git.sv.gnu.org/lilypond.git
88 The repository does not contain generated files. To create
92 For information on packaging, see `http://lilypond.org/devel'.
100 In addition to the packages needed for running LilyPond (see below), you
101 need the following extra packages for building.
103 When installing a binary package FOO, you may need to install the
104 FOO-devel, libFOO-dev or FOO-dev package too.
106 * FontForge (http://fontforge.sf.net/) 20060125 or newer.
108 * MetaFont (http://metafont.tutorial.free.fr/) (mf-nowin, mf, mfw or
109 mfont binaries) and MetaPost
110 (http://cm.bell-labs.com/who/hobby/MetaPost.html) (mpost binary),
111 usually packaged with a LaTeX distribution like tetex or texlive.
113 * t1utils (http://www.lcdf.org/~eddietwo/type/#t1utils) (version
114 1.33 or newer recommended).
116 * New Century Schoolbook fonts, as PFB files. These are shipped with
117 X11 and Ghostscript, and are named `c059033l.pfb' `c059036l.pfb',
118 `c059013l.pfb' and `c059016l.pfb'.
120 * GUILE (http://www.gnu.org/software/guile/guile.html) (version
121 1.8.2 or newer). If you are installing binary packages, you may
122 need to install guile-devel or guile-dev or libguile-dev too.
124 * Texinfo (ftp://ftp.gnu.org/gnu/texinfo/) (version 4.11 or newer).
126 * The GNU c++ compiler (http://gcc.gnu.org/) (version 3.4 or newer.
127 4.x is strongly recommended).
129 * Python (http://www.python.org) (version 2.4 or newer)
131 * GNU Make (ftp://ftp.gnu.org/gnu/make/) (version 3.78 or newer).
133 * gettext (http://www.gnu.org/software/gettext/gettext.html)
134 (version 0.17 or newer).
136 * Flex (http://www.gnu.org/software/flex/).
138 * Perl (http://www.perl.org/).
140 * GNU Bison (http://www.gnu.org/software/bison/).
142 * All packages required for running, including development packages
143 with header files and libraries.
149 Running LilyPond requires proper installation of the following software
151 * Freetype (http://www.freetype.org/) (version 2.1.10 or newer).
153 * FontConfig (http://fontconfig.org/) (version 2.2 or newer).
155 * Pango (http://www.pango.org/) (version 1.12 or newer).
157 * GUILE (http://www.gnu.org/software/guile/guile.html) (version
158 1.8.2 or newer), or patch 1.8.1 with
159 `http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch'.
161 * Python (http://www.python.org) (version 2.4 or newer).
163 * Ghostscript (http://www.ghostscript.com) (version 8.15 or newer.
166 * Dejaview. (This is normally installed by default)
168 International fonts are required to create music with international
171 Requirements for building documentation
172 .......................................
174 You can view the documentation online at `http://lilypond.org/doc/',
175 but you can also build it locally. This process requires a successful
176 compile of LilyPond, and some additional tools and packages:
178 * The netpbm utilities (http://netpbm.sourceforge.net/)
182 * International fonts (see input/regression/utf-8.ly for hints about
183 which font packages are necessary for your platform)
185 * Ghostscript 8.60 or newer, or 8.50 with the patch from
186 `http://bugs.ghostscript.com/show_bug.cgi?id=688154' and the patch
187 from `http://bugs.ghostscript.com/show_bug.cgi?id=688017'.
189 * Texi2HTML (http://www.nongnu.org/texi2html/) 1.80 or newer
199 To install GNU LilyPond, type
201 gunzip -c lilypond-x.y.z | tar xf -
203 ./configure # run with --help for applicable options
207 If you are not root, you should choose a `--prefix' argument that
208 points into your home directory, e.g.
210 ./configure --prefix=$HOME/usr
212 Compiling for multiple platforms
213 ................................
215 If you want to build multiple versions of LilyPond with different
216 configuration settings, you can use the `--enable-config=CONF' option
217 of `configure'. You should use `make conf=CONF' to generate the output
218 in `out-CONF'. For example, suppose you want to build with and without
219 profiling, then use the following for the normal build
221 ./configure --prefix=$HOME/usr/ --enable-checking
225 and for the profiling version, specify a different configuration
227 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
229 make conf=prof install
231 Compiling outside the source tree
232 .................................
234 It is possible to compile LilyPond in a build tree different from the
235 source tree, with `--srcdir' option of `configure':
237 mkdir lily-build && cd lily-build
238 SOURCEDIR/configure --srcdir=SOURCEDIR
240 Useful `make' variables
241 .......................
243 If a less verbose build output if desired, the variable `QUIET_BUILD'
244 may be set to `1' on `make' command line, or in `local.make' at top of
247 Building documentation
248 ----------------------
250 This requires a successful compile of LilyPond, or using an external
253 Commands for building documentation
254 ...................................
256 The documentation is built by issuing
260 After compilation, the HTML documentation tree is available in
261 `out-www/offline-root/', and can be browsed locally.
263 The HTML, PDF and if available Info files can be installed into the
264 standard documentation path by issuing
268 This also installs Info documentation with images if the installation
269 prefix is properly set; otherwise, instructions to complete proper
270 installation of Info documentation are printed on standard output.
272 Compilation of documentation in Info format with images can be done
273 separately by issuing
277 Separate installation of this documentation is done by issuing
281 Note that to get the images in Info documentation, `install-doc' target
282 creates symbolic links to HTML and PDF installed documentation tree in
283 `PREFIX/share/info', in order to save disk space, whereas
284 `install-info' copies images in `PREFIX/share/info' subdirectories.
286 It is possible to build a documentation tree in
287 `out-www/online-root/', with special processing, so it can be used on a
288 website with content negotiation for automatic language selection; this
289 can be achieved by issuing
291 make WEB_TARGETS=online doc
293 and both `offline' and `online' targets can be generated by issuing
295 make WEB_TARGETS="offline online" doc
297 Several targets are available to clean the documentation build and
298 help with maintaining documentation; an overview of these targets is
303 from every directory in the build tree. Most targets for documentation
304 maintenance are available from `Documentation/'; for more information,
305 see the Contributors' Guide, section _Documentation work_.
307 The makefile variable `QUIET_BUILD' may be set to `1' for a less
308 verbose build output, just like for building the programs.
312 Known issues and warnings
313 .........................
315 The most time consuming task for building the documentation is running
316 LilyPond to build images of music, and there cannot be several
317 simultaneously running `lilypond-book' instances, so `-j' `make' option
318 does not significantly speed up the build process. To help speed it
319 up, the makefile variable CPU_COUNT may be set in `local.make' or on
320 the command line to the number of `.ly' files that LilyPond should
321 process simultaneously, e.g. on a bi-processor or dual core machine
323 make -j3 CPU_COUNT=3 doc
325 The recommended value of CPU_COUNT is one plus the number of cores or
326 processors, but it is advisable to set it to a smaller value if your
327 system has not enough RAM to run that many simultaneous LilyPond
330 If source files have changed since last documentation build, output
331 files that need to be rebuilt are normally rebuilt, even if you do not
332 run `make doc-clean' first. However, building dependencies in the
333 documentation are so complex that rebuilding of some targets may not be
334 triggered as they should be; a workaround is to force rebuilding by
335 touching appropriate files, e.g.
337 touch Documentation/user/*.itely
340 Building documentation without compiling LilyPond
341 .................................................
343 The documentation can be built locally without compiling LilyPond
344 binary, if LilyPond is already installed on your system.
346 From a fresh Git checkout, do
348 ./autogen.sh # ignore any warning messages
349 cp GNUmakefile.in GNUmakefile
351 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
353 Please note that this may break sometimes - for example, if a new
354 feature is added with a test file in input/regression, even the latest
355 development release of LilyPond will fail to build the docs.
357 You may build the manual without building all the `input/*' stuff:
358 change directory, for example to `Documentation/user', issue `make
359 doc', which will build documentation in a subdirectory `out-www' from
360 the source files in current directory. In this case, if you also want
361 to browse the documentation in its post-processed form, change back to
362 top directory and issue
364 make out=www WWW-post
367 Known issues and warnings
368 .........................
370 You may also need to create a script for `pngtopnm' and `pnmtopng'. On
371 GNU/Linux, I use this:
373 export LD_LIBRARY_PATH=/usr/lib
374 exec /usr/bin/pngtopnm "$@"
376 On MacOS X, I use this:
378 export DYLD_LIBRARY_PATH=/sw/lib
379 exec /sw/bin/pngtopnm "$@"
384 LilyPond comes with an extensive suite that exercises the entire
385 program. This suite can be used to automatically check the impact of a
386 change. This is done as follows
389 _## apply your changes, compile_
392 This will leave an HTML page `out/test-results/index.html'. This
393 page shows all the important differences that your change introduced,
394 whether in the layout, MIDI, performance or error reporting.
398 make test-redo _## redo files differing from baseline_
399 make test-clean _## remove all test results_
401 and then run `make check' again.
403 For tracking memory usage as part of this test, you will need GUILE
404 CVS; especially the following patch:
405 `http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch'.
407 For checking the coverage of the test suite, do the following
409 ./scripts/auxiliar/build-coverage.sh
410 _# uncovered files, least covered first_
411 ./scripts/auxiliar/coverage.py --summary out-cov/*.cc
412 _# consecutive uncovered lines, longest first_
413 ./scripts/auxiliar/coverage.py --uncovered out-cov/*.cc
418 For help and questions use <lilypond-user@gnu.org>. Send bug reports
419 to <bug-lilypond@gnu.org>.
421 Bugs that are not fault of LilyPond are documented here.
426 There is a bug in bison-1.875: compilation fails with "parse error
427 before `goto'" in line 4922 due to a bug in bison. To fix, please
428 recompile bison 1.875 with the following fix
430 $ cd lily; make out/parser.cc
431 $ vi +4919 out/parser.cc
432 # append a semicolon to the line containing "__attribute__ ((__unused__))
439 Solaris7, ./configure
441 `./configure' needs a POSIX compliant shell. On Solaris7, `/bin/sh'
442 is not yet POSIX compliant, but `/bin/ksh' or bash is. Run configure
445 CONFIG_SHELL=/bin/ksh ksh -c ./configure
449 CONFIG_SHELL=/bin/bash bash -c ./configure
454 To use system fonts, dejaview must be installed. With the default
455 port, the fonts are installed in `usr/X11R6/lib/X11/fonts/dejavu'.
457 Open the file `$LILYPONDBASE/usr/etc/fonts/local.conf' and add the
458 following line just after the `<fontconfig>' line. (Adjust as necessary
461 <dir>/usr/X11R6/lib/X11/fonts</dir>
466 On MacOS X, all fonts are installed by default. However, finding all
467 system fonts requires a bit of configuration; see this post
468 (http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
469 on the `lilypond-user' mailing list.
471 On Linux, international fonts are installed by different means on
472 every distribution. We cannot list the exact commands or packages that
473 are necessary, as each distribution is different, and the exact package
474 names within each distribution changes. Here are some hints, though:
478 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
479 ttfonts-zh_CN fonts-ja fonts-hebrew
483 apt-get install emacs-intl-fonts xfonts-intl-.* \
484 ttf-kochi-gothic ttf-kochi-mincho \
485 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi