9 INSTALL - compiling and installing GNU LilyPond
19 Configuring for multiple platforms
21 Compiling for distributions
29 FLex-2.5.4a and gcc-3.0
31 Linux-2.4.0, Guile-1.4 -with-threads
37 INSTALL - compiling and installing GNU LilyPond
38 ***********************************************
40 This document describes how to build LilyPond on Unix platforms. It
41 is also known to run and compile on Windows NT/95/98 as well. More
42 information on this topic can be found at the LilyPond on Windows page
43 (http://www.lilypond.org/gnu-windows/).
48 Even numbered versions are `stable'. The webpages for the stable
49 version (1.2) reside on the GNU servers
50 (http://www.gnu.org/software/lilypond). Big enhancements go into the
51 latest odd numbered version (1.3), whose webpages are on the lilypond
52 site (http://www.lilypond.org/).
57 If you want to compile LilyPond from source, download here:
58 * Download development releases from
59 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/' by FTP and
60 `http://ftp.cs.uu.nl/pub/GNU/LilyPond/', by HTTP.
62 * `ftp://sca.uwaterloo.ca/pub/' by FTP (Canadian mirror)
64 * at `lilypond.org' `ftp://ftp.lilypond.org/pub/LilyPond/' by FTP and
65 `http://www.lilypond.org/ftp/' by HTTP.
67 Of course, if your platform supports LilyPond, such as Debian
68 GNU/Linux, FreeBSD, OpenBSD or NetBSD, you're encouraged to use the
69 native build from source drill.
71 For Red Hat Linux and SuSE Linux, `.spec' files are included in the
72 tarball; see instructions below.
77 If you want to track bleeding edge development, try:
80 (ftp://ftp.debian.org/debian/pool/main/l/lilypond/) usually has
81 the latest binaries for the most useful stable and development
85 (http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/) also
86 provides fairly recent versions.
88 Binaries are made available for other popular platforms, but as we
89 need to compile them ourselves, they are not updated for every version
93 (ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/)
95 * SuSE (ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE)
97 * LinuxPPC (ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/)
99 * Windows (http://www.lilypond.org/gnu-windows/)
104 There are two options for upgrading sources.
106 * if you have an unpacked source tree of a previous version, you may
109 _If you upgrade by patching do remember to rerun autoconf after
112 * if you have the `.tar.gz' file of a previous release, you can use
113 xdelta (ftp://ftp.xcf.berkeley.edu/pub/xdelta/). This is much
114 safer than using patches, and is the recommended way.
116 The following command produces `lilypond-1.4.3.tar.gz' from
117 `lilypond-1.4.2.tar.gz' identical (up to compression dates) to the
119 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
127 You need the following packages to compile Lilypond.
129 * A reasonably new C++ compiler: EGCS 1.1, GCC 2.95.2 or newer.
130 Check out the gcc site (ftp://ftp.gnu.org/gnu/gcc/).
132 * Python (version 1.5 or newer; not 2.1.x) Check out the python
133 website (http://www.python.org).
135 * GUILE 1.4 or newer, check out the GUILE webpage
136 (http://www.gnu.org/software/guile/guile.html). Version 1.4 is
137 recommended for better performance.
139 * GNU Make. Check out the GNU make FTP directory
140 (ftp://ftp.gnu.org/gnu/make/).
142 * Flex (version 2.5.4a or newer). Check out the Flex webpage
143 (http://www.gnu.org/software/flex/).
145 * Bison (version 1.25 or newer). Check out the bison webpage
146 (http://www.gnu.org/software/bison/)
150 TeX is used as an output backend.
152 Also, TeX's libkpathsea is used to find the fonts (`.mf', `.afm',
153 `.tfm'). Make sure you have tetex 1.0 or newer (1.0.6 is known to
154 work). You may need to install a tetex-devel or tetex-dev package
157 * Texinfo (version 4.0 or newer). The documentation of lily is
158 written in texinfo. Check out the texinfo FTP directory
159 (ftp://ftp.gnu.org/gnu/texinfo/).
161 * The geometry package for LaTeX is needed to use ly2dvi. It is
162 available at the FTP directory for `geometry'
163 (ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry).
164 This package is normally included with the TeX distribution.
166 * kpathsea, a library for searching (TeX) files. `kpathsea' is
167 usually included with your installation of TeX. You may need to
168 install a tetex-devel or tetex-dev package too.
170 In the very unlikely case that kpathsea is not available for your
171 platform (ie, you're not running GNU/Linux, Windows, or any recent
172 UNIX), you can compile LilyPond without kpathsea support. In that
173 case, you'll probably have to indicate where TeX's tfm files live.
174 Invoke configure something like:
176 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
178 * pktrace, [OPTIONAL], needed for generating PostScript Type1 fonts.
179 Get it from `http://www.cs.uu.nl/~hanwen/pktrace/'
181 * autotrace-0.27a, [OPTIONAL], needed for generating PostScript Type1
182 fonts. `http://autotrace.sourceforge.net'.
184 * MetaPost [OPTIONAL] needed for generating PostScript Type3 fonts.
185 Please note that tetex-0.4pl8 (included with Red Hat 5.x) does not
186 include `mfplain.mp', which is needed for producing the scalable
189 If you don't have MetaPost and don't want to use PostScript
190 output, then edit `mf/GNUmakefile', removing the line saying
197 GNU LilyPond does use a lot of resources. For operation you need the
202 * Xdvi and Ghostscript
204 * GUILE 1.3.4, or newer. Check out the GUILE webpage
205 (http://www.gnu.org/software/guile.html)
207 For running LilyPond successfully you have to help TeX and MetaFont
208 find various files. The recommended way of doing so is adjusting the
209 environment variables in the start-up scripts of your shell. Appropriate
210 Csh and bourne sh scripts are left in
211 `buildscripts/out/lilypond-profile' and
212 `buildscripts/out/lilypond-login' after compilation.
214 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
215 recommended for comfortable use.
220 The documentation comes in the form of a website. You can view this
221 website on the internet, but you can also build it locally. This process
222 requires a successful compile of lilypond. The website is built by
227 Building the website requires some additional tools:
229 * xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
230 The original is at the netpbm FTP site
231 (ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz)
233 * pnmtopng. The original is at in the pnmtopng FTP site
234 (ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz).
236 * texinfo (a development release) The documentation will build with
237 texinfo-4.0, but if you want split html pages, you're best off
238 using the lates pretest version from texinfo-4.0b
239 (ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz) or
240 texinfo-4.0b (ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz)
245 to install GNU LilyPond, type:
246 gunzip -c lilypond-x.y.z | tar xf -
248 ./configure # run with --help to see appropriate options
251 sh buildscripts/clean-fonts.sh
253 If you are doing an upgrade, you should remove all `feta' `.pk' and
254 `.tfm' files. A script has been provided to do the work for you, see
255 `buildscripts/clean-fonts.sh'.
257 If you are not root, you should choose a `--prefix' argument that
258 points into your home directory, eg.
260 ./configure --prefix=$HOME/usr
262 In this case, you have to insert the contents of
263 `buildscripts/out/lilypond-login' or
264 `buildscripts/out/lilypond-profile' into your start up scripts by hand.
266 Configuring for multiple platforms
267 ----------------------------------
269 If you want to build multiple versions of LilyPond with different
270 configuration settings, you can use the `--enable-config=CONF' option
271 of configure. You should use `make conf=CONF' to generate the output
272 in `out-CONF'. Example: suppose I want to build with and without
273 profiling. Then I'd use the following for the normal build,
275 ./configure --prefix=~ --enable-checking
279 and for the profiling version, I specify a different configuration.
282 ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
284 make conf=prof install
289 An Emacs mode for entering music and running LilyPond is included
290 with the source archive as `lilypond-mode.el' and
291 `lilypond-font-lock.el'. You should install these files somewhere in
292 your LOAD-PATH. If you have installed a precompiled LilyPond package,
293 these files can be found in `/usr/share/doc/lilypond-x.y.z/'.
295 Add this to your `~/.emacs' or `~/.emacs.el', or install this file
296 in Emacs' `site-start.d':
297 ;;; lilypond-init.el --- Startup code for LilyPond mode
299 (load-library "lilypond-mode.el")
300 (setq auto-mode-alist
301 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
302 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
304 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode
305 is automatically loaded, you not even need to modify your `~/.emacs'
308 Compiling for distributions
309 ===========================
314 Red Hat 7.0 i386 RPMS are available from
315 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
317 You can also compile them yourself. A spec file is in
318 `make/out/lilypond.redhat.spec'. This file is distributed along with
319 the sources. You can make the rpm by issuing
321 tar xfz lilypond-x.y.z.tar.gz
322 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
323 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
325 For running on a Red Hat system you need these packages: guile,
326 tetex, tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
328 For compilation on a Red Hat system you need these packages, in
329 addition to the those needed for running: glibc-devel, gcc-c++,
330 libstdc++-devel, guile-devel, flex, bison, texinfo, tetex-devel, groff,
336 Some LinuxPPC RPMS should available from
337 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
339 A LinuxPPC RPM can be made using the `lilypond.redhat.spec' file.
344 Some SUSE RPMS should available from
345 `ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE'.
347 You can also compile a RPM for SUSE yourself. A spec file is in
348 `make/out/lilypond.suse.spec', see the instructions for building the
351 You must have the following packages: guile tcsh tetex te_latex
352 te_kpath te_mpost libpng python gpp libgpp gettext autoconf netpbm
353 libnetpb gs_serv gs_lib gs_fonts guile
358 No precompiled packages for Slackware are available.
360 Problems have been reported with Slackware 7.0; apparently, it ships
361 with a faulty compiler. Do not compile LilyPond with -O2 on this
367 Some binaries are available at rpmfind.net. Refer to
368 `http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/'.
370 You can also compile a RPM for Mandrake yourself. A spec file is in
371 `make/out/lilypond.mandrake.spec', see the instructions for building
377 A Debian package is also available. You may install it easily by
378 running `apt-get' as root:
380 apt-get install lilypond lilypond-doc
382 You can also compile the .deb for Debian yourself, do:
384 apt-get -b source lilypond
386 If you're real impatient, you may even do:
388 cd lilypond-x.y.z # a previous version
389 uscan # download and build latest directly from upstream
391 Debian's TeX installation is a bit short on memory, you may want to
392 increase it like this:
393 --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
394 +++ texmf.cnf Sun Dec 16 23:46:34 2001
396 main_memory.context = 1500000
397 main_memory.mpost = 1000000
398 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
399 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
400 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
401 +extra_mem_top = 1000000 % extra high memory for chars, tokens, etc.
402 +extra_mem_bot = 1000000 % extra low memory for boxes, glue, breakpoints, etc.
404 obj_tab_size.context = 300000
407 % Max number of characters in all strings, including all error messages,
408 % help texts, font names, control sequences. These values apply to TeX and MP.
409 pool_size.context = 750000
412 % Minimum pool space after TeX/MP's own strings; must be at least
413 % 25000 less than pool_size, but doesn't need to be nearly that large.
414 string_vacancies.context = 45000
416 You could also export `extra_mem_top' and `extra_mem_bot' as
417 environment variables if you do not want to or cannot modify
418 `/etc/texmf/texmf.cnf'.
422 * http://packages.debian.org/lilypond
423 (http://packages.debian.org/lilypond)
425 * http://people.debian.org/~foka/lilypond/
426 (http://people.debian.org/~foka/lilypond/) for latest
427 semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato)
428 users. The official stable Debian 2.2 is stuck with the old
429 LilyPond-1.3.24. Since LilyPond-1.4 has been released, the older
430 lilypond1.3 Debian package is now obsolete.
432 Please contact Anthony Fok <lilypond@packages.debian.org> for more
435 The build scripts are in the subdirectory `debian/'; you can make
436 the .deb by doing, for example:
439 # dpkg --purge lilypond lilypond1.3
441 $ tar xzf lilypond-1.4.3.tar.gz
443 $ dch -p -v 1.4.3-0.local.1 "Local build."
446 # dpkg -i ../lilypond_1.4.3*.deb
450 Use command `debuild' instead of `debuild -B' if you have a very
451 fast machine and want to build the HTML, PS and DVI documentation too.
453 For compilation on a Debian GNU/Linux system you need these packages,
454 in addition to the those needed for running:
456 * g++, cpp, libc6-dev, libstdc++<YOUR-LIBSTDC++-VERSION-HERE>-dev
458 * libguile<YOUR-LIBGUILE-VERSION-HERE>-dev
460 * make, m4, flex, bison
466 * tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
468 * dpkg-dev, debhelper, fakeroot
472 * pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
473 in Debian testing/unstable.)
475 Most of these are listed on the `Build-Depends' line in the
476 `debian/control' file. To ensure the creation of the lilypond deb is
477 trouble-free, we recommend that you first install the following packages
478 by running \`apt-get' as root before building the package:
482 apt-get install task-debian-devel task-c++-dev \
483 python-base libguile6-dev tetex-bin tetex-dev \
484 tetex-extra flex bison texinfo groff gs \
485 netpbm pnmtopng m4 gettext
487 For Debian in development ("unstable", the future 2.3 or 3.0):
489 apt-get install binutils cpp gcc libc6-dev \
490 g++ libstdc++2.10-dev \
491 python-base libguile-dev tetex-bin libkpathsea-dev \
492 tetex-extra flex bison texinfo groff gs \
495 And, just so that old fonts from previous versions of LilyPond won't
496 interfere with your build, you may want to do this before the build too:
498 dpkg --purge lilypond lilypond1.3
503 For help and questions use <lilypond-user@gnu.org>. Please consult
504 the FAQ before mailing your problems. If you find bugs, please send
505 bug reports to <bug-lilypond@gnu.org>.
507 Bugs that are not fault of LilyPond are documented here.
509 FLex-2.5.4a and gcc-3.0
510 -----------------------
512 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
513 LilyPond with gcc-3.0 you may do:
515 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
516 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
517 patch -p1 < lexer-gcc-3.0.patch
518 make conf=gcc-3.0 -C lily
520 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
525 Regular expressions are broken in Python 2.1.[.1], either upgrade or
528 Linux-2.4.0, Guile-1.4 -with-threads
529 ------------------------------------
531 There's a bug in certain kernels around version 2.4.0, that is
532 triggered when using Guile 1.4 compiled with pthreads. You'll see
533 random segmentation fault crashes of LilyPond. Upgrade to a newer
534 version of Linux. If you can't do that, you may try to recompiling
535 Guile without threads (YMMV):
537 guile-1.4$ ./configure --without-threads; make all install
542 * The flex precompiled in NetBSD-1.4.2 is broken. Download
543 flex-2.5.4a, build, install.
545 * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
546 release)) does not include `/usr/pkg' paths. Configure using:
548 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
554 * Sparc64/Solaris 2.6, GNU make-3.77
556 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
559 * Sparc64/Solaris 2.6, ld
568 The following is from the gcc install/SPECIFIC file.
569 Some versions of the AIX binder (linker) can fail with a
570 relocation overflow severe error when the -bbigtoc option
571 is used to link GCC-produced object files into an
572 executable that overflows the TOC. A fix for APAR IX75823
573 (OVERFLOW DURING LINK WHEN USING GCC AND -BBIGTOC) is
574 available from IBM Customer Support and from its
575 27service.boulder.ibm.com website as PTF U455193.
577 Binutils does not support AIX 4.3 (at least through release
578 2.9). GNU as and GNU ld will not work properly and one
579 should not configure GCC to use those GNU utilities. Use
580 the native AIX tools which do interoperate with GCC.
582 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
583 LDFLAGS='-Wl,-bbigtoc' ./configure