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 version of the GNU C++ compiler: EGCS 1.1, GCC 2.95.2 or
120 newer. Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
122 @item Python (version 1.5 or newer).
123 Check out @uref{http://www.python.org, the python website}.
125 @item GUILE (version 1.4 or newer).
127 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
128 Version 1.4 is recommended for better performance.
132 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
135 @item Flex (version 2.5.4a or newer).
136 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
138 @item Bison (version 1.25 or newer).
139 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}
143 @TeX{} is used as an output backend.
145 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf}, @file{.afm}, @file{.tfm}).
146 Make sure you have tetex 1.0 or newer (1.0.6 is known to work). You may
147 need to install a tetex-devel or tetex-dev package too.
149 @item Texinfo (version 4.0 or newer).
150 The documentation of lily is written in texinfo. Check out
151 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
153 @item The geometry package for LaTeX is needed to use ly2dvi.
155 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
156 FTP directory for @code{geometry}}. This package is normally included
157 with the @TeX{} distribution.
159 @item kpathsea, a library for searching (@TeX{}) files. @code{kpathsea} is
160 usually included with your installation of @TeX{}. You may need to install
161 a tetex-devel or tetex-dev package too.
163 In the very unlikely case that kpathsea is not available for your
164 platform (ie, you're not running GNU/Linux, Windows, or any recent
165 UNIX), you can compile LilyPond without kpathsea support. In that case,
166 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
167 configure something like:
170 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
174 @item pktrace, [OPTIONAL], needed for generating PostScript Type1
175 fonts. Get it from @uref{http://www.cs.uu.nl/~hanwen/pktrace/}. You
176 will need to install some additional packages to get pktrace to work.
180 @subsection Running requirements
182 GNU LilyPond does use a lot of resources. For operation you need the
187 @item Xdvi and Ghostscript
188 @item GUILE 1.3.4, or newer. Check out
189 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
192 For running LilyPond successfully you have to help @TeX{} and MetaFont find
193 various files. The recommended way of doing so is adjusting the
194 environment variables in the start-up scripts of your shell. Appropriate
195 Csh and bourne sh scripts are left in
196 @file{buildscripts/out/lilypond-profile} and
197 @file{buildscripts/out/lilypond-login} after compilation.
199 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
200 recommended for comfortable use.
202 @subsection Website requirements
204 The documentation comes in the form of a website. You can view this
205 website on the internet, but you can also build it locally. This process
206 requires a successful compile of lilypond. The website is built
214 Building the website requires some additional tools:
217 @item xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
219 @uref{ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz,the
222 @item pnmtopng. The original is
224 @uref{ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz,in
225 the pnmtopng FTP site}.
227 @item texinfo (a development release)
228 The documentation will build with texinfo-4.0, but if you want split
229 html pages, you're best off using the lates pretest version from
230 @uref{ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz,
232 @uref{ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz,texinfo-4.0b}
235 @section Building LilyPond
237 to install GNU LilyPond, type:
239 gunzip -c lilypond-x.y.z | tar xf -
241 ./configure # run with --help to see appropriate options
244 sh buildscripts/clean-fonts.sh
247 If you are doing an upgrade, you should remove all @file{feta}
248 @code{.pk} and @file{.tfm} files. A script has been provided to do the
249 work for you, see @file{buildscripts/clean-fonts.sh}.
252 If you are not root, you should choose a @code{--prefix} argument that
253 points into your home directory, eg.
256 ./configure --prefix=$HOME/usr
260 In this case, you have to insert the contents of
261 @code{buildscripts/out/lilypond-login} or
262 @code{buildscripts/out/lilypond-profile} into your start up scripts by
267 @subsection Configuring for multiple platforms
269 If you want to build multiple versions of LilyPond with different
270 configuration settings, you can use the @code{--enable-config=CONF}
271 option of configure. You should use @samp{make conf=CONF} to generate
272 the output in @file{out-CONF}. Example: suppose I want to build with
273 and without profiling. Then I'd use the following for the normal build,
276 ./configure --prefix=~ --enable-checking
281 and for the profiling version, I specify a different configuration.
285 ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
287 make conf=prof install
297 An Emacs mode for entering music and running LilyPond is included with
298 the source archive as @file{lilypond-mode.el} and
299 @file{lilypond-font-lock.el}. You should install these files somewhere
300 in your @var{load-path}. If you have installed a precompiled LilyPond
301 package, these files can be found in
302 @file{/usr/share/doc/lilypond-x.y.z/}.
304 Add this to your @file{~/.emacs} or @file{~/.emacs.el}, or install this
305 file in Emacs' @file{site-start.d}:
307 ;;; lilypond-init.el --- Startup code for LilyPond mode
309 (load-library "lilypond-mode.el")
310 (setq auto-mode-alist
311 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
312 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
315 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode is
316 automatically loaded, you not even need to modify your @code{~/.emacs}
319 @section Compiling for distributions
321 @subsection Red Hat Linux
323 Red Hat 7.0 i386 RPMS are available from
324 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
326 You can also compile them yourself. A spec file is in
327 @file{make/out/lilypond.redhat.spec}. This file is distributed along
328 with the sources. You can make the rpm by issuing
331 tar xfz lilypond-x.y.z.tar.gz
332 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
333 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
337 For running on a Red Hat system you need these packages: guile, tetex,
338 tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
340 For compilation on a Red Hat system you need these packages, in addition
341 to the those needed for running: glibc-devel, gcc-c++, libstdc++-devel,
342 guile-devel, flex, bison, texinfo, groff.
349 Some LinuxPPC RPMS should available from
350 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
352 A LinuxPPC RPM can be made using the @file{lilypond.redhat.spec} file.
356 Some SUSE RPMS should available from
357 @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.
359 You can also compile a RPM for SUSE yourself. A spec file is in
360 @file{make/out/lilypond.suse.spec}, see the instructions for building
363 You must have the following packages: guile tcsh tetex te_latex te_kpath
364 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
365 gs_serv gs_lib gs_fonts guile
367 @subsection Slackware
369 No precompiled packages for Slackware are available.
371 Problems have been reported with Slackware 7.0; apparently, it ships
372 with a faulty compiler. Do not compile LilyPond with -O2 on this
377 Some binaries are available at rpmfind.net. Refer to
378 @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.
380 You can also compile a RPM for Mandrake yourself. A spec file is in
381 @file{make/out/lilypond.mandrake.spec}, see the instructions for building
384 @subsection Debian GNU/Linux
386 A Debian package is also available. You may install it easily by running
387 @command{apt-get} as root:
390 apt-get install lilypond lilypond-doc
393 You can also compile the .deb for Debian yourself, do:
396 apt-get -b source lilypond
399 If you're real impatient, you may even do:
402 cd lilypond-x.y.z # a previous version
403 uscan # download and build latest directly from upstream
407 Debian's @TeX{} installation is a bit short on memory, you may want to
408 increase it like this:
410 --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
411 +++ texmf.cnf Sun Dec 16 23:46:34 2001
413 main_memory.context = 1500000
414 main_memory.mpost = 1000000
415 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
416 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
417 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
418 +extra_mem_top = 1000000 % extra high memory for chars, tokens, etc.
419 +extra_mem_bot = 1000000 % extra low memory for boxes, glue, breakpoints, etc.
421 obj_tab_size.context = 300000
424 % Max number of characters in all strings, including all error messages,
425 % help texts, font names, control sequences. These values apply to TeX and MP.
426 pool_size.context = 750000
429 % Minimum pool space after TeX/MP's own strings; must be at least
430 % 25000 less than pool_size, but doesn't need to be nearly that large.
431 string_vacancies.context = 45000
434 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
435 environment variables if you do not want to or cannot modify
436 @file{/etc/texmf/texmf.cnf}.
441 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
442 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
443 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
444 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
445 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
446 package is now obsolete.
449 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
452 The build scripts are in the subdirectory @file{debian/}; you can
453 make the .deb by doing, for example:
457 # dpkg --purge lilypond lilypond1.3
459 $ tar xzf lilypond-1.4.3.tar.gz
461 $ dch -p -v 1.4.3-0.local.1 "Local build."
464 # dpkg -i ../lilypond_1.4.3*.deb
469 Use command @command{debuild} instead of @command{debuild -B} if you have
470 a very fast machine and want to build the HTML, PS and DVI documentation
473 For compilation on a Debian GNU/Linux system you need these packages,
474 in addition to the those needed for running:
477 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
478 @item libguile<@var{your-libguile-version-here}>-dev
479 @item make, m4, flex, bison
482 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
483 @item dpkg-dev, debhelper, fakeroot
485 @item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
486 in Debian testing/unstable.)
489 Most of these are listed on the @samp{Build-Depends} line in the
490 @file{debian/control} file. To ensure the creation of the lilypond deb is
491 trouble-free, we recommend that you first install the following packages
492 by running \@command{apt-get} as root before building the package:
497 apt-get install task-debian-devel task-c++-dev \
498 python-base libguile6-dev tetex-bin tetex-dev \
499 tetex-extra flex bison texinfo groff gs \
500 netpbm pnmtopng m4 gettext
503 For Debian in development ("unstable", the future 2.3 or 3.0):
506 apt-get install binutils cpp gcc libc6-dev \
507 g++ libstdc++2.10-dev \
508 python-base libguile-dev tetex-bin libkpathsea-dev \
509 tetex-extra flex bison texinfo groff gs \
513 And, just so that old fonts from previous versions of LilyPond won't
514 interfere with your build, you may want to do this before the build too:
517 dpkg --purge lilypond lilypond1.3
521 @c Why isn't this in BUGS (where it belongs?)
524 For help and questions use @email{lilypond-user@@gnu.org}. Please
525 consult the FAQ before mailing your problems. If you find bugs, please
526 send bug reports to @email{bug-lilypond@@gnu.org}.
528 Bugs that are not fault of LilyPond are documented here.
530 @unnumberedsubsec FLex-2.5.4a and gcc-3.0
532 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
533 LilyPond with gcc-3.0 you may do:
536 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
537 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
538 patch -p1 < lexer-gcc-3.0.patch
539 make conf=gcc-3.0 -C lily
542 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
544 @unnumberedsubsec Python-2.1[.1]
546 Regular expressions are broken in Python 2.1.[.1], either upgrade or
549 @unnumberedsubsec Linux-2.4.0, Guile-1.4 --with-threads
551 There's a bug in certain kernels around version 2.4.0, that is
552 triggered when using Guile 1.4 compiled with pthreads. You'll see
553 random segmentation fault crashes of LilyPond. Upgrade to a newer
554 version of Linux. If you can't do that, you may try to recompiling
555 Guile without threads (YMMV):
558 guile-1.4$ ./configure --without-threads; make all install
562 @unnumberedsubsec NetBSD
565 @item The flex precompiled in NetBSD-1.4.2 is broken.
566 Download flex-2.5.4a, build, install.
568 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
569 release)) does not include @file{/usr/pkg} paths. Configure using:
572 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
578 @unnumberedsubsec Solaris:
581 @item Sparc64/Solaris 2.6, GNU make-3.77
583 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
585 @item Sparc64/Solaris 2.6, ld
591 @unnumberedsubsec AIX
596 The following is from the gcc install/SPECIFIC file.
598 Some versions of the AIX binder (linker) can fail with a relocation
599 overflow severe error when the -bbigtoc option is used to link
600 GCC-produced object files into an executable that overflows the TOC.
601 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
602 -BBIGTOC) is available from IBM Customer Support and from its
603 27service.boulder.ibm.com website as PTF U455193.
605 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
606 as and GNU ld will not work properly and one should not configure GCC
607 to use those GNU utilities. Use the native AIX tools which do
608 interoperate with GCC.
611 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
613 LDFLAGS='-Wl,-bbigtoc' ./configure