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
30 Linux-2.4.0, Guile-1.4 -with-threads
36 INSTALL - compiling and installing GNU LilyPond
37 ***********************************************
39 This document describes how to build LilyPond on Unix platforms. It
40 is also known to run and compile on Windows NT/95/98 as well. More
41 information on this topic can be found at the LilyPond on Windows page
42 (http://www.lilypond.org/gnu-windows/).
47 Even numbered versions are `stable'. The webpages for the stable
48 version (1.2) reside on the GNU servers
49 (http://www.gnu.org/software/lilypond). Big enhancements go into the
50 latest odd numbered version (1.3), whose webpages are on the lilypond
51 site (http://www.lilypond.org/).
56 If you want to compile LilyPond from source, download here:
57 * Download development releases from
58 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/' by FTP and
59 `http://ftp.cs.uu.nl/pub/GNU/LilyPond/', by HTTP.
61 * `ftp://sca.uwaterloo.ca/pub/' by FTP (Canadian mirror)
63 * at `lilypond.org' `ftp://ftp.lilypond.org/pub/LilyPond/' by FTP and
64 `http://www.lilypond.org/ftp/' by HTTP.
66 Of course, if your platform supports LilyPond, such as Debian
67 GNU/Linux, FreeBSD, OpenBSD or NetBSD, you're encouraged to use the
68 native build from source drill.
70 For Red Hat Linux and SuSE Linux, `.spec' files are included in the
71 tarball; see instructions below.
76 If you want to track bleeding edge development, try:
79 (ftp://ftp.debian.org/debian/pool/main/l/lilypond/) usually has
80 the latest binaries for the most useful stable and development
84 (http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/) also
85 provides fairly recent versions.
87 Binaries are made available for other popular platforms, but as we
88 need to compile them ourselves, they are not updated for every version
92 (ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/)
94 * SuSE (ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE)
96 * LinuxPPC (ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/)
98 * Windows (http://www.lilypond.org/gnu-windows/)
103 There are two options for upgrading sources.
105 * if you have an unpacked source tree of a previous version, you may
108 _If you upgrade by patching do remember to rerun autoconf after
111 * if you have the `.tar.gz' file of a previous release, you can use
112 xdelta (ftp://ftp.xcf.berkeley.edu/pub/xdelta/). This is much
113 safer than using patches, and is the recommended way.
115 The following command produces `lilypond-1.4.3.tar.gz' from
116 `lilypond-1.4.2.tar.gz' identical (up to compression dates) to the
118 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
126 You need the following packages to compile Lilypond.
128 * A reasonably new C++ compiler: EGCS 1.1, GCC 2.95.2 or newer.
129 Check out the gcc site (ftp://ftp.gnu.org/gnu/gcc/).
131 * Python 1.5, Check out the python website (http://www.python.org).
133 * GUILE 1.3.4 or newer, check out the GUILE webpage
134 (http://www.gnu.org/software/guile/guile.html). Version 1.4 is
135 recommended for better performance.
137 * GNU Make. Check out the GNU make FTP directory
138 (ftp://ftp.gnu.org/gnu/make/).
140 * Flex (version 2.5.4a or newer). Check out the Flex webpage
141 (http://www.gnu.org/software/flex/).
143 * Bison (version 1.25 or newer). Check out the bison webpage
144 (http://www.gnu.org/software/bison/)
148 TeX is used as an output backend.
150 Also, TeX's libkpathsea is used to find the fonts (`.mf', `.afm',
151 `.tfm'). Make sure you have tetex 1.0 or newer (1.0.6 is known to
152 work). You may need to install a tetex-devel or tetex-dev package
155 * Texinfo (version 4.0 or newer). The documentation of lily is
156 written in texinfo. Check out the texinfo FTP directory
157 (ftp://ftp.gnu.org/gnu/texinfo/).
159 * The geometry package for LaTeX is needed to use ly2dvi. It is
160 available at the FTP directory for `geometry'
161 (ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry).
162 This package is normally included with the TeX distribution.
164 * kpathsea, a library for searching (TeX) files. `kpathsea' is
165 usually included with your installation of TeX. You may need to
166 install a tetex-devel or tetex-dev package too.
168 In the very unlikely case that kpathsea is not available for your
169 platform (ie, you're not running GNU/Linux, Windows, or any recent
170 UNIX), you can compile LilyPond without kpathsea support. In that
171 case, you'll probably have to indicate where TeX's tfm files live.
172 Invoke configure something like:
174 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
176 * pktrace, [OPTIONAL], needed for generating PostScript Type1 fonts.
177 Get it from `http://www.cs.uu.nl/~hanwen/pktrace/'
179 * autotrace-0.27a, [OPTIONAL], needed for generating PostScript Type1
180 fonts. `http://autotrace.sourceforge.net'.
182 * MetaPost [OPTIONAL] needed for generating PostScript Type3 fonts.
183 Please note that tetex-0.4pl8 (included with Red Hat 5.x) does not
184 include `mfplain.mp', which is needed for producing the scalable
187 If you don't have MetaPost and don't want to use PostScript
188 output, then edit `mf/GNUmakefile', removing the line saying
195 GNU LilyPond does use a lot of resources. For operation you need the
200 * Xdvi and Ghostscript
202 * GUILE 1.3.4, or newer. Check out the GUILE webpage
203 (http://www.gnu.org/software/guile.html)
205 For running LilyPond successfully you have to help TeX and MetaFont
206 find various files. The recommended way of doing so is adjusting the
207 environment variables in the start-up scripts of your shell. Appropriate
208 Csh and bourne sh scripts are left in
209 `buildscripts/out/lilypond-profile' and
210 `buildscripts/out/lilypond-login' after compilation.
212 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
213 recommended for comfortable use.
218 The documentation comes in the form of a website. You can view this
219 website on the internet, but you can also build it locally. This process
220 requires a successful compile of lilypond. The website is built by
225 Building the website requires some additional tools:
227 * xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
228 The original is at the netpbm FTP site
229 (ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz)
231 * pnmtopng. The original is at in the pnmtopng FTP site
232 (ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz).
234 * texinfo (a development release) The documentation will build with
235 texinfo-4.0, but if you want split html pages, you're best off
236 using the lates pretest version from texinfo-4.0b
237 (ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz) or
238 texinfo-4.0b (ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz)
243 to install GNU LilyPond, type:
244 gunzip -c lilypond-x.y.z | tar xf -
246 ./configure # run with --help to see appropriate options
249 sh buildscripts/clean-fonts.sh
251 If you are doing an upgrade, you should remove all `feta' `.pk' and
252 `.tfm' files. A script has been provided to do the work for you, see
253 `buildscripts/clean-fonts.sh'.
255 If you are not root, you should choose a `--prefix' argument that
256 points into your home directory, eg.
258 ./configure --prefix=$HOME/usr
260 In this case, you have to insert the contents of
261 `buildscripts/out/lilypond-login' or
262 `buildscripts/out/lilypond-profile' into your start up scripts by hand.
264 Configuring for multiple platforms
265 ----------------------------------
267 If you want to build multiple versions of LilyPond with different
268 configuration settings, you can use the `--enable-config=CONF' option
269 of configure. You should use `make conf=CONF' to generate the output
270 in `out-CONF'. Example: suppose I want to build with and without
271 profiling. Then I'd use the following for the normal build,
273 ./configure --prefix=~ --enable-checking
277 and for the profiling version, I specify a different configuration.
280 ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
282 make conf=prof install
287 An Emacs mode for entering music and running LilyPond is included
288 with the source archive as `lilypond-mode.el' and
289 `lilypond-font-lock.el'. You should install these files somewhere in
290 your LOAD-PATH. If you have installed a precompiled LilyPond package,
291 these files can be found in `/usr/share/doc/lilypond-x.y.z/'.
293 Add this to your `~/.emacs' or `~/.emacs.el', or install this file
294 in Emacs' `site-start.d':
295 ;;; lilypond-init.el --- Startup code for LilyPond mode
297 (load-library "lilypond-mode.el")
298 (setq auto-mode-alist
299 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
300 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
302 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode
303 is automatically loaded, you not even need to modify your `~/.emacs'
306 Compiling for distributions
307 ===========================
312 Red Hat 7.0 i386 RPMS are available from
313 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
315 You can also compile them yourself. A spec file is in
316 `make/out/lilypond.redhat.spec'. This file is distributed along with
317 the sources. You can make the rpm by issuing
319 tar xfz lilypond-x.y.z.tar.gz
320 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
321 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
323 For running on a Red Hat system you need these packages: guile,
324 tetex, tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
326 For compilation on a Red Hat system you need these packages, in
327 addition to the those needed for running: glibc-devel, gcc-c++,
328 libstdc++-devel, guile-devel, flex, bison, texinfo, tetex-devel, groff,
334 Some LinuxPPC RPMS should available from
335 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
337 A LinuxPPC RPM can be made using the `lilypond.redhat.spec' file.
342 Some SUSE RPMS should available from
343 `ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE'.
345 You can also compile a RPM for SUSE yourself. A spec file is in
346 `make/out/lilypond.suse.spec', see the instructions for building the
349 You must have the following packages: guile tcsh tetex te_latex
350 te_kpath te_mpost libpng python gpp libgpp gettext autoconf netpbm
351 libnetpb gs_serv gs_lib gs_fonts guile
356 No precompiled packages for Slackware are available.
358 Problems have been reported with Slackware 7.0; apparently, it ships
359 with a faulty compiler. Do not compile LilyPond with -O2 on this
365 Some binaries are available at rpmfind.net. Refer to
366 `http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/'.
368 You can also compile a RPM for Mandrake yourself. A spec file is in
369 `make/out/lilypond.mandrake.spec', see the instructions for building
375 A Debian package is also available. You may install it easily by
376 running `apt-get' as root:
378 apt-get install lilypond lilypond-doc
380 You can also compile the .deb for Debian yourself, do:
382 apt-get -b source lilypond
384 If you're real impatient, you may even do:
386 cd lilypond-x.y.z # a previous version
387 uscan # download and build latest directly from upstream
389 Debian's TeX installation is a bit short on memory, you may want to
390 increase it like this:
391 --- /etc/texmf/texmf.cnf.dpkg Sun Jan 28 14:12:14 2001
392 +++ /etc/texmf/texmf.cnf Fri Apr 27 11:09:35 2001
394 main_memory.context = 1500000
395 main_memory.mpost = 1000000
396 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
397 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
398 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
399 +extra_mem_top = 100000 % extra high memory for chars, tokens, etc.
400 +extra_mem_bot = 100000 % extra low memory for boxes, glue, breakpoints, etc.
402 obj_tab_size.context = 256000
404 You could also export `extra_mem_top' and `extra_mem_bot' as
405 environment variables if you do not want to or cannot modify
406 `/etc/texmf/texmf.cnf'.
410 * http://packages.debian.org/lilypond
411 (http://packages.debian.org/lilypond)
413 * http://people.debian.org/~foka/lilypond/
414 (http://people.debian.org/~foka/lilypond/) for latest
415 semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato)
416 users. The official stable Debian 2.2 is stuck with the old
417 LilyPond-1.3.24. Since LilyPond-1.4 has been released, the older
418 lilypond1.3 Debian package is now obsolete.
420 Please contact Anthony Fok <lilypond@packages.debian.org> for more
423 The build scripts are in the subdirectory `debian/'; you can make
424 the .deb by doing, for example:
427 # dpkg --purge lilypond lilypond1.3
429 $ tar xzf lilypond-1.4.3.tar.gz
431 $ dch -p -v 1.4.3-0.local.1 "Local build."
434 # dpkg -i ../lilypond_1.4.3*.deb
438 Use command `debuild' instead of `debuild -B' if you have a very
439 fast machine and want to build the HTML, PS and DVI documentation too.
441 For compilation on a Debian GNU/Linux system you need these packages,
442 in addition to the those needed for running:
444 * g++, cpp, libc6-dev, libstdc++<YOUR-LIBSTDC++-VERSION-HERE>-dev
446 * libguile<YOUR-LIBGUILE-VERSION-HERE>-dev
448 * make, m4, flex, bison
454 * tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
456 * dpkg-dev, debhelper, fakeroot
460 * pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
461 in Debian testing/unstable.)
463 Most of these are listed on the `Build-Depends' line in the
464 `debian/control' file. To ensure the creation of the lilypond deb is
465 trouble-free, we recommend that you first install the following packages
466 by running \`apt-get' as root before building the package:
470 apt-get install task-debian-devel task-c++-dev \
471 python-base libguile6-dev tetex-bin tetex-dev \
472 tetex-extra flex bison texinfo groff gs \
473 netpbm pnmtopng m4 gettext
475 For Debian in development ("unstable", the future 2.3 or 3.0):
477 apt-get install binutils cpp gcc libc6-dev \
478 g++ libstdc++2.10-dev \
479 python-base libguile-dev tetex-bin libkpathsea-dev \
480 tetex-extra flex bison texinfo groff gs \
483 And, just so that old fonts from previous versions of LilyPond won't
484 interfere with your build, you may want to do this before the build too:
486 dpkg --purge lilypond lilypond1.3
491 For help and questions use <lilypond-user@gnu.org>. Please consult
492 the FAQ before mailing your problems. If you find bugs, please send
493 bug reports to <bug-lilypond@gnu.org>.
495 Bugs that are not fault of LilyPond are documented here.
497 FLex-2.5.4a and gcc-3.0
498 -----------------------
500 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
501 LilyPond with gcc-3.0 you may do:
503 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
504 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
505 patch -p1 < lexer-gcc-3.0.patch
506 make conf=gcc-3.0 -C lily
508 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
510 Linux-2.4.0, Guile-1.4 -with-threads
511 ------------------------------------
513 There's a bug in certain kernels around version 2.4.0, that is
514 triggered when using Guile 1.4 compiled with pthreads. You'll see
515 random segmentation fault crashes of LilyPond. Upgrade to a newer
516 version of Linux. If you can't do that, you may try to recompiling
517 Guile without threads (YMMV):
519 guile-1.4$ ./configure --without-threads; make all install
524 * The flex precompiled in NetBSD-1.4.2 is broken. Download
525 flex-2.5.4a, build, install.
527 * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
528 release)) does not include `/usr/pkg' paths. Configure using:
530 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
536 * Sparc64/Solaris 2.6, GNU make-3.77
538 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
541 * Sparc64/Solaris 2.6, ld
550 The following is from the gcc install/SPECIFIC file.
551 Some versions of the AIX binder (linker) can fail with a
552 relocation overflow severe error when the -bbigtoc option
553 is used to link GCC-produced object files into an
554 executable that overflows the TOC. A fix for APAR IX75823
555 (OVERFLOW DURING LINK WHEN USING GCC AND -BBIGTOC) is
556 available from IBM Customer Support and from its
557 27service.boulder.ibm.com website as PTF U455193.
559 Binutils does not support AIX 4.3 (at least through release
560 2.9). GNU as and GNU ld will not work properly and one
561 should not configure GCC to use those GNU utilities. Use
562 the native AIX tools which do interoperate with GCC.
564 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
565 LDFLAGS='-Wl,-bbigtoc' ./configure