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 version of the GNU C++ compiler: EGCS 1.1, GCC
130 2.95.2 or newer. Check out the gcc site
131 (ftp://ftp.gnu.org/gnu/gcc/).
133 * Python (version 1.5 or newer). Check out the python website
134 (http://www.python.org).
136 * GUILE (version 1.4 or newer). Check out the GUILE webpage
137 (http://www.gnu.org/software/guile/guile.html). Version 1.4 is
138 recommended for better performance.
140 * GNU Make. Check out the GNU make FTP directory
141 (ftp://ftp.gnu.org/gnu/make/).
143 * Flex (version 2.5.4a or newer). Check out the Flex webpage
144 (http://www.gnu.org/software/flex/).
146 * Bison (version 1.25 or newer). Check out the bison webpage
147 (http://www.gnu.org/software/bison/)
151 TeX is used as an output backend.
153 Also, TeX's libkpathsea is used to find the fonts (`.mf', `.afm',
154 `.tfm'). Make sure you have tetex 1.0 or newer (1.0.6 is known to
155 work). You may need to install a tetex-devel or tetex-dev package
158 * Texinfo (version 4.0 or newer). The documentation of lily is
159 written in texinfo. Check out the texinfo FTP directory
160 (ftp://ftp.gnu.org/gnu/texinfo/).
162 * The geometry package for LaTeX is needed to use ly2dvi. It is
163 available at the FTP directory for `geometry'
164 (ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry).
165 This package is normally included with the TeX distribution.
167 * kpathsea, a library for searching (TeX) files. `kpathsea' is
168 usually included with your installation of TeX. You may need to
169 install a tetex-devel or tetex-dev package too.
171 In the very unlikely case that kpathsea is not available for your
172 platform (ie, you're not running GNU/Linux, Windows, or any recent
173 UNIX), you can compile LilyPond without kpathsea support. In that
174 case, you'll probably have to indicate where TeX's tfm files live.
175 Invoke configure something like:
177 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
179 * pktrace, [OPTIONAL], needed for generating PostScript Type1 fonts.
180 Get it from `http://www.cs.uu.nl/~hanwen/pktrace/'. You will
181 need to install some additional packages to get pktrace to work.
187 GNU LilyPond does use a lot of resources. For operation you need the
192 * Xdvi and Ghostscript
194 * GUILE 1.3.4, or newer. Check out the GUILE webpage
195 (http://www.gnu.org/software/guile.html)
197 For running LilyPond successfully you have to help TeX and MetaFont
198 find various files. The recommended way of doing so is adjusting the
199 environment variables in the start-up scripts of your shell. Appropriate
200 Csh and bourne sh scripts are left in
201 `buildscripts/out/lilypond-profile' and
202 `buildscripts/out/lilypond-login' after compilation.
204 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
205 recommended for comfortable use.
210 The documentation comes in the form of a website. You can view this
211 website on the internet, but you can also build it locally. This process
212 requires a successful compile of lilypond. The website is built by
217 Building the website requires some additional tools:
219 * xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
220 The original is at the netpbm FTP site
221 (ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz)
223 * pnmtopng. The original is at in the pnmtopng FTP site
224 (ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz).
226 * texinfo (a development release) The documentation will build with
227 texinfo-4.0, but if you want split html pages, you're best off
228 using the lates pretest version from texinfo-4.0b
229 (ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz) or
230 texinfo-4.0b (ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz)
235 to install GNU LilyPond, type:
236 gunzip -c lilypond-x.y.z | tar xf -
238 ./configure # run with --help to see appropriate options
241 sh buildscripts/clean-fonts.sh
243 If you are doing an upgrade, you should remove all `feta' `.pk' and
244 `.tfm' files. A script has been provided to do the work for you, see
245 `buildscripts/clean-fonts.sh'.
247 If you are not root, you should choose a `--prefix' argument that
248 points into your home directory, eg.
250 ./configure --prefix=$HOME/usr
252 In this case, you have to insert the contents of
253 `buildscripts/out/lilypond-login' or
254 `buildscripts/out/lilypond-profile' into your start up scripts by hand.
256 Configuring for multiple platforms
257 ----------------------------------
259 If you want to build multiple versions of LilyPond with different
260 configuration settings, you can use the `--enable-config=CONF' option
261 of configure. You should use `make conf=CONF' to generate the output
262 in `out-CONF'. Example: suppose I want to build with and without
263 profiling. Then I'd use the following for the normal build,
265 ./configure --prefix=~ --enable-checking
269 and for the profiling version, I specify a different configuration.
272 ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
274 make conf=prof install
279 An Emacs mode for entering music and running LilyPond is included
280 with the source archive as `lilypond-mode.el' and
281 `lilypond-font-lock.el'. You should install these files somewhere in
282 your LOAD-PATH. If you have installed a precompiled LilyPond package,
283 these files can be found in `/usr/share/doc/lilypond-x.y.z/'.
285 Add this to your `~/.emacs' or `~/.emacs.el', or install this file
286 in Emacs' `site-start.d':
287 ;;; lilypond-init.el --- Startup code for LilyPond mode
289 (load-library "lilypond-mode.el")
290 (setq auto-mode-alist
291 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
292 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
294 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode
295 is automatically loaded, you not even need to modify your `~/.emacs'
298 Compiling for distributions
299 ===========================
304 Red Hat 7.0 i386 RPMS are available from
305 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
307 You can also compile them yourself. A spec file is in
308 `make/out/lilypond.redhat.spec'. This file is distributed along with
309 the sources. You can make the rpm by issuing
311 tar xfz lilypond-x.y.z.tar.gz
312 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
313 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
315 For running on a Red Hat system you need these packages: guile,
316 tetex, tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
318 For compilation on a Red Hat system you need these packages, in
319 addition to the those needed for running: glibc-devel, gcc-c++,
320 libstdc++-devel, guile-devel, flex, bison, texinfo, groff.
325 Some LinuxPPC RPMS should available from
326 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
328 A LinuxPPC RPM can be made using the `lilypond.redhat.spec' file.
333 Some SUSE RPMS should available from
334 `ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE'.
336 You can also compile a RPM for SUSE yourself. A spec file is in
337 `make/out/lilypond.suse.spec', see the instructions for building the
340 You must have the following packages: guile tcsh tetex te_latex
341 te_kpath te_mpost libpng python gpp libgpp gettext autoconf netpbm
342 libnetpb gs_serv gs_lib gs_fonts guile
347 No precompiled packages for Slackware are available.
349 Problems have been reported with Slackware 7.0; apparently, it ships
350 with a faulty compiler. Do not compile LilyPond with -O2 on this
356 Some binaries are available at rpmfind.net. Refer to
357 `http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/'.
359 You can also compile a RPM for Mandrake yourself. A spec file is in
360 `make/out/lilypond.mandrake.spec', see the instructions for building
366 A Debian package is also available. You may install it easily by
367 running `apt-get' as root:
369 apt-get install lilypond lilypond-doc
371 You can also compile the .deb for Debian yourself, do:
373 apt-get -b source lilypond
375 If you're real impatient, you may even do:
377 cd lilypond-x.y.z # a previous version
378 uscan # download and build latest directly from upstream
380 Debian's TeX installation is a bit short on memory, you may want to
381 increase it like this:
382 --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
383 +++ texmf.cnf Sun Dec 16 23:46:34 2001
385 main_memory.context = 1500000
386 main_memory.mpost = 1000000
387 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
388 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
389 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
390 +extra_mem_top = 1000000 % extra high memory for chars, tokens, etc.
391 +extra_mem_bot = 1000000 % extra low memory for boxes, glue, breakpoints, etc.
393 obj_tab_size.context = 300000
396 % Max number of characters in all strings, including all error messages,
397 % help texts, font names, control sequences. These values apply to TeX and MP.
398 pool_size.context = 750000
401 % Minimum pool space after TeX/MP's own strings; must be at least
402 % 25000 less than pool_size, but doesn't need to be nearly that large.
403 string_vacancies.context = 45000
405 You could also export `extra_mem_top' and `extra_mem_bot' as
406 environment variables if you do not want to or cannot modify
407 `/etc/texmf/texmf.cnf'.
411 * http://packages.debian.org/lilypond
412 (http://packages.debian.org/lilypond)
414 * http://people.debian.org/~foka/lilypond/
415 (http://people.debian.org/~foka/lilypond/) for latest
416 semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato)
417 users. The official stable Debian 2.2 is stuck with the old
418 LilyPond-1.3.24. Since LilyPond-1.4 has been released, the older
419 lilypond1.3 Debian package is now obsolete.
421 Please contact Anthony Fok <lilypond@packages.debian.org> for more
424 The build scripts are in the subdirectory `debian/'; you can make
425 the .deb by doing, for example:
428 # dpkg --purge lilypond lilypond1.3
430 $ tar xzf lilypond-1.4.3.tar.gz
432 $ dch -p -v 1.4.3-0.local.1 "Local build."
435 # dpkg -i ../lilypond_1.4.3*.deb
439 Use command `debuild' instead of `debuild -B' if you have a very
440 fast machine and want to build the HTML, PS and DVI documentation too.
442 For compilation on a Debian GNU/Linux system you need these packages,
443 in addition to the those needed for running:
445 * g++, cpp, libc6-dev, libstdc++<YOUR-LIBSTDC++-VERSION-HERE>-dev
447 * libguile<YOUR-LIBGUILE-VERSION-HERE>-dev
449 * make, m4, flex, bison
455 * tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
457 * dpkg-dev, debhelper, fakeroot
461 * pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
462 in Debian testing/unstable.)
464 Most of these are listed on the `Build-Depends' line in the
465 `debian/control' file. To ensure the creation of the lilypond deb is
466 trouble-free, we recommend that you first install the following packages
467 by running \`apt-get' as root before building the package:
471 apt-get install task-debian-devel task-c++-dev \
472 python-base libguile6-dev tetex-bin tetex-dev \
473 tetex-extra flex bison texinfo groff gs \
474 netpbm pnmtopng m4 gettext
476 For Debian in development ("unstable", the future 2.3 or 3.0):
478 apt-get install binutils cpp gcc libc6-dev \
479 g++ libstdc++2.10-dev \
480 python-base libguile-dev tetex-bin libkpathsea-dev \
481 tetex-extra flex bison texinfo groff gs \
484 And, just so that old fonts from previous versions of LilyPond won't
485 interfere with your build, you may want to do this before the build too:
487 dpkg --purge lilypond lilypond1.3
492 For help and questions use <lilypond-user@gnu.org>. Please consult
493 the FAQ before mailing your problems. If you find bugs, please send
494 bug reports to <bug-lilypond@gnu.org>.
496 Bugs that are not fault of LilyPond are documented here.
498 FLex-2.5.4a and gcc-3.0
499 -----------------------
501 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
502 LilyPond with gcc-3.0 you may do:
504 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
505 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
506 patch -p1 < lexer-gcc-3.0.patch
507 make conf=gcc-3.0 -C lily
509 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
514 Regular expressions are broken in Python 2.1.[.1], either upgrade or
517 Linux-2.4.0, Guile-1.4 -with-threads
518 ------------------------------------
520 There's a bug in certain kernels around version 2.4.0, that is
521 triggered when using Guile 1.4 compiled with pthreads. You'll see
522 random segmentation fault crashes of LilyPond. Upgrade to a newer
523 version of Linux. If you can't do that, you may try to recompiling
524 Guile without threads (YMMV):
526 guile-1.4$ ./configure --without-threads; make all install
531 * The flex precompiled in NetBSD-1.4.2 is broken. Download
532 flex-2.5.4a, build, install.
534 * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
535 release)) does not include `/usr/pkg' paths. Configure using:
537 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
543 * Sparc64/Solaris 2.6, GNU make-3.77
545 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
548 * Sparc64/Solaris 2.6, ld
557 The following is from the gcc install/SPECIFIC file.
558 Some versions of the AIX binder (linker) can fail with a
559 relocation overflow severe error when the -bbigtoc option
560 is used to link GCC-produced object files into an
561 executable that overflows the TOC. A fix for APAR IX75823
562 (OVERFLOW DURING LINK WHEN USING GCC AND -BBIGTOC) is
563 available from IBM Customer Support and from its
564 27service.boulder.ibm.com website as PTF U455193.
566 Binutils does not support AIX 4.3 (at least through release
567 2.9). GNU as and GNU ld will not work properly and one
568 should not configure GCC to use those GNU utilities. Use
569 the native AIX tools which do interoperate with GCC.
571 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
572 LDFLAGS='-Wl,-bbigtoc' ./configure