3 @comment node-name, next, previous, up\input texinfo @c -*-texinfo-*-
4 @setfilename INSTALL.info
5 @settitle INSTALL - compiling and installing GNU LilyPond
8 <!--- @@WEB-TITLE@@=Installation Instructions --->
13 @chapter INSTALL - compiling and installing GNU LilyPond
16 This document describes how to build LilyPond on Unix platforms. It
17 is also known to run and compile on Windows NT/95/98/ME/XP as well.
18 More information on this topic can be found at the
19 @uref{http://www.lilypond.org/cygwin/, LilyPond on Windows page}.
23 <a name="download-source">
28 Even numbered versions are `stable'. The webpages for the stable version
29 (1.4) reside @uref{http://www.gnu.org/software/lilypond, on the GNU
30 servers}. Big enhancements go into the latest odd numbered version
31 (1.5), whose webpages are on @uref{http://www.lilypond.org/,the lilypond
34 @subsection Source code
36 If you want to compile LilyPond from source, download here:
38 @item Download development releases from
39 @c Hmm, these won't show up in lilypond.org/stats
40 @c Otoh, lilypond.org is not updated when release mail arrives
41 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/} by FTP and
42 @uref{http://ftp.cs.uu.nl/pub/GNU/LilyPond/}, by HTTP.
43 @item @uref{ftp://sca.uwaterloo.ca/pub/} by FTP (Canadian mirror)
44 @item at @code{lilypond.org}
45 @uref{ftp://ftp.lilypond.org/pub/LilyPond/} by FTP and
46 @uref{http://www.lilypond.org/ftp/} by HTTP.
50 For Red Hat Linux and SuSE Linux, @file{.spec} files are included in the
51 tarball; see instructions below.
55 Of course, if your platform supports LilyPond, such as Debian GNU/Linux,
56 FreeBSD, OpenBSD or NetBSD, you're encouraged to use the native build
59 The latest development version is also available through anonymous
60 CVS. See @uref{http://savannah.gnu.org/cvs/?group=lilypond}.
62 CVS does not contain generated files. To create @file{configure}, run
70 <a name="download-binaries">
75 @subsection Precompiled binaries
77 If you want to track bleeding edge development, try:
80 @item @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond/, Debian
81 GNU/Linux} usually has the latest binaries for the most useful stable
82 and development versions, while
83 @item @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/,
84 Mandrake Cooker} also provides fairly recent versions.
87 Binaries are made available for other popular platforms, but as we need
88 to compile them ourselves, they are not updated for every version
92 @item @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/, Red Hat i386}
93 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE, SuSE}
94 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/,
97 @uref{http://www.lilypond.org/gnu-windows/, Windows}
100 @subsection Upgrading
102 There are two options for upgrading sources.
105 @item if you have an unpacked source tree of a previous version, you
108 @emph{If you upgrade by patching do remember to rerun autoconf after
111 @item if you have the @code{.tar.gz} file of a previous release, you can
113 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
114 This is much safer than using patches, and is the recommended way.
116 The following command produces @file{lilypond-1.4.3.tar.gz} from
117 @file{lilypond-1.4.2.tar.gz} identical (up to compression dates) to the .3
120 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
124 @subsection Font problems.
126 If you are upgrading from a previous version of LilyPond, be sure to
127 remove all old font files. These include @file{.pk} and @file{.tfm} files
128 that may be located in @file{/var/lib/texmf}, @file{/var/spool/texmf},
129 @file{/var/tmp/texmf} or @file{@var{prefix}/share/lilypond/fonts/}. A
130 script automating this has been included, see
131 @file{buildscripts/clean-fonts.sh}.
136 @section Requirements
138 @subsection Compilation
140 You need the following packages to compile Lilypond.
143 @item The GNU c++ compiler (version 2.95.2 or newer).
144 EGCS 1.1 may work, but is no longer supported.
145 Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
147 WARNING: if you choose to upgrade to GCC 3.x, enquire if your
148 distribution supports g++ 3.x and flex. At the time of writing (Fri
149 Jul 5 2002), @strong{no} distribution that we know of ships a flex
150 that generates gcc-3.1.x compliant C++ code.
152 @item Python (version 1.5 or newer).
153 Check out @uref{http://www.python.org, the python website}.
155 @item GUILE (version 1.4 or newer).
157 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
161 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
164 @item Flex (version 2.5.4a or newer).
165 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
167 WARNING: plain Flex 2.5.4(a) generates invalid C++ code. GCC 3.x
168 chokes on this. If you wish to use GCC 3.x, make sure that your
169 distribution supports g++ 3.x and flex. For workarounds, see
170 lexer-gcc-3.0.patch and lexer-gcc-3.1.sh in the source directory.
172 @item Bison (version 1.25 or newer).
173 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}
177 @TeX{} is used as an output backend.
179 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf},
180 @file{.afm}, @file{.tfm}). Make sure you have tetex 1.0 or newer
181 (1.0.6 is known to work). You may need to install a tetex-devel (or
182 tetex-dev or libkpathsea-dev) package too.
184 @item Texinfo (version 4.2 or newer).
185 The documentation of lily is written in texinfo. Check out
186 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
188 @item The geometry package for LaTeX is needed to use ly2dvi.
190 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
191 FTP directory for @code{geometry}}. This package is normally included
192 with the @TeX{} distribution.
194 @item kpathsea, a library for searching (@TeX{}) files. @code{kpathsea} is
195 usually included with your installation of @TeX{}. You may need to
196 install a tetex-devel or tetex-dev package too. If kpathsea is not
197 installed in a directory where the compiler normally looks, read the
198 hints for Slackware below.
200 In the very unlikely case that kpathsea is not available for your
201 platform (ie, you're not running GNU/Linux, Windows, or any recent
202 UNIX), you can compile LilyPond without kpathsea support. In that case,
203 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
204 configure something like:
208 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
214 @subsection Running requirements
216 GNU LilyPond does use a lot of resources. For operation you need the
221 @item Xdvi and Ghostscript
222 @item GUILE 1.4, or newer.
224 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
227 For running LilyPond successfully you have to help @TeX{} and MetaFont find
228 various files. The recommended way of doing so is adjusting the
229 environment variables in the start-up scripts of your shell. Appropriate
230 Csh and bourne sh scripts are left in
231 @file{buildscripts/out/lilypond-profile} and
232 @file{buildscripts/out/lilypond-login} after compilation.
234 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
235 recommended for comfortable use.
237 @subsection Building website
239 The documentation comes in the form of a website. You can view this
240 website on the internet, but you can also build it locally. This process
241 requires a successful compile of lilypond. The website is built
249 Building the website requires some additional tools:
252 @item The netpbm utilities, see @uref{http://netpbm.sourceforge.net/}
253 @item mftrace 1.0 or newer, needed for generating PostScript Type1
254 fonts. Get it from @uref{http://www.cs.uu.nl/~hanwen/mftrace/}. You
255 will need to install some additional packages to get mftrace to work.
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
301 ./configure --prefix=$HOME/usr/ --enable-checking
306 and for the profiling version, I specify a different configuration.
310 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
312 make conf=prof install
322 An Emacs mode for entering music and running LilyPond is included with
323 the source archive as @file{lilypond-mode.el},
324 @file{lilypond-indent.el} and @file{lilypond-font-lock.el}. You
325 should install these files somewhere in your @var{load-path}. If you
326 have installed a precompiled LilyPond package, these files can be
327 found in @file{/usr/share/doc/lilypond-x.y.z/}.
329 Add this to your @file{~/.emacs} or @file{~/.emacs.el}, or install this
330 file in Emacs' @file{site-start.d}:
333 ;;; lilypond-init.el --- Startup code for LilyPond mode
335 (autoload 'LilyPond-mode "lilypond-mode")
336 (setq auto-mode-alist
337 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
339 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
343 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode is
344 automatically loaded, you not even need to modify your @code{~/.emacs}
347 @section Compiling for distributions
349 @subsection Red Hat Linux
351 Red Hat 7.x i386 RPMS are available from
352 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}. For running on
353 a Red Hat system you need these packages: guile, tetex, tetex-latex,
354 tetex-dvips, libstdc++, python, ghostscript.
356 You can also compile them yourself. A spec file is in
357 @file{make/out/lilypond.redhat.spec}. This file is distributed along
358 with the sources. You can make the rpm by issuing
361 tar xfz lilypond-x.y.z.tar.gz
362 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
363 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
367 For compilation on a Red Hat system you need these packages, in
368 addition to the those needed for running: glibc-devel, gcc-c++,
369 libstdc++-devel, guile-devel, flex, bison, texinfo, groff, mftrace,
370 netpbm-progs, autotrace, t1utils.
377 Some LinuxPPC RPMS should available from
378 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
380 A LinuxPPC RPM can be made using the @file{lilypond.redhat.spec} file.
384 Some SUSE RPMS should available from
385 @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.
387 You can also compile a RPM for SUSE yourself. A spec file is in
388 @file{make/out/lilypond.suse.spec}, see the instructions for building
391 You must have the following packages: guile tcsh tetex te_latex te_kpath
392 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
393 gs_serv gs_lib gs_fonts guile
395 @subsection Slackware
397 No precompiled packages for Slackware are available.
399 Problems have been reported with Slackware 7.0; apparently, it ships
400 with a faulty compiler. Do not compile LilyPond with -O2 on this
403 At least on Slackware 8.0, you have to manually specify the paths to the
404 Kpathsea library, see the section on kpathsea
409 Some binaries are available at rpmfind.net. Refer to
410 @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.
412 You can also compile a RPM for Mandrake yourself. A spec file is in
413 @file{make/out/lilypond.mandrake.spec}, see the instructions for building
416 @subsection Debian GNU/Linux
418 A Debian package is also available. You may install it easily by running
419 @command{apt-get} as root:
422 apt-get install lilypond lilypond-doc
425 You can also compile the .deb for Debian yourself, do:
428 apt-get -b source lilypond
431 If you're real impatient, you may even do:
434 cd lilypond-x.y.z # a previous version
435 uscan # download and build latest directly from upstream
439 Debian's @TeX{} installation is a bit short on memory, you may want to
440 increase it like this:
442 --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
443 +++ texmf.cnf Sun Dec 16 23:46:34 2001
445 main_memory.context = 1500000
446 main_memory.mpost = 1000000
447 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
448 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
449 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
450 +extra_mem_top = 1000000 % extra high memory for chars, tokens, etc.
451 +extra_mem_bot = 1000000 % extra low memory for boxes, glue, breakpoints, etc.
453 obj_tab_size.context = 300000
456 % Max number of characters in all strings, including all error messages,
457 % help texts, font names, control sequences. These values apply to TeX and MP.
458 pool_size.context = 750000
461 % Minimum pool space after TeX/MP's own strings; must be at least
462 % 25000 less than pool_size, but doesn't need to be nearly that large.
463 string_vacancies.context = 45000
466 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
467 environment variables if you do not want to or cannot modify
468 @file{/etc/texmf/texmf.cnf}.
473 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
474 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
475 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
476 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
477 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
478 package is now obsolete.
481 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
484 The build scripts are in the subdirectory @file{debian/}; you can
485 make the .deb by doing, for example:
489 # dpkg --purge lilypond lilypond1.3
491 $ tar xzf lilypond-1.4.3.tar.gz
493 $ dch -p -v 1.4.3-0.local.1 "Local build."
496 # dpkg -i ../lilypond_1.4.3*.deb
501 Use command @command{debuild} instead of @command{debuild -B} if you have
502 a very fast machine and want to build the HTML, PS and DVI documentation
505 For compilation on a Debian GNU/Linux system you need these packages,
506 in addition to the those needed for running:
509 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
510 @item libguile<@var{your-libguile-version-here}>-dev
511 @item make, m4, flex, bison
514 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
515 @item dpkg-dev, debhelper, fakeroot
517 @item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
518 in Debian testing/unstable.)
521 Most of these are listed on the @samp{Build-Depends} line in the
522 @file{debian/control} file. To ensure the creation of the lilypond deb is
523 trouble-free, we recommend that you first install the following packages
524 by running \@command{apt-get} as root before building the package:
529 apt-get install task-debian-devel task-c++-dev \
530 python-base libguile6-dev tetex-bin tetex-dev \
531 tetex-extra flex bison texinfo groff gs \
532 netpbm pnmtopng m4 gettext
535 For Debian in development ("unstable", the future 2.3 or 3.0):
538 apt-get install binutils cpp gcc libc6-dev \
539 g++ libstdc++2.10-dev \
540 python-base libguile-dev tetex-bin libkpathsea-dev \
541 tetex-extra flex bison texinfo groff gs \
545 And, just so that old fonts from previous versions of LilyPond won't
546 interfere with your build, you may want to do this before the build too:
549 dpkg --purge lilypond lilypond1.3
554 LilyPond is available through fink, in the unstable cvs distribution.
558 @item Get the Fink package manager from @uref{http://fink.sourceforge.net}
559 @item Get the Lilypond package description by enabling the "unstable" tree
560 in fink and executing @command{fink selfupdate-cvs}.
566 fink install lilypond-unstable
570 That's it! The command should compile and install all LilyPond
571 prerequisites (python, TeX, X11, ghostscript) and then LilyPond
575 @subsection compiling on MacOS X
576 LilyPond has been built on Darwin, to be precise, on:
578 Darwin buoux.aspiratie.nl 5.3 Darwin Kernel Version 5.3: Thu Jan 24
579 22:06:02 PST 2002; root:xnu/xnu-201.19.obj~1/RELEASE_PPC Power Macintosh powerpc
585 Apple Computer, Inc. version gcc-932.1, based on gcc version 2.95.2 19991024 (release)
588 To make sure you have all packages needed to build LilyPond installed,
592 apt-get install bash python guile debianutils flex bison texinfo \
593 ghostscript6 netpbm m4 gettext
602 For more information about @file{apt-get} and @file{fink}, see
603 @uref{http://fink.sf.net,fink.sourceforge.net}.
605 @c brokenness of autoconf; don't ask
606 Then, configure, patch, make and install LilyPond using these commands:
609 CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
610 ./configure --prefix=/sw
611 make -C lily out/parser.hh out/parser.cc out/config.h
612 patch -p0 < darwin.patch
613 make -C lily out/parser.o
614 make DEPENDENCIES_OUTPUT=/dev/null all
618 For installing, you must be root, of course.
620 @c Why isn't this in BUGS (where it belongs?)
623 For help and questions use @email{lilypond-user@@gnu.org}. Please
624 consult the FAQ before mailing your problems. If you find bugs, please
625 send bug reports to @email{bug-lilypond@@gnu.org}.
627 Bugs that are not fault of LilyPond are documented here.
629 @subsection Linking to kpathsea
631 If kpathsea and the corresponding header files are installed in some
632 directory where GCC does not search by default, for example in
633 @file{/usr/local/lib/} and @file{/usr/local/include/} respectively,
634 you have to explicitly tell configure where to find it. To do this,
637 @item @code{rm config.cache}
638 @item @code{export LDFLAGS=-L/usr/share/texmf/lib}
639 @item @code{export CPPFLAGS=-I/usr/share/texmf/include}
640 @item @code{./configure}
642 Once configure has found them, the paths are stored in
643 @file{config.make} and will be used even if you don't have the
644 environment variables set during make.
647 @unnumberedsubsec Gcc-3.0.4
649 Gcc 3.0.4, is a bit flaky. Try downgrading to 2.95.x, or if you're
650 adventurous (see below), upgrading to 3.1.x.
652 @unnumberedsubsec Flex-2.5.4a and gcc-3.x
654 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
655 LilyPond with gcc-3.0 you may do:
658 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
659 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
660 patch -p1 < lexer-gcc-3.0.patch
661 make conf=gcc-3.0 -C lily
664 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
666 @unnumberedsubsec Flex-2.5.4a and gcc-3.1.x
668 Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code. To compile
669 LilyPond with gcc-3.1.1 you may do:
672 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
673 CPPFLAGS=-I$(pwd)/lily/out-gcc-3.1 CC=gcc-3.1 CXX=g++-3.1 \
674 ./configure --enable-config=gcc-3.1
675 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
679 This assumes that the GCC 3.1 binaries are called gcc-3.1 and g++-3.1.
680 Note that this is @strong{not} fixed in Debian/unstable for flex <=
683 @unnumberedsubsec Linux-2.4.0, Guile-1.4 --with-threads
685 There's a bug in certain kernels around version 2.4.0, that is
686 triggered when using Guile 1.4 compiled with pthreads. You'll see
687 random segmentation fault crashes of LilyPond. Upgrade to a newer
688 version of Linux. If you can't do that, you may try to recompiling
689 Guile without threads (YMMV):
692 guile-1.4$ ./configure --without-threads; make all install
695 @unnumberedsubsec OpenBSD
698 @item By default, gcc on OpenBSD doesn't include
699 @file{/usr/local/include} and @file{/usr/local/lib} in the system
700 paths. Depending upon where/how you installed kpathsea and other
701 libraries, you may need to refer to the section ``Linking to
706 @unnumberedsubsec NetBSD
709 @item The flex precompiled in NetBSD-1.4.2 is broken.
710 Download flex-2.5.4a, build, install.
712 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
713 release)) does not include @file{/usr/pkg} paths. Configure using:
716 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
722 @unnumberedsubsec Solaris:
725 @item Sparc64/Solaris 2.6, GNU make-3.77
727 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
729 @item Sparc64/Solaris 2.6, ld
735 @unnumberedsubsec AIX
740 The following is from the gcc install/SPECIFIC file.
742 Some versions of the AIX binder (linker) can fail with a relocation
743 overflow severe error when the -bbigtoc option is used to link
744 GCC-produced object files into an executable that overflows the TOC.
745 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
746 -BBIGTOC) is available from IBM Customer Support and from its
747 27service.boulder.ibm.com website as PTF U455193.
749 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
750 as and GNU ld will not work properly and one should not configure GCC
751 to use those GNU utilities. Use the native AIX tools which do
752 interoperate with GCC.
755 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
757 LDFLAGS='-Wl,-bbigtoc' ./configure