1 \input texinfo @c -*-texinfo-*-
2 @setfilename INSTALL.info
3 @settitle INSTALL - compiling and installing GNU LilyPond
6 <!--- @@WEB-TITLE@@=Installation Instructions --->
14 @chapter INSTALL - compiling and installing GNU LilyPond
17 This document describes how to build LilyPond on Unix platforms. It is
18 also known to run and compile on Windows NT/95/98 as well. More
19 information on this topic can be found at the
20 @uref{http://www.lilypond.org/gnu-windows/, LilyPond on Windows page}.
24 <a name="download-source">
29 Even numbered versions are `stable'. The webpages for the stable version
30 (1.2) reside @uref{http://www.gnu.org/software/lilypond, on the GNU
31 servers}. Big enhancements go into the latest odd numbered version
32 (1.3), whose webpages are on @uref{http://www.lilypond.org/,the lilypond
35 @subsection Source code
37 If you want to compile LilyPond from source, download here:
39 @item Download development releases from
40 @c Hmm, these won't show up in lilypond.org/stats
41 @c Otoh, lilypond.org is not updated when release mail arrives
42 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/} by FTP and
43 @uref{http://ftp.cs.uu.nl/pub/GNU/LilyPond/}, by HTTP.
44 @item @uref{ftp://sca.uwaterloo.ca/pub/} by FTP (Canadian mirror)
45 @item at @code{lilypond.org}
46 @uref{ftp://ftp.lilypond.org/pub/LilyPond/} by FTP and
47 @uref{http://www.lilypond.org/ftp/} by HTTP.
50 Of course, if your platform supports LilyPond, such as Debian GNU/Linux,
51 FreeBSD, OpenBSD or NetBSD, you're encouraged to use the native build
54 For Red Hat Linux and SuSE Linux, @file{.spec} files are included in the
55 tarball; see instructions below.
58 <a name="download-binaries">
63 @subsection Precompiled binaries
65 If you want to track bleeding edge development, try:
68 @item @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond/, Debian
69 GNU/Linux} usually has the latest binaries for the most useful stable
70 and development versions, while
71 @item @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/,
72 Mandrake Cooker} also provides fairly recent versions.
75 Binaries are made available for other popular platforms, but as we need
76 to compile them ourselves, they are not updated for every version
80 @item @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/, Red Hat i386}
81 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE, SuSE}
82 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/,
85 @uref{http://www.lilypond.org/gnu-windows/, Windows}
90 There are two options for upgrading sources.
93 @item if you have an unpacked source tree of a previous version, you
96 @emph{If you upgrade by patching do remember to rerun autoconf after
99 @item if you have the @code{.tar.gz} file of a previous release, you can
101 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
102 This is much safer than using patches, and is the recommended way.
104 The following command produces @file{lilypond-1.4.3.tar.gz} from
105 @file{lilypond-1.4.2.tar.gz} identical (up to compression dates) to the .3
108 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
112 @section Requirements
114 @subsection Compilation
116 You need the following packages to compile Lilypond.
119 @item A reasonably new C++ compiler: EGCS 1.1, GCC 2.95.2 or
120 newer. Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
123 Check out @uref{http://www.python.org, the python website}.
125 @item GUILE 1.3.4 or newer, check out
126 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
127 Version 1.4 is recommended for better performance.
131 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
134 @item Flex (version 2.5.4a or newer).
135 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
137 @item Bison (version 1.25 or newer).
138 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}
142 @TeX{} is used as an output backend.
144 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf}, @file{.afm}, @file{.tfm}).
145 Make sure you have tetex 1.0 or newer (1.0.6 is known to work). You may
146 need to install a tetex-devel or tetex-dev package too.
148 @item Texinfo (version 4.0 or newer).
149 The documentation of lily is written in texinfo. Check out
150 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
152 @item The geometry package for LaTeX is needed to use ly2dvi.
154 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
155 FTP directory for @code{geometry}}. This package is normally included
156 with the @TeX{} distribution.
158 @item kpathsea, a library for searching (@TeX{}) files. @code{kpathsea} is
159 usually included with your installation of @TeX{}. You may need to install
160 a tetex-devel or tetex-dev package too.
162 In the very unlikely case that kpathsea is not available for your
163 platform (ie, you're not running GNU/Linux, Windows, or any recent
164 UNIX), you can compile LilyPond without kpathsea support. In that case,
165 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
166 configure something like:
169 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
173 @item pktrace, [OPTIONAL], needed for generating PostScript Type1
175 @uref{http://www.cs.uu.nl/~hanwen/public/software/pktrace-0.1.tar.gz}
177 @item autotrace-0.27a, [OPTIONAL], needed for generating PostScript Type1
178 fonts. You must apply the patch included pktrace-0.1 first.
179 @uref{http://autotrace.sourceforge.net}.
181 @item MetaPost [OPTIONAL] needed for generating PostScript Type3 fonts. Please
182 note that tetex-0.4pl8 (included with Red Hat 5.x) does not include
183 @file{mfplain.mp}, which is needed for producing the scalable font
186 If you don't have MetaPost and don't want to use PostScript output, then
187 edit @file{mf/GNUmakefile}, removing the line saying @code{PFA_FILES=}.
193 @subsection Running requirements
195 GNU LilyPond does use a lot of resources. For operation you need the
200 @item Xdvi and Ghostscript
201 @item GUILE 1.3.4, or newer. Check out
202 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
205 For running LilyPond successfully you have to help @TeX{} and MetaFont find
206 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 @file{buildscripts/out/lilypond-profile} and
210 @file{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.
215 @subsection Website requirements
217 The documentation comes in the form of a website. You can view this
218 website on the internet, but you can also build it locally. This process
219 requires a successful compile of lilypond. The website is built
227 Building the website requires some additional tools:
230 @item xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
232 @uref{ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz,the
235 @item pnmtopng. The original is
237 @uref{ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz,in
238 the pnmtopng FTP site}.
240 @item @uref{http://www.lri.fr/~filliatr/ftp/bibtex2html/, Bibtex2html}, or
241 @uref{http://www.uni-koblenz.de/ag-ki/ftp/bib2html/, Bib2html}.
242 Bibtex2html is available in debian, while bib2html is in some rpm based
244 Bib2html, in turn depends on man2html for proper installation.
245 man2html can be had from @uref{http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05,http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05}.
247 The website will build without bib converter utility, but you will not
248 see our hypertextified bibliography.
250 @item texinfo (a development release)
251 The documentation will build with texinfo-4.0, but if you want split
252 html pages, you're best off using the lates pretest version from
253 @uref{ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz,
255 @uref{ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz,texinfo-4.0b}
258 @section Building LilyPond
260 to install GNU LilyPond, type:
262 gunzip -c lilypond-x.y.z | tar xf -
264 ./configure # run with --help to see appropriate options
267 sh buildscripts/clean-fonts.sh
270 If you are doing an upgrade, you should remove all @file{feta}
271 @code{.pk} and @file{.tfm} files. A script has been provided to do the
272 work for you, see @file{buildscripts/clean-fonts.sh}.
275 If you are not root, you should choose a @code{--prefix} argument that
276 points into your home directory, eg.
279 ./configure --prefix=$HOME/usr
283 In this case, you have to insert the contents of
284 @code{buildscripts/out/lilypond-login} or
285 @code{buildscripts/out/lilypond-profile} into your start up scripts by
290 @subsection Configuring for multiple platforms
292 If you want to build multiple versions of LilyPond with different
293 configuration settings, you can use the @code{--enable-config=CONF}
294 option of configure. You should use @samp{make conf=CONF} to generate
295 the output in @file{out-CONF}. Example: suppose I want to build with
296 and without profiling. Then I'd use the following for the normal build,
299 ./configure --prefix=~ --enable-checking
304 and for the profiling version, I specify a different configuration.
308 ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
310 make conf=prof install
320 An Emacs mode for entering music and running LilyPond is included with
321 the source archive as @file{lilypond-mode.el} and
322 @file{lilypond-font-lock.el}. You should install these files somewhere
323 in your @var{load-path}. If you have installed a precompiled LilyPond
324 package, these files can be found in
325 @file{/usr/share/doc/lilypond-x.y.z/}.
327 Add this to your @file{~/.emacs} or @file{~/.emacs.el}, or install this
328 file in Emacs' @file{site-start.d}:
330 ;;; lilypond-init.el --- Startup code for LilyPond mode
332 (load-library "lilypond-mode.el")
333 (setq auto-mode-alist
334 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
335 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
338 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode is
339 automatically loaded, you not even need to modify your @code{~/.emacs}
342 @section Compiling for distributions
344 @subsection Red Hat Linux
346 Red Hat 7.0 i386 RPMS are available from
347 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
349 You can also compile them yourself. A spec file is in
350 @file{make/out/lilypond.redhat.spec}. This file is distributed along
351 with the sources. You can make the rpm by issuing
354 tar xfz lilypond-x.y.z.tar.gz
355 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
356 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
360 For running on a Red Hat system you need these packages: guile, tetex,
361 tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
363 For compilation on a Red Hat system you need these packages, in addition
364 to the those needed for running: glibc-devel, gcc-c++, libstdc++-devel,
365 guile-devel, flex, bison, texinfo, tetex-devel, groff,
372 Some LinuxPPC RPMS should available from
373 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
375 A LinuxPPC RPM can be made using the @file{lilypond.redhat.spec} file.
379 Some SUSE RPMS should available from
380 @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.
382 You can also compile a RPM for SUSE yourself. A spec file is in
383 @file{make/out/lilypond.suse.spec}, see the instructions for building
386 You must have the following packages: guile tcsh tetex te_latex te_kpath
387 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
388 gs_serv gs_lib gs_fonts guile
390 @subsection Slackware
392 No precompiled packages for Slackware are available.
394 Problems have been reported with Slackware 7.0; apparently, it ships
395 with a faulty compiler. Do not compile LilyPond with -O2 on this
400 Some binaries are available at rpmfind.net. Refer to
401 @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.
403 You can also compile a RPM for Mandrake yourself. A spec file is in
404 @file{make/out/lilypond.mandrake.spec}, see the instructions for building
407 @subsection Debian GNU/Linux
409 A Debian package is also available. You may install it easily by running
410 @command{apt-get} as root:
413 apt-get install lilypond lilypond-doc
416 You can also compile the .deb for Debian yourself, do:
419 apt-get -b source lilypond
422 If you're real impatient, you may even do:
425 cd lilypond-x.y.z # a previous version
426 uscan # download and build latest directly from upstream
430 Debian's @TeX{} installation is a bit short on memory, you may want to
431 increase it like this:
433 --- /etc/texmf/texmf.cnf.dpkg Sun Jan 28 14:12:14 2001
434 +++ /etc/texmf/texmf.cnf Fri Apr 27 11:09:35 2001
436 main_memory.context = 1500000
437 main_memory.mpost = 1000000
438 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
439 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
440 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
441 +extra_mem_top = 100000 % extra high memory for chars, tokens, etc.
442 +extra_mem_bot = 100000 % extra low memory for boxes, glue, breakpoints, etc.
444 obj_tab_size.context = 256000
448 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
449 environment variables if you do not want to or cannot modify
450 @file{/etc/texmf/texmf.cnf}.
455 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
456 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
457 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
458 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
459 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
460 package is now obsolete.
463 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
466 The build scripts are in the subdirectory @file{debian/}; you can
467 make the .deb by doing, for example:
471 # dpkg --purge lilypond lilypond1.3
473 $ tar xzf lilypond-1.4.3.tar.gz
475 $ dch -p -v 1.4.3-0.local.1 "Local build."
478 # dpkg -i ../lilypond_1.4.3*.deb
483 Use command @command{debuild} instead of @command{debuild -B} if you have
484 a very fast machine and want to build the HTML, PS and DVI documentation
487 For compilation on a Debian GNU/Linux system you need these packages,
488 in addition to the those needed for running:
491 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
492 @item libguile<@var{your-libguile-version-here}>-dev
493 @item make, m4, flex, bison
496 @item bibtex2html (not in Debian 2.2)
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 bibtex2html 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
536 @c Why isn't this in BUGS (where it belongs?)
539 For help and questions use @email{lilypond-user@@gnu.org}. Please
540 consult the FAQ before mailing your problems. If you find bugs, please
541 send bug reports to @email{bug-lilypond@@gnu.org}.
543 Bugs that are not fault of LilyPond are documented here.
545 @unnumberedsubsec FLex-2.5.4a and gcc-3.0
547 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
548 LilyPond with gcc-3.0 you may do:
552 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
553 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
554 patch -p1 < lexer-gcc-3.0.patch
555 make conf=gcc-3.0 -C lily
558 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
560 @unnumberedsubsec Linux-2.4.0, Guile-1.4 --with-threads
562 There's a bug in certain kernels around version 2.4.0, that is
563 triggered when using Guile 1.4 compiled with pthreads. You'll see
564 random segmentation fault craches of LilyPond. Upgrade to a newer
565 version of Linux. If you can't do that, you may try to recompiling
566 Guile without threads (YMMV):
569 guile-1.4$ ./configure --without-threads; make all install
572 @unnumberedsubsec NetBSD
575 @item The flex precompiled in NetBSD-1.4.2 is broken.
576 Download flex-2.5.4a, build, install.
578 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
579 release)) does not include @file{/usr/pkg} paths. Configure using:
582 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
588 @unnumberedsubsec Solaris:
591 @item Sparc64/Solaris 2.6, GNU make-3.77
593 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
595 @item Sparc64/Solaris 2.6, ld
601 @unnumberedsubsec AIX
606 The following is from the gcc install/SPECIFIC file.
608 Some versions of the AIX binder (linker) can fail with a relocation
609 overflow severe error when the -bbigtoc option is used to link
610 GCC-produced object files into an executable that overflows the TOC.
611 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
612 -BBIGTOC) is available from IBM Customer Support and from its
613 27service.boulder.ibm.com website as PTF U455193.
615 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
616 as and GNU ld will not work properly and one should not configure GCC
617 to use those GNU utilities. Use the native AIX tools which do
618 interoperate with GCC.
621 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
623 LDFLAGS='-Wl,-bbigtoc' ./configure