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 Of course, if your platform supports LilyPond, such as Debian GNU/Linux,
53 FreeBSD, OpenBSD or NetBSD, you're encouraged to use the native build
56 For Red Hat Linux and SuSE Linux, @file{.spec} files are included in the
57 tarball; see instructions below.
60 @subsubsection Anonymous CVS access
66 cvs -d :pserver:anoncvs@@lilypond.org:/home/lilypond login
67 cvs -d :pserver:anoncvs@@lilypond.org:/home/lilypond co -P lilypond
71 See @uref{http://lilypond.org/wiki/?CVS} for more information.
74 <a name="download-binaries">
79 @subsection Precompiled binaries
81 If you want to track bleeding edge development, try:
84 @item @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond/, Debian
85 GNU/Linux} usually has the latest binaries for the most useful stable
86 and development versions, while
87 @item @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/,
88 Mandrake Cooker} also provides fairly recent versions.
91 Binaries are made available for other popular platforms, but as we need
92 to compile them ourselves, they are not updated for every version
96 @item @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/, Red Hat i386}
97 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE, SuSE}
98 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/,
101 @uref{http://www.lilypond.org/gnu-windows/, Windows}
104 @subsection Upgrading
106 There are two options for upgrading sources.
109 @item if you have an unpacked source tree of a previous version, you
112 @emph{If you upgrade by patching do remember to rerun autoconf after
115 @item if you have the @code{.tar.gz} file of a previous release, you can
117 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
118 This is much safer than using patches, and is the recommended way.
120 The following command produces @file{lilypond-1.4.3.tar.gz} from
121 @file{lilypond-1.4.2.tar.gz} identical (up to compression dates) to the .3
124 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
128 @section Requirements
130 @subsection Compilation
132 You need the following packages to compile Lilypond.
135 @item The GNU c++ compiler (version 2.95.2 or newer).
136 EGCS 1.1 may work, but is no longer supported.
137 Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
139 WARNING: if you choose to upgrade to GCC 3.x, enquire if your
140 distribution supports g++ 3.x and flex. At the time of writing (Fri
141 Jul 5 2002), @strong{no} distribution that we know of ships a flex
142 that generates gcc-3.1.x compliant C++ code.
144 @item Python (version 1.5 or newer).
145 Check out @uref{http://www.python.org, the python website}.
147 @item GUILE (version 1.4 or newer).
149 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
153 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
156 @item Flex (version 2.5.4a or newer).
157 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
159 WARNING: plain Flex 2.5.4(a) generates invalid C++ code. GCC 3.x
160 chokes on this. If you wish to use GCC 3.x, make sure that your
161 distribution supports g++ 3.x and flex. For workarounds, see
162 lexer-gcc-3.0.patch and lexer-gcc-3.1.sh in the source directory.
164 @item Bison (version 1.25 or newer).
165 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}
169 @TeX{} is used as an output backend.
171 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf}, @file{.afm}, @file{.tfm}).
172 Make sure you have tetex 1.0 or newer (1.0.6 is known to work). You may
173 need to install a tetex-devel or tetex-dev package too.
175 @item Texinfo (version 4.2 or newer).
176 The documentation of lily is written in texinfo. Check out
177 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
179 @item The geometry package for LaTeX is needed to use ly2dvi.
181 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
182 FTP directory for @code{geometry}}. This package is normally included
183 with the @TeX{} distribution.
185 @item kpathsea, a library for searching (@TeX{}) files. @code{kpathsea} is
186 usually included with your installation of @TeX{}. You may need to install
187 a tetex-devel or tetex-dev package too. If kpathsea is not installed in
188 a directory where the compiler normally looks, read the hints for
191 In the very unlikely case that kpathsea is not available for your
192 platform (ie, you're not running GNU/Linux, Windows, or any recent
193 UNIX), you can compile LilyPond without kpathsea support. In that case,
194 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
195 configure something like:
199 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
205 @subsection Running requirements
207 GNU LilyPond does use a lot of resources. For operation you need the
212 @item Xdvi and Ghostscript
213 @item GUILE 1.4, or newer.
215 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
218 For running LilyPond successfully you have to help @TeX{} and MetaFont find
219 various files. The recommended way of doing so is adjusting the
220 environment variables in the start-up scripts of your shell. Appropriate
221 Csh and bourne sh scripts are left in
222 @file{buildscripts/out/lilypond-profile} and
223 @file{buildscripts/out/lilypond-login} after compilation.
225 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
226 recommended for comfortable use.
228 @subsection Website requirements
230 The documentation comes in the form of a website. You can view this
231 website on the internet, but you can also build it locally. This process
232 requires a successful compile of lilypond. The website is built
240 Building the website requires some additional tools:
243 @item The netpbm utilities, see @uref{http://netpbm.sourceforge.net/}
244 @item pktrace 1.0 or newer, needed for generating PostScript Type1
245 fonts. Get it from @uref{http://www.cs.uu.nl/~hanwen/pktrace/}. You
246 will need to install some additional packages to get pktrace to work.
249 @section Building LilyPond
251 to install GNU LilyPond, type:
253 gunzip -c lilypond-x.y.z | tar xf -
255 ./configure # run with --help to see appropriate options
258 sh buildscripts/clean-fonts.sh
261 If you are doing an upgrade, you should remove all @file{feta}
262 @code{.pk} and @file{.tfm} files. A script has been provided to do the
263 work for you, see @file{buildscripts/clean-fonts.sh}.
266 If you are not root, you should choose a @code{--prefix} argument that
267 points into your home directory, eg.
270 ./configure --prefix=$HOME/usr
274 In this case, you have to insert the contents of
275 @code{buildscripts/out/lilypond-login} or
276 @code{buildscripts/out/lilypond-profile} into your start up scripts by
281 @subsection Configuring for multiple platforms
283 If you want to build multiple versions of LilyPond with different
284 configuration settings, you can use the @code{--enable-config=CONF}
285 option of configure. You should use @samp{make conf=CONF} to generate
286 the output in @file{out-CONF}. Example: suppose I want to build with
287 and without profiling. Then I'd use the following for the normal
292 ./configure --prefix=~ --enable-checking
297 and for the profiling version, I specify a different configuration.
301 ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
303 make conf=prof install
313 An Emacs mode for entering music and running LilyPond is included with
314 the source archive as @file{lilypond-mode.el},
315 @file{lilypond-indent.el} and @file{lilypond-font-lock.el}. You
316 should install these files somewhere in your @var{load-path}. If you
317 have installed a precompiled LilyPond package, these files can be
318 found in @file{/usr/share/doc/lilypond-x.y.z/}.
320 Add this to your @file{~/.emacs} or @file{~/.emacs.el}, or install this
321 file in Emacs' @file{site-start.d}:
324 ;;; lilypond-init.el --- Startup code for LilyPond mode
326 (autoload 'LilyPond-mode "lilypond-mode")
327 (setq auto-mode-alist
328 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
330 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
334 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode is
335 automatically loaded, you not even need to modify your @code{~/.emacs}
338 @section Compiling for distributions
340 @subsection Red Hat Linux
342 Red Hat 7.x i386 RPMS are available from
343 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}. For running on
344 a Red Hat system you need these packages: guile, tetex, tetex-latex,
345 tetex-dvips, libstdc++, python, ghostscript.
347 You can also compile them yourself. A spec file is in
348 @file{make/out/lilypond.redhat.spec}. This file is distributed along
349 with the sources. You can make the rpm by issuing
352 tar xfz lilypond-x.y.z.tar.gz
353 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
354 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
358 For compilation on a Red Hat system you need these packages, in
359 addition to the those needed for running: glibc-devel, gcc-c++,
360 libstdc++-devel, guile-devel, flex, bison, texinfo, groff, pktrace,
361 netpbm-progs, autotrace, t1utils.
368 Some LinuxPPC RPMS should available from
369 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
371 A LinuxPPC RPM can be made using the @file{lilypond.redhat.spec} file.
375 Some SUSE RPMS should available from
376 @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.
378 You can also compile a RPM for SUSE yourself. A spec file is in
379 @file{make/out/lilypond.suse.spec}, see the instructions for building
382 You must have the following packages: guile tcsh tetex te_latex te_kpath
383 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
384 gs_serv gs_lib gs_fonts guile
386 @subsection Slackware
388 No precompiled packages for Slackware are available.
390 Problems have been reported with Slackware 7.0; apparently, it ships
391 with a faulty compiler. Do not compile LilyPond with -O2 on this
394 At least on Slackware 8.0, you have to manually specify the paths to the
395 Kpathsea library, using
397 @item @code{rm config.cache}
398 @item @code{export LDFLAGS=-L/usr/share/texmf/lib}
399 @item @code{export CPPFLAGS=-I/usr/share/texmf/include}
400 @item @code{./configure}
406 Some binaries are available at rpmfind.net. Refer to
407 @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.
409 You can also compile a RPM for Mandrake yourself. A spec file is in
410 @file{make/out/lilypond.mandrake.spec}, see the instructions for building
413 @subsection Debian GNU/Linux
415 A Debian package is also available. You may install it easily by running
416 @command{apt-get} as root:
419 apt-get install lilypond lilypond-doc
422 You can also compile the .deb for Debian yourself, do:
425 apt-get -b source lilypond
428 If you're real impatient, you may even do:
431 cd lilypond-x.y.z # a previous version
432 uscan # download and build latest directly from upstream
436 Debian's @TeX{} installation is a bit short on memory, you may want to
437 increase it like this:
439 --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
440 +++ texmf.cnf Sun Dec 16 23:46:34 2001
442 main_memory.context = 1500000
443 main_memory.mpost = 1000000
444 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
445 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
446 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
447 +extra_mem_top = 1000000 % extra high memory for chars, tokens, etc.
448 +extra_mem_bot = 1000000 % extra low memory for boxes, glue, breakpoints, etc.
450 obj_tab_size.context = 300000
453 % Max number of characters in all strings, including all error messages,
454 % help texts, font names, control sequences. These values apply to TeX and MP.
455 pool_size.context = 750000
458 % Minimum pool space after TeX/MP's own strings; must be at least
459 % 25000 less than pool_size, but doesn't need to be nearly that large.
460 string_vacancies.context = 45000
463 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
464 environment variables if you do not want to or cannot modify
465 @file{/etc/texmf/texmf.cnf}.
470 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
471 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
472 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
473 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
474 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
475 package is now obsolete.
478 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
481 The build scripts are in the subdirectory @file{debian/}; you can
482 make the .deb by doing, for example:
486 # dpkg --purge lilypond lilypond1.3
488 $ tar xzf lilypond-1.4.3.tar.gz
490 $ dch -p -v 1.4.3-0.local.1 "Local build."
493 # dpkg -i ../lilypond_1.4.3*.deb
498 Use command @command{debuild} instead of @command{debuild -B} if you have
499 a very fast machine and want to build the HTML, PS and DVI documentation
502 For compilation on a Debian GNU/Linux system you need these packages,
503 in addition to the those needed for running:
506 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
507 @item libguile<@var{your-libguile-version-here}>-dev
508 @item make, m4, flex, bison
511 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
512 @item dpkg-dev, debhelper, fakeroot
514 @item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
515 in Debian testing/unstable.)
518 Most of these are listed on the @samp{Build-Depends} line in the
519 @file{debian/control} file. To ensure the creation of the lilypond deb is
520 trouble-free, we recommend that you first install the following packages
521 by running \@command{apt-get} as root before building the package:
526 apt-get install task-debian-devel task-c++-dev \
527 python-base libguile6-dev tetex-bin tetex-dev \
528 tetex-extra flex bison texinfo groff gs \
529 netpbm pnmtopng m4 gettext
532 For Debian in development ("unstable", the future 2.3 or 3.0):
535 apt-get install binutils cpp gcc libc6-dev \
536 g++ libstdc++2.10-dev \
537 python-base libguile-dev tetex-bin libkpathsea-dev \
538 tetex-extra flex bison texinfo groff gs \
542 And, just so that old fonts from previous versions of LilyPond won't
543 interfere with your build, you may want to do this before the build too:
546 dpkg --purge lilypond lilypond1.3
551 LilyPond is available through fink, in the unstable cvs distribution.
555 @item Get the Fink package manager from @uref{http://fink.sourceforge.net}
556 @item Get the Lilypond package description by enabling the "unstable" tree
557 in fink and executing @command{fink selfupdate-cvs}.
563 fink install lilypond-unstable
567 That's it! The command should compile and install all LilyPond
568 prerequisites (python, TeX, X11, ghostscript) and then LilyPond
572 @subsubsection compiling on MacOS X
573 LilyPond has been built on Darwin, to be precise, on:
575 Darwin buoux.aspiratie.nl 5.3 Darwin Kernel Version 5.3: Thu Jan 24
576 22:06:02 PST 2002; root:xnu/xnu-201.19.obj~1/RELEASE_PPC Power Macintosh powerpc
582 Apple Computer, Inc. version gcc-932.1, based on gcc version 2.95.2 19991024 (release)
585 To make sure you have all packages needed to build LilyPond installed,
589 apt-get install bash python guile debianutils flex bison texinfo \
590 ghostscript6 netpbm m4 gettext
599 For more information about @file{apt-get} and @file{fink}, see
600 @uref{http://fink.sf.net,fink.sourceforge.net}.
602 @c brokenness of autoconf; don't ask
603 Then, configure, patch, make and install LilyPond using these commands:
606 CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
607 ./configure --prefix=/sw
608 make -C lily out/parser.hh out/parser.cc out/config.h
609 patch -p0 < darwin.patch
610 make -C lily out/parser.o
611 make DEPENDENCIES_OUTPUT=/dev/null all
615 For installing, you must be root, of course.
617 @c Why isn't this in BUGS (where it belongs?)
620 For help and questions use @email{lilypond-user@@gnu.org}. Please
621 consult the FAQ before mailing your problems. If you find bugs, please
622 send bug reports to @email{bug-lilypond@@gnu.org}.
624 Bugs that are not fault of LilyPond are documented here.
626 @unnumberedsubsec Gcc-3.0.4
628 Gcc 3.0.4, is a bit flaky. Try downgrading to 2.95.x, or if you're
629 adventurous (see below), upgrading to 3.1.x.
631 @unnumberedsubsec Flex-2.5.4a and gcc-3.x
633 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
634 LilyPond with gcc-3.0 you may do:
637 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
638 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
639 patch -p1 < lexer-gcc-3.0.patch
640 make conf=gcc-3.0 -C lily
643 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
645 @unnumberedsubsec Flex-2.5.4a and gcc-3.1.x
647 Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code. To compile
648 LilyPond with gcc-3.1.1 you may do:
651 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
652 CPPFLAGS=$(pwd)/lily/out-gcc-3.1 CC=gcc-3.1 CXX=g++-3.1 \
653 ./configure --enable-config=gcc-3.1
654 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
658 Note that this is @strong{not} fixed in Debian/unstable for flex <=
661 @unnumberedsubsec Linux-2.4.0, Guile-1.4 --with-threads
663 There's a bug in certain kernels around version 2.4.0, that is
664 triggered when using Guile 1.4 compiled with pthreads. You'll see
665 random segmentation fault crashes of LilyPond. Upgrade to a newer
666 version of Linux. If you can't do that, you may try to recompiling
667 Guile without threads (YMMV):
670 guile-1.4$ ./configure --without-threads; make all install
674 @unnumberedsubsec NetBSD
677 @item The flex precompiled in NetBSD-1.4.2 is broken.
678 Download flex-2.5.4a, build, install.
680 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
681 release)) does not include @file{/usr/pkg} paths. Configure using:
684 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
690 @unnumberedsubsec Solaris:
693 @item Sparc64/Solaris 2.6, GNU make-3.77
695 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
697 @item Sparc64/Solaris 2.6, ld
703 @unnumberedsubsec AIX
708 The following is from the gcc install/SPECIFIC file.
710 Some versions of the AIX binder (linker) can fail with a relocation
711 overflow severe error when the -bbigtoc option is used to link
712 GCC-produced object files into an executable that overflows the TOC.
713 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
714 -BBIGTOC) is available from IBM Customer Support and from its
715 27service.boulder.ibm.com website as PTF U455193.
717 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
718 as and GNU ld will not work properly and one should not configure GCC
719 to use those GNU utilities. Use the native AIX tools which do
720 interoperate with GCC.
723 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
725 LDFLAGS='-Wl,-bbigtoc' ./configure