2 @comment node-name, next, previous, up\input texinfo @c -*-texinfo-*-
3 @setfilename INSTALL.info
4 @settitle INSTALL - compiling and installing GNU LilyPond
7 <!--- @@WEB-TITLE@@=Installation Instructions --->
15 @chapter INSTALL - compiling and installing GNU LilyPond
18 This document describes how to build LilyPond on Unix platforms. It
19 is also known to run and compile on Windows NT/95/98/ME/XP as well.
20 More information on this topic can be found at the
21 @uref{http://www.lilypond.org/cygwin/, LilyPond on Windows page}.
25 <a name="download-source">
30 Even numbered versions are `stable'. The webpages for the stable version
31 (1.4) reside @uref{http://www.gnu.org/software/lilypond, on the GNU
32 servers}. Big enhancements go into the latest odd numbered version
33 (1.5), whose webpages are on @uref{http://www.lilypond.org/,the lilypond
36 @subsection Source code
38 If you want to compile LilyPond from source, download here:
40 @item Download development releases from
41 @c Hmm, these won't show up in lilypond.org/stats
42 @c Otoh, lilypond.org is not updated when release mail arrives
43 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/} by FTP and
44 @uref{http://ftp.cs.uu.nl/pub/GNU/LilyPond/}, by HTTP.
45 @item @uref{ftp://sca.uwaterloo.ca/pub/} by FTP (Canadian mirror)
46 @item at @code{lilypond.org}
47 @uref{ftp://ftp.lilypond.org/pub/LilyPond/} by FTP and
48 @uref{http://www.lilypond.org/ftp/} by HTTP.
52 For Red Hat Linux and SuSE Linux, @file{.spec} files are included in the
53 tarball; see instructions below.
57 Of course, if your platform supports LilyPond, such as Debian GNU/Linux,
58 FreeBSD, OpenBSD or NetBSD, you're encouraged to use the native build
61 The latest development version is also available through anonymous
62 CVS. See @uref{http://savannah.gnu.org/cvs/?group=lilypond}.
66 <a name="download-binaries">
71 @subsection Precompiled binaries
73 If you want to track bleeding edge development, try:
76 @item @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond/, Debian
77 GNU/Linux} usually has the latest binaries for the most useful stable
78 and development versions, while
79 @item @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/,
80 Mandrake Cooker} also provides fairly recent versions.
83 Binaries are made available for other popular platforms, but as we need
84 to compile them ourselves, they are not updated for every version
88 @item @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/, Red Hat i386}
89 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE, SuSE}
90 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/,
93 @uref{http://www.lilypond.org/gnu-windows/, Windows}
98 There are two options for upgrading sources.
101 @item if you have an unpacked source tree of a previous version, you
104 @emph{If you upgrade by patching do remember to rerun autoconf after
107 @item if you have the @code{.tar.gz} file of a previous release, you can
109 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
110 This is much safer than using patches, and is the recommended way.
112 The following command produces @file{lilypond-1.4.3.tar.gz} from
113 @file{lilypond-1.4.2.tar.gz} identical (up to compression dates) to the .3
116 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
120 @section Requirements
122 @subsection Compilation
124 You need the following packages to compile Lilypond.
127 @item The GNU c++ compiler (version 2.95.2 or newer).
128 EGCS 1.1 may work, but is no longer supported.
129 Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
131 WARNING: if you choose to upgrade to GCC 3.x, enquire if your
132 distribution supports g++ 3.x and flex. At the time of writing (Fri
133 Jul 5 2002), @strong{no} distribution that we know of ships a flex
134 that generates gcc-3.1.x compliant C++ code.
136 @item Python (version 1.5 or newer).
137 Check out @uref{http://www.python.org, the python website}.
139 @item GUILE (version 1.4 or newer).
141 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
145 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
148 @item Flex (version 2.5.4a or newer).
149 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
151 WARNING: plain Flex 2.5.4(a) generates invalid C++ code. GCC 3.x
152 chokes on this. If you wish to use GCC 3.x, make sure that your
153 distribution supports g++ 3.x and flex. For workarounds, see
154 lexer-gcc-3.0.patch and lexer-gcc-3.1.sh in the source directory.
156 @item Bison (version 1.25 or newer).
157 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}
161 @TeX{} is used as an output backend.
163 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf}, @file{.afm}, @file{.tfm}).
164 Make sure you have tetex 1.0 or newer (1.0.6 is known to work). You may
165 need to install a tetex-devel or tetex-dev package too.
167 @item Texinfo (version 4.2 or newer).
168 The documentation of lily is written in texinfo. Check out
169 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
171 @item The geometry package for LaTeX is needed to use ly2dvi.
173 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
174 FTP directory for @code{geometry}}. This package is normally included
175 with the @TeX{} distribution.
177 @item kpathsea, a library for searching (@TeX{}) files. @code{kpathsea} is
178 usually included with your installation of @TeX{}. You may need to
179 install a tetex-devel or tetex-dev package too. If kpathsea is not
180 installed in a directory where the compiler normally looks, read the
181 hints for Slackware below.
183 In the very unlikely case that kpathsea is not available for your
184 platform (ie, you're not running GNU/Linux, Windows, or any recent
185 UNIX), you can compile LilyPond without kpathsea support. In that case,
186 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
187 configure something like:
191 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
197 @subsection Running requirements
199 GNU LilyPond does use a lot of resources. For operation you need the
204 @item Xdvi and Ghostscript
205 @item GUILE 1.4, or newer.
207 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
210 For running LilyPond successfully you have to help @TeX{} and MetaFont find
211 various files. The recommended way of doing so is adjusting the
212 environment variables in the start-up scripts of your shell. Appropriate
213 Csh and bourne sh scripts are left in
214 @file{buildscripts/out/lilypond-profile} and
215 @file{buildscripts/out/lilypond-login} after compilation.
217 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
218 recommended for comfortable use.
220 @subsection Website requirements
222 The documentation comes in the form of a website. You can view this
223 website on the internet, but you can also build it locally. This process
224 requires a successful compile of lilypond. The website is built
232 Building the website requires some additional tools:
235 @item The netpbm utilities, see @uref{http://netpbm.sourceforge.net/}
236 @item mftrace 1.0 or newer, needed for generating PostScript Type1
237 fonts. Get it from @uref{http://www.cs.uu.nl/~hanwen/mftrace/}. You
238 will need to install some additional packages to get mftrace to work.
241 @section Building LilyPond
243 to install GNU LilyPond, type:
245 gunzip -c lilypond-x.y.z | tar xf -
247 ./configure # run with --help to see appropriate options
250 sh buildscripts/clean-fonts.sh
253 If you are doing an upgrade, you should remove all @file{feta}
254 @code{.pk} and @file{.tfm} files. A script has been provided to do the
255 work for you, see @file{buildscripts/clean-fonts.sh}.
258 If you are not root, you should choose a @code{--prefix} argument that
259 points into your home directory, eg.
262 ./configure --prefix=$HOME/usr
266 In this case, you have to insert the contents of
267 @code{buildscripts/out/lilypond-login} or
268 @code{buildscripts/out/lilypond-profile} into your start up scripts by
273 @subsection Configuring for multiple platforms
275 If you want to build multiple versions of LilyPond with different
276 configuration settings, you can use the @code{--enable-config=CONF}
277 option of configure. You should use @samp{make conf=CONF} to generate
278 the output in @file{out-CONF}. Example: suppose I want to build with
279 and without profiling. Then I'd use the following for the normal
284 ./configure --prefix=$HOME/usr/ --enable-checking
289 and for the profiling version, I specify a different configuration.
293 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
295 make conf=prof install
305 An Emacs mode for entering music and running LilyPond is included with
306 the source archive as @file{lilypond-mode.el},
307 @file{lilypond-indent.el} and @file{lilypond-font-lock.el}. You
308 should install these files somewhere in your @var{load-path}. If you
309 have installed a precompiled LilyPond package, these files can be
310 found in @file{/usr/share/doc/lilypond-x.y.z/}.
312 Add this to your @file{~/.emacs} or @file{~/.emacs.el}, or install this
313 file in Emacs' @file{site-start.d}:
316 ;;; lilypond-init.el --- Startup code for LilyPond mode
318 (autoload 'LilyPond-mode "lilypond-mode")
319 (setq auto-mode-alist
320 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
322 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
326 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode is
327 automatically loaded, you not even need to modify your @code{~/.emacs}
330 @section Compiling for distributions
332 @subsection Red Hat Linux
334 Red Hat 7.x i386 RPMS are available from
335 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}. For running on
336 a Red Hat system you need these packages: guile, tetex, tetex-latex,
337 tetex-dvips, libstdc++, python, ghostscript.
339 You can also compile them yourself. A spec file is in
340 @file{make/out/lilypond.redhat.spec}. This file is distributed along
341 with the sources. You can make the rpm by issuing
344 tar xfz lilypond-x.y.z.tar.gz
345 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
346 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
350 For compilation on a Red Hat system you need these packages, in
351 addition to the those needed for running: glibc-devel, gcc-c++,
352 libstdc++-devel, guile-devel, flex, bison, texinfo, groff, mftrace,
353 netpbm-progs, autotrace, t1utils.
360 Some LinuxPPC RPMS should available from
361 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
363 A LinuxPPC RPM can be made using the @file{lilypond.redhat.spec} file.
367 Some SUSE RPMS should available from
368 @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.
370 You can also compile a RPM for SUSE yourself. A spec file is in
371 @file{make/out/lilypond.suse.spec}, see the instructions for building
374 You must have the following packages: guile tcsh tetex te_latex te_kpath
375 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
376 gs_serv gs_lib gs_fonts guile
378 @subsection Slackware
380 No precompiled packages for Slackware are available.
382 Problems have been reported with Slackware 7.0; apparently, it ships
383 with a faulty compiler. Do not compile LilyPond with -O2 on this
386 At least on Slackware 8.0, you have to manually specify the paths to the
387 Kpathsea library, see the section on kpathsea
392 Some binaries are available at rpmfind.net. Refer to
393 @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.
395 You can also compile a RPM for Mandrake yourself. A spec file is in
396 @file{make/out/lilypond.mandrake.spec}, see the instructions for building
399 @subsection Debian GNU/Linux
401 A Debian package is also available. You may install it easily by running
402 @command{apt-get} as root:
405 apt-get install lilypond lilypond-doc
408 You can also compile the .deb for Debian yourself, do:
411 apt-get -b source lilypond
414 If you're real impatient, you may even do:
417 cd lilypond-x.y.z # a previous version
418 uscan # download and build latest directly from upstream
422 Debian's @TeX{} installation is a bit short on memory, you may want to
423 increase it like this:
425 --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
426 +++ texmf.cnf Sun Dec 16 23:46:34 2001
428 main_memory.context = 1500000
429 main_memory.mpost = 1000000
430 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
431 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
432 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
433 +extra_mem_top = 1000000 % extra high memory for chars, tokens, etc.
434 +extra_mem_bot = 1000000 % extra low memory for boxes, glue, breakpoints, etc.
436 obj_tab_size.context = 300000
439 % Max number of characters in all strings, including all error messages,
440 % help texts, font names, control sequences. These values apply to TeX and MP.
441 pool_size.context = 750000
444 % Minimum pool space after TeX/MP's own strings; must be at least
445 % 25000 less than pool_size, but doesn't need to be nearly that large.
446 string_vacancies.context = 45000
449 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
450 environment variables if you do not want to or cannot modify
451 @file{/etc/texmf/texmf.cnf}.
456 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
457 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
458 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
459 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
460 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
461 package is now obsolete.
464 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
467 The build scripts are in the subdirectory @file{debian/}; you can
468 make the .deb by doing, for example:
472 # dpkg --purge lilypond lilypond1.3
474 $ tar xzf lilypond-1.4.3.tar.gz
476 $ dch -p -v 1.4.3-0.local.1 "Local build."
479 # dpkg -i ../lilypond_1.4.3*.deb
484 Use command @command{debuild} instead of @command{debuild -B} if you have
485 a very fast machine and want to build the HTML, PS and DVI documentation
488 For compilation on a Debian GNU/Linux system you need these packages,
489 in addition to the those needed for running:
492 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
493 @item libguile<@var{your-libguile-version-here}>-dev
494 @item make, m4, flex, bison
497 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
498 @item dpkg-dev, debhelper, fakeroot
500 @item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
501 in Debian testing/unstable.)
504 Most of these are listed on the @samp{Build-Depends} line in the
505 @file{debian/control} file. To ensure the creation of the lilypond deb is
506 trouble-free, we recommend that you first install the following packages
507 by running \@command{apt-get} as root before building the package:
512 apt-get install task-debian-devel task-c++-dev \
513 python-base libguile6-dev tetex-bin tetex-dev \
514 tetex-extra flex bison texinfo groff gs \
515 netpbm pnmtopng m4 gettext
518 For Debian in development ("unstable", the future 2.3 or 3.0):
521 apt-get install binutils cpp gcc libc6-dev \
522 g++ libstdc++2.10-dev \
523 python-base libguile-dev tetex-bin libkpathsea-dev \
524 tetex-extra flex bison texinfo groff gs \
528 And, just so that old fonts from previous versions of LilyPond won't
529 interfere with your build, you may want to do this before the build too:
532 dpkg --purge lilypond lilypond1.3
537 LilyPond is available through fink, in the unstable cvs distribution.
541 @item Get the Fink package manager from @uref{http://fink.sourceforge.net}
542 @item Get the Lilypond package description by enabling the "unstable" tree
543 in fink and executing @command{fink selfupdate-cvs}.
549 fink install lilypond-unstable
553 That's it! The command should compile and install all LilyPond
554 prerequisites (python, TeX, X11, ghostscript) and then LilyPond
558 @subsection compiling on MacOS X
559 LilyPond has been built on Darwin, to be precise, on:
561 Darwin buoux.aspiratie.nl 5.3 Darwin Kernel Version 5.3: Thu Jan 24
562 22:06:02 PST 2002; root:xnu/xnu-201.19.obj~1/RELEASE_PPC Power Macintosh powerpc
568 Apple Computer, Inc. version gcc-932.1, based on gcc version 2.95.2 19991024 (release)
571 To make sure you have all packages needed to build LilyPond installed,
575 apt-get install bash python guile debianutils flex bison texinfo \
576 ghostscript6 netpbm m4 gettext
585 For more information about @file{apt-get} and @file{fink}, see
586 @uref{http://fink.sf.net,fink.sourceforge.net}.
588 @c brokenness of autoconf; don't ask
589 Then, configure, patch, make and install LilyPond using these commands:
592 CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
593 ./configure --prefix=/sw
594 make -C lily out/parser.hh out/parser.cc out/config.h
595 patch -p0 < darwin.patch
596 make -C lily out/parser.o
597 make DEPENDENCIES_OUTPUT=/dev/null all
601 For installing, you must be root, of course.
603 @c Why isn't this in BUGS (where it belongs?)
606 For help and questions use @email{lilypond-user@@gnu.org}. Please
607 consult the FAQ before mailing your problems. If you find bugs, please
608 send bug reports to @email{bug-lilypond@@gnu.org}.
610 Bugs that are not fault of LilyPond are documented here.
612 @subsection Linking to kpathsea
614 If kpathsea and the corresponding header files are installed in some
615 directory where GCC does not search by default, for example in
616 @file{/usr/local/lib/} and @file{/usr/local/include/} respectively,
617 you have to explicitly tell configure where to find it. To do this,
620 @item @code{rm config.cache}
621 @item @code{export LDFLAGS=-L/usr/share/texmf/lib}
622 @item @code{export CPPFLAGS=-I/usr/share/texmf/include}
623 @item @code{./configure}
625 Once configure has found them, the paths are stored in
626 @file{config.make} and will be used even if you don't have the
627 environment variables set during make.
630 @unnumberedsubsec Gcc-3.0.4
632 Gcc 3.0.4, is a bit flaky. Try downgrading to 2.95.x, or if you're
633 adventurous (see below), upgrading to 3.1.x.
635 @unnumberedsubsec Flex-2.5.4a and gcc-3.x
637 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
638 LilyPond with gcc-3.0 you may do:
641 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
642 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
643 patch -p1 < lexer-gcc-3.0.patch
644 make conf=gcc-3.0 -C lily
647 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
649 @unnumberedsubsec Flex-2.5.4a and gcc-3.1.x
651 Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code. To compile
652 LilyPond with gcc-3.1.1 you may do:
655 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
656 CPPFLAGS=$(pwd)/lily/out-gcc-3.1 CC=gcc-3.1 CXX=g++-3.1 \
657 ./configure --enable-config=gcc-3.1
658 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
662 Note that this is @strong{not} fixed in Debian/unstable for flex <=
665 @unnumberedsubsec Linux-2.4.0, Guile-1.4 --with-threads
667 There's a bug in certain kernels around version 2.4.0, that is
668 triggered when using Guile 1.4 compiled with pthreads. You'll see
669 random segmentation fault crashes of LilyPond. Upgrade to a newer
670 version of Linux. If you can't do that, you may try to recompiling
671 Guile without threads (YMMV):
674 guile-1.4$ ./configure --without-threads; make all install
678 @unnumberedsubsec NetBSD
681 @item The flex precompiled in NetBSD-1.4.2 is broken.
682 Download flex-2.5.4a, build, install.
684 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
685 release)) does not include @file{/usr/pkg} paths. Configure using:
688 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
694 @unnumberedsubsec Solaris:
697 @item Sparc64/Solaris 2.6, GNU make-3.77
699 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
701 @item Sparc64/Solaris 2.6, ld
707 @unnumberedsubsec AIX
712 The following is from the gcc install/SPECIFIC file.
714 Some versions of the AIX binder (linker) can fail with a relocation
715 overflow severe error when the -bbigtoc option is used to link
716 GCC-produced object files into an executable that overflows the TOC.
717 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
718 -BBIGTOC) is available from IBM Customer Support and from its
719 27service.boulder.ibm.com website as PTF U455193.
721 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
722 as and GNU ld will not work properly and one should not configure GCC
723 to use those GNU utilities. Use the native AIX tools which do
724 interoperate with GCC.
727 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
729 LDFLAGS='-Wl,-bbigtoc' ./configure