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 is
19 also known to run and compile on Windows NT/95/98 as well. More
20 information on this topic can be found at the
21 @uref{http://www.lilypond.org/gnu-windows/, LilyPond on Windows page}.
25 <a name="download-source">
30 Even numbered versions are `stable'. The webpages for the stable version
31 (1.2) reside @uref{http://www.gnu.org/software/lilypond, on the GNU
32 servers}. Big enhancements go into the latest odd numbered version
33 (1.3), 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.
51 Of course, if your platform supports LilyPond, such as Debian GNU/Linux,
52 FreeBSD, OpenBSD or NetBSD, you're encouraged to use the native build
55 For Red Hat Linux and SuSE Linux, @file{.spec} files are included in the
56 tarball; see instructions below.
59 <a name="download-binaries">
64 @subsection Precompiled binaries
66 If you want to track bleeding edge development, try:
69 @item @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond/, Debian
70 GNU/Linux} usually has the latest binaries for the most useful stable
71 and development versions, while
72 @item @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/,
73 Mandrake Cooker} also provides fairly recent versions.
76 Binaries are made available for other popular platforms, but as we need
77 to compile them ourselves, they are not updated for every version
81 @item @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/, Red Hat i386}
82 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE, SuSE}
83 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/,
86 @uref{http://www.lilypond.org/gnu-windows/, Windows}
91 There are two options for upgrading sources.
94 @item if you have an unpacked source tree of a previous version, you
97 @emph{If you upgrade by patching do remember to rerun autoconf after
100 @item if you have the @code{.tar.gz} file of a previous release, you can
102 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
103 This is much safer than using patches, and is the recommended way.
105 The following command produces @file{lilypond-1.4.3.tar.gz} from
106 @file{lilypond-1.4.2.tar.gz} identical (up to compression dates) to the .3
109 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
113 @section Requirements
115 @subsection Compilation
117 You need the following packages to compile Lilypond.
120 @item The GNU c++ compiler (version 2.95.2 or newer).
121 EGCS 1.1 may work, but is no longer supported.
122 Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
124 WARNING: if you choose to upgrade to GCC 3.x, enquire if your
125 distribution supports g++ 3.x and flex.
127 @item Python (version 1.5 or newer).
128 Check out @uref{http://www.python.org, the python website}.
130 @item GUILE (version 1.4 or newer).
131 GUILE-1.3.4 may work but is no longer supported.
133 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
137 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
140 @item Flex (version 2.5.4a or newer).
141 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
143 WARNING: plain Flex 2.5.4(a) generates invalid C++ code. GCC 3.x
144 chokes on this. If you wish to use GCC 3.x, make sure that your
145 distribution supports g++ 3.x and flex. For a workaround, see
148 @item Bison (version 1.25 or newer).
149 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}
153 @TeX{} is used as an output backend.
155 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf}, @file{.afm}, @file{.tfm}).
156 Make sure you have tetex 1.0 or newer (1.0.6 is known to work). You may
157 need to install a tetex-devel or tetex-dev package too.
159 @item Texinfo (version 4.2 or newer).
160 The documentation of lily is written in texinfo. Check out
161 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
163 @item The geometry package for LaTeX is needed to use ly2dvi.
165 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
166 FTP directory for @code{geometry}}. This package is normally included
167 with the @TeX{} distribution.
169 @item kpathsea, a library for searching (@TeX{}) files. @code{kpathsea} is
170 usually included with your installation of @TeX{}. You may need to install
171 a tetex-devel or tetex-dev package too. If kpathsea is not installed in
172 a directory where the compiler normally looks, read the hints for
175 In the very unlikely case that kpathsea is not available for your
176 platform (ie, you're not running GNU/Linux, Windows, or any recent
177 UNIX), you can compile LilyPond without kpathsea support. In that case,
178 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
179 configure something like:
182 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
187 @subsection Running requirements
189 GNU LilyPond does use a lot of resources. For operation you need the
194 @item Xdvi and Ghostscript
195 @item GUILE 1.4, or newer. Check out
196 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
199 For running LilyPond successfully you have to help @TeX{} and MetaFont find
200 various files. The recommended way of doing so is adjusting the
201 environment variables in the start-up scripts of your shell. Appropriate
202 Csh and bourne sh scripts are left in
203 @file{buildscripts/out/lilypond-profile} and
204 @file{buildscripts/out/lilypond-login} after compilation.
206 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
207 recommended for comfortable use.
209 @subsection Website requirements
211 The documentation comes in the form of a website. You can view this
212 website on the internet, but you can also build it locally. This process
213 requires a successful compile of lilypond. The website is built
221 Building the website requires some additional tools:
224 @item The netpbm utilities, see @uref{http://netpbm.sourceforge.net/}
225 @item pktrace 1.0 or newer, needed for generating PostScript Type1
226 fonts. Get it from @uref{http://www.cs.uu.nl/~hanwen/pktrace/}. You
227 will need to install some additional packages to get pktrace to work.
230 @section Building LilyPond
232 to install GNU LilyPond, type:
234 gunzip -c lilypond-x.y.z | tar xf -
236 ./configure # run with --help to see appropriate options
239 sh buildscripts/clean-fonts.sh
242 If you are doing an upgrade, you should remove all @file{feta}
243 @code{.pk} and @file{.tfm} files. A script has been provided to do the
244 work for you, see @file{buildscripts/clean-fonts.sh}.
247 If you are not root, you should choose a @code{--prefix} argument that
248 points into your home directory, eg.
251 ./configure --prefix=$HOME/usr
255 In this case, you have to insert the contents of
256 @code{buildscripts/out/lilypond-login} or
257 @code{buildscripts/out/lilypond-profile} into your start up scripts by
262 @subsection Configuring for multiple platforms
264 If you want to build multiple versions of LilyPond with different
265 configuration settings, you can use the @code{--enable-config=CONF}
266 option of configure. You should use @samp{make conf=CONF} to generate
267 the output in @file{out-CONF}. Example: suppose I want to build with
268 and without profiling. Then I'd use the following for the normal build,
271 ./configure --prefix=~ --enable-checking
276 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
292 An Emacs mode for entering music and running LilyPond is included with
293 the source archive as @file{lilypond-mode.el},
294 @file{lilypond-indent.el} and @file{lilypond-font-lock.el}. You
295 should install these files somewhere in your @var{load-path}. If you
296 have installed a precompiled LilyPond package, these files can be
297 found in @file{/usr/share/doc/lilypond-x.y.z/}.
299 Add this to your @file{~/.emacs} or @file{~/.emacs.el}, or install this
300 file in Emacs' @file{site-start.d}:
303 ;;; lilypond-init.el --- Startup code for LilyPond mode
305 (autoload 'LilyPond-mode "lilypond-mode")
306 (setq auto-mode-alist
307 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
309 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
313 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode is
314 automatically loaded, you not even need to modify your @code{~/.emacs}
317 @section Compiling for distributions
319 @subsection Red Hat Linux
321 Red Hat 7.x i386 RPMS are available from
322 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
324 You can also compile them yourself. A spec file is in
325 @file{make/out/lilypond.redhat.spec}. This file is distributed along
326 with the sources. You can make the rpm by issuing
329 tar xfz lilypond-x.y.z.tar.gz
330 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
331 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
335 For running on a Red Hat system you need these packages: guile, tetex,
336 tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
338 For compilation on a Red Hat system you need these packages, in
339 addition to the those needed for running: glibc-devel, gcc-c++,
340 libstdc++-devel, guile-devel, flex, bison, texinfo, groff, pktrace,
341 netpbm-progs, autotrace, t1utils.
348 Some LinuxPPC RPMS should available from
349 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
351 A LinuxPPC RPM can be made using the @file{lilypond.redhat.spec} file.
355 Some SUSE RPMS should available from
356 @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.
358 You can also compile a RPM for SUSE yourself. A spec file is in
359 @file{make/out/lilypond.suse.spec}, see the instructions for building
362 You must have the following packages: guile tcsh tetex te_latex te_kpath
363 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
364 gs_serv gs_lib gs_fonts guile
366 @subsection Slackware
368 No precompiled packages for Slackware are available.
370 Problems have been reported with Slackware 7.0; apparently, it ships
371 with a faulty compiler. Do not compile LilyPond with -O2 on this
374 At least on Slackware 8.0, you have to manually specify the paths to the
375 Kpathsea library, using
377 @item @code{rm config.cache}
378 @item @code{export LDFLAGS=-L/usr/share/texmf/lib}
379 @item @code{export CPPFLAGS=-I/usr/share/texmf/include}
380 @item @code{./configure}
386 Some binaries are available at rpmfind.net. Refer to
387 @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.
389 You can also compile a RPM for Mandrake yourself. A spec file is in
390 @file{make/out/lilypond.mandrake.spec}, see the instructions for building
393 @subsection Debian GNU/Linux
395 A Debian package is also available. You may install it easily by running
396 @command{apt-get} as root:
399 apt-get install lilypond lilypond-doc
402 You can also compile the .deb for Debian yourself, do:
405 apt-get -b source lilypond
408 If you're real impatient, you may even do:
411 cd lilypond-x.y.z # a previous version
412 uscan # download and build latest directly from upstream
416 Debian's @TeX{} installation is a bit short on memory, you may want to
417 increase it like this:
419 --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
420 +++ texmf.cnf Sun Dec 16 23:46:34 2001
422 main_memory.context = 1500000
423 main_memory.mpost = 1000000
424 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
425 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
426 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
427 +extra_mem_top = 1000000 % extra high memory for chars, tokens, etc.
428 +extra_mem_bot = 1000000 % extra low memory for boxes, glue, breakpoints, etc.
430 obj_tab_size.context = 300000
433 % Max number of characters in all strings, including all error messages,
434 % help texts, font names, control sequences. These values apply to TeX and MP.
435 pool_size.context = 750000
438 % Minimum pool space after TeX/MP's own strings; must be at least
439 % 25000 less than pool_size, but doesn't need to be nearly that large.
440 string_vacancies.context = 45000
443 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
444 environment variables if you do not want to or cannot modify
445 @file{/etc/texmf/texmf.cnf}.
450 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
451 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
452 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
453 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
454 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
455 package is now obsolete.
458 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
461 The build scripts are in the subdirectory @file{debian/}; you can
462 make the .deb by doing, for example:
466 # dpkg --purge lilypond lilypond1.3
468 $ tar xzf lilypond-1.4.3.tar.gz
470 $ dch -p -v 1.4.3-0.local.1 "Local build."
473 # dpkg -i ../lilypond_1.4.3*.deb
478 Use command @command{debuild} instead of @command{debuild -B} if you have
479 a very fast machine and want to build the HTML, PS and DVI documentation
482 For compilation on a Debian GNU/Linux system you need these packages,
483 in addition to the those needed for running:
486 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
487 @item libguile<@var{your-libguile-version-here}>-dev
488 @item make, m4, flex, bison
491 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
492 @item dpkg-dev, debhelper, fakeroot
494 @item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
495 in Debian testing/unstable.)
498 Most of these are listed on the @samp{Build-Depends} line in the
499 @file{debian/control} file. To ensure the creation of the lilypond deb is
500 trouble-free, we recommend that you first install the following packages
501 by running \@command{apt-get} as root before building the package:
506 apt-get install task-debian-devel task-c++-dev \
507 python-base libguile6-dev tetex-bin tetex-dev \
508 tetex-extra flex bison texinfo groff gs \
509 netpbm pnmtopng m4 gettext
512 For Debian in development ("unstable", the future 2.3 or 3.0):
515 apt-get install binutils cpp gcc libc6-dev \
516 g++ libstdc++2.10-dev \
517 python-base libguile-dev tetex-bin libkpathsea-dev \
518 tetex-extra flex bison texinfo groff gs \
522 And, just so that old fonts from previous versions of LilyPond won't
523 interfere with your build, you may want to do this before the build too:
526 dpkg --purge lilypond lilypond1.3
531 LilyPond is available through fink, in the unstable cvs distribution.
535 @item Get the Fink package manager from @uref{http://fink.sourceforge.net}
536 @item Get the Lilypond package description by enabling the "unstable" tree
537 in fink and executing @command{fink selfupdate-cvs}.
543 fink install lilypond-unstable
547 That's it! The command should compile and install all LilyPond
548 prerequisites (python, TeX, X11, ghostscript) and then LilyPond
552 @subsubsection compiling on MacOS X
553 LilyPond has been built on Darwin, to be precise, on:
555 Darwin buoux.aspiratie.nl 5.3 Darwin Kernel Version 5.3: Thu Jan 24
556 22:06:02 PST 2002; root:xnu/xnu-201.19.obj~1/RELEASE_PPC Power Macintosh powerpc
562 Apple Computer, Inc. version gcc-932.1, based on gcc version 2.95.2 19991024 (release)
565 To make sure you have all packages needed to build LilyPond installed,
569 apt-get install bash python guile debianutils flex bison texinfo \
570 ghostscript6 netpbm m4 gettext
579 For more information about @file{apt-get} and @file{fink}, see
580 @uref{http://fink.sf.net,fink.sourceforge.net}.
582 @c brokenness of autoconf; don't ask
583 Then, configure, patch, make and install LilyPond using these commands:
586 CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
587 ./configure --prefix=/sw
588 make -C lily out/parser.hh out/parser.cc out/config.h
589 patch -p0 < darwin.patch
590 make -C lily out/parser.o
591 make DEPENDENCIES_OUTPUT=/dev/null all
595 For installing, you must be root, of course.
597 @c Why isn't this in BUGS (where it belongs?)
600 For help and questions use @email{lilypond-user@@gnu.org}. Please
601 consult the FAQ before mailing your problems. If you find bugs, please
602 send bug reports to @email{bug-lilypond@@gnu.org}.
604 Bugs that are not fault of LilyPond are documented here.
606 @unnumberedsubsec FLex-2.5.4a and gcc-3.0
608 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
609 LilyPond with gcc-3.0 you may do:
612 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
613 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
614 patch -p1 < lexer-gcc-3.0.patch
615 make conf=gcc-3.0 -C lily
618 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
620 @unnumberedsubsec Linux-2.4.0, Guile-1.4 --with-threads
622 There's a bug in certain kernels around version 2.4.0, that is
623 triggered when using Guile 1.4 compiled with pthreads. You'll see
624 random segmentation fault crashes of LilyPond. Upgrade to a newer
625 version of Linux. If you can't do that, you may try to recompiling
626 Guile without threads (YMMV):
629 guile-1.4$ ./configure --without-threads; make all install
633 @unnumberedsubsec NetBSD
636 @item The flex precompiled in NetBSD-1.4.2 is broken.
637 Download flex-2.5.4a, build, install.
639 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
640 release)) does not include @file{/usr/pkg} paths. Configure using:
643 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
649 @unnumberedsubsec Solaris:
652 @item Sparc64/Solaris 2.6, GNU make-3.77
654 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
656 @item Sparc64/Solaris 2.6, ld
662 @unnumberedsubsec AIX
667 The following is from the gcc install/SPECIFIC file.
669 Some versions of the AIX binder (linker) can fail with a relocation
670 overflow severe error when the -bbigtoc option is used to link
671 GCC-produced object files into an executable that overflows the TOC.
672 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
673 -BBIGTOC) is available from IBM Customer Support and from its
674 27service.boulder.ibm.com website as PTF U455193.
676 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
677 as and GNU ld will not work properly and one should not configure GCC
678 to use those GNU utilities. Use the native AIX tools which do
679 interoperate with GCC.
682 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
684 LDFLAGS='-Wl,-bbigtoc' ./configure