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 For Red Hat Linux and SuSE Linux, @file{.spec} files are included in the
53 tarball; see instructions below.
57 Of course, if your platform supports LilyPond, such as Debian GNU/Linux,
58 FreeBSD, OpenBSD or NetBSD, you're encouraged to use the native build
61 The latest development version is also available through anonymous
62 CVS. See @uref{http://savannah.gnu.org/cvs/?group=lilypond}.
64 CVS does not contain generated files. To create @file{configure}, run
72 <a name="download-binaries">
77 @subsection Precompiled binaries
79 If you want to track bleeding edge development, try:
82 @item @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond/, Debian
83 GNU/Linux} usually has the latest binaries for the most useful stable
84 and development versions, while
85 @item @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/,
86 Mandrake Cooker} also provides fairly recent versions.
89 Binaries are made available for other popular platforms, but as we need
90 to compile them ourselves, they are not updated for every version
94 @item @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/, Red Hat i386}
95 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE, SuSE}
96 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/,
99 @uref{http://www.lilypond.org/gnu-windows/, Windows}
102 @subsection Upgrading
104 There are two options for upgrading sources.
107 @item if you have an unpacked source tree of a previous version, you
110 @emph{If you upgrade by patching do remember to rerun autoconf after
113 @item if you have the @code{.tar.gz} file of a previous release, you can
115 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
116 This is much safer than using patches, and is the recommended way.
118 The following command produces @file{lilypond-1.4.3.tar.gz} from
119 @file{lilypond-1.4.2.tar.gz} identical (up to compression dates) to the .3
122 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
126 @subsection Font problems.
128 If you are upgrading from a previous version of LilyPond, be sure to
129 remove all old font files. These include @file{.pk} and @file{.tfm} files
130 that may be located in @file{/var/lib/texmf}, @file{/var/spool/texmf},
131 @file{/var/tmp/texmf} or @file{@var{prefix}/share/lilypond/fonts/}. A
132 script automating this has been included, see
133 @file{buildscripts/clean-fonts.sh}.
138 @section Requirements
140 @subsection Compilation
142 You need the following packages to compile Lilypond.
145 @item The GNU c++ compiler (version 2.95.2 or newer).
146 EGCS 1.1 may work, but is no longer supported.
147 Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
149 WARNING: if you choose to upgrade to GCC 3.x, enquire if your
150 distribution supports g++ 3.x and flex. At the time of writing (Fri
151 Jul 5 2002), @strong{no} distribution that we know of ships a flex
152 that generates gcc-3.1.x compliant C++ code.
154 @item Python (version 1.5 or newer).
155 Check out @uref{http://www.python.org, the python website}.
157 @item GUILE (version 1.4 or newer).
159 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
163 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
166 @item Flex (version 2.5.4a or newer).
167 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
169 WARNING: plain Flex 2.5.4(a) generates invalid C++ code. GCC 3.x
170 chokes on this. If you wish to use GCC 3.x, make sure that your
171 distribution supports g++ 3.x and flex. For workarounds, see
172 lexer-gcc-3.0.patch and lexer-gcc-3.1.sh in the source directory.
174 @item Bison (version 1.25 or newer).
175 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}
179 @TeX{} is used as an output backend.
181 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf},
182 @file{.afm}, @file{.tfm}). Make sure you have tetex 1.0 or newer
183 (1.0.6 is known to work). You may need to install a tetex-devel (or
184 tetex-dev or libkpathsea-dev) package too.
186 @item Texinfo (version 4.2 or newer).
187 The documentation of lily is written in texinfo. Check out
188 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
190 @item The geometry package for LaTeX is needed to use ly2dvi.
192 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
193 FTP directory for @code{geometry}}. This package is normally included
194 with the @TeX{} distribution.
196 @item kpathsea, a library for searching (@TeX{}) files. @code{kpathsea} is
197 usually included with your installation of @TeX{}. You may need to
198 install a tetex-devel or tetex-dev package too. If kpathsea is not
199 installed in a directory where the compiler normally looks, read the
200 hints for Slackware below.
202 In the very unlikely case that kpathsea is not available for your
203 platform (ie, you're not running GNU/Linux, Windows, or any recent
204 UNIX), you can compile LilyPond without kpathsea support. In that case,
205 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
206 configure something like:
210 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
216 @subsection Running requirements
218 GNU LilyPond does use a lot of resources. For operation you need the
223 @item Xdvi and Ghostscript
224 @item GUILE 1.4, or newer.
226 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
229 For running LilyPond successfully you have to help @TeX{} and MetaFont find
230 various files. The recommended way of doing so is adjusting the
231 environment variables in the start-up scripts of your shell. Appropriate
232 Csh and bourne sh scripts are left in
233 @file{buildscripts/out/lilypond-profile} and
234 @file{buildscripts/out/lilypond-login} after compilation.
236 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
237 recommended for comfortable use.
239 @subsection Building website
241 The documentation comes in the form of a website. You can view this
242 website on the internet, but you can also build it locally. This process
243 requires a successful compile of lilypond. The website is built
251 Building the website requires some additional tools:
254 @item The netpbm utilities, see @uref{http://netpbm.sourceforge.net/}
255 @item mftrace 1.0 or newer, needed for generating PostScript Type1
256 fonts. Get it from @uref{http://www.cs.uu.nl/~hanwen/mftrace/}. You
257 will need to install some additional packages to get mftrace to work.
260 @section Building LilyPond
262 to install GNU LilyPond, type:
264 gunzip -c lilypond-x.y.z | tar xf -
266 ./configure # run with --help to see appropriate options
269 sh buildscripts/clean-fonts.sh
272 If you are doing an upgrade, you should remove all @file{feta}
273 @code{.pk} and @file{.tfm} files. A script has been provided to do the
274 work for you, see @file{buildscripts/clean-fonts.sh}.
277 If you are not root, you should choose a @code{--prefix} argument that
278 points into your home directory, eg.
281 ./configure --prefix=$HOME/usr
285 In this case, you have to insert the contents of
286 @code{buildscripts/out/lilypond-login} or
287 @code{buildscripts/out/lilypond-profile} into your start up scripts by
292 @subsection Configuring for multiple platforms
294 If you want to build multiple versions of LilyPond with different
295 configuration settings, you can use the @code{--enable-config=CONF}
296 option of configure. You should use @samp{make conf=CONF} to generate
297 the output in @file{out-CONF}. Example: suppose I want to build with
298 and without profiling. Then I'd use the following for the normal
303 ./configure --prefix=$HOME/usr/ --enable-checking
308 and for the profiling version, I specify a different configuration.
312 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
314 make conf=prof install
324 An Emacs mode for entering music and running LilyPond is included with
325 the source archive as @file{lilypond-mode.el},
326 @file{lilypond-indent.el} and @file{lilypond-font-lock.el}. You
327 should install these files somewhere in your @var{load-path}. If you
328 have installed a precompiled LilyPond package, these files can be
329 found in @file{/usr/share/doc/lilypond-x.y.z/}.
331 Add this to your @file{~/.emacs} or @file{~/.emacs.el}, or install this
332 file in Emacs' @file{site-start.d}:
335 ;;; lilypond-init.el --- Startup code for LilyPond mode
337 (autoload 'LilyPond-mode "lilypond-mode")
338 (setq auto-mode-alist
339 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
341 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
345 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode is
346 automatically loaded, you not even need to modify your @code{~/.emacs}
349 @section Compiling for distributions
351 @subsection Red Hat Linux
353 Red Hat 7.x i386 RPMS are available from
354 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}. For running on
355 a Red Hat system you need these packages: guile, tetex, tetex-latex,
356 tetex-dvips, libstdc++, python, ghostscript.
358 You can also compile them yourself. A spec file is in
359 @file{make/out/lilypond.redhat.spec}. This file is distributed along
360 with the sources. You can make the rpm by issuing
363 tar xfz lilypond-x.y.z.tar.gz
364 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
365 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
369 For compilation on a Red Hat system you need these packages, in
370 addition to the those needed for running: glibc-devel, gcc-c++,
371 libstdc++-devel, guile-devel, flex, bison, texinfo, groff, mftrace,
372 netpbm-progs, autotrace, t1utils.
379 Some LinuxPPC RPMS should available from
380 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
382 A LinuxPPC RPM can be made using the @file{lilypond.redhat.spec} file.
386 Some SUSE RPMS should available from
387 @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.
389 You can also compile a RPM for SUSE yourself. A spec file is in
390 @file{make/out/lilypond.suse.spec}, see the instructions for building
393 You must have the following packages: guile tcsh tetex te_latex te_kpath
394 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
395 gs_serv gs_lib gs_fonts guile
397 @subsection Slackware
399 No precompiled packages for Slackware are available.
401 Problems have been reported with Slackware 7.0; apparently, it ships
402 with a faulty compiler. Do not compile LilyPond with -O2 on this
405 At least on Slackware 8.0, you have to manually specify the paths to the
406 Kpathsea library, see the section on kpathsea
411 Some binaries are available at rpmfind.net. Refer to
412 @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.
414 You can also compile a RPM for Mandrake yourself. A spec file is in
415 @file{make/out/lilypond.mandrake.spec}, see the instructions for building
418 @subsection Debian GNU/Linux
420 A Debian package is also available. You may install it easily by running
421 @command{apt-get} as root:
424 apt-get install lilypond lilypond-doc
427 You can also compile the .deb for Debian yourself, do:
430 apt-get -b source lilypond
433 If you're real impatient, you may even do:
436 cd lilypond-x.y.z # a previous version
437 uscan # download and build latest directly from upstream
441 Debian's @TeX{} installation is a bit short on memory, you may want to
442 increase it like this:
444 --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
445 +++ texmf.cnf Sun Dec 16 23:46:34 2001
447 main_memory.context = 1500000
448 main_memory.mpost = 1000000
449 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
450 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
451 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
452 +extra_mem_top = 1000000 % extra high memory for chars, tokens, etc.
453 +extra_mem_bot = 1000000 % extra low memory for boxes, glue, breakpoints, etc.
455 obj_tab_size.context = 300000
458 % Max number of characters in all strings, including all error messages,
459 % help texts, font names, control sequences. These values apply to TeX and MP.
460 pool_size.context = 750000
463 % Minimum pool space after TeX/MP's own strings; must be at least
464 % 25000 less than pool_size, but doesn't need to be nearly that large.
465 string_vacancies.context = 45000
468 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
469 environment variables if you do not want to or cannot modify
470 @file{/etc/texmf/texmf.cnf}.
475 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
476 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
477 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
478 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
479 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
480 package is now obsolete.
483 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
486 The build scripts are in the subdirectory @file{debian/}; you can
487 make the .deb by doing, for example:
491 # dpkg --purge lilypond lilypond1.3
493 $ tar xzf lilypond-1.4.3.tar.gz
495 $ dch -p -v 1.4.3-0.local.1 "Local build."
498 # dpkg -i ../lilypond_1.4.3*.deb
503 Use command @command{debuild} instead of @command{debuild -B} if you have
504 a very fast machine and want to build the HTML, PS and DVI documentation
507 For compilation on a Debian GNU/Linux system you need these packages,
508 in addition to the those needed for running:
511 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
512 @item libguile<@var{your-libguile-version-here}>-dev
513 @item make, m4, flex, bison
516 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
517 @item dpkg-dev, debhelper, fakeroot
519 @item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
520 in Debian testing/unstable.)
523 Most of these are listed on the @samp{Build-Depends} line in the
524 @file{debian/control} file. To ensure the creation of the lilypond deb is
525 trouble-free, we recommend that you first install the following packages
526 by running \@command{apt-get} as root before building the package:
531 apt-get install task-debian-devel task-c++-dev \
532 python-base libguile6-dev tetex-bin tetex-dev \
533 tetex-extra flex bison texinfo groff gs \
534 netpbm pnmtopng m4 gettext
537 For Debian in development ("unstable", the future 2.3 or 3.0):
540 apt-get install binutils cpp gcc libc6-dev \
541 g++ libstdc++2.10-dev \
542 python-base libguile-dev tetex-bin libkpathsea-dev \
543 tetex-extra flex bison texinfo groff gs \
547 And, just so that old fonts from previous versions of LilyPond won't
548 interfere with your build, you may want to do this before the build too:
551 dpkg --purge lilypond lilypond1.3
556 LilyPond is available through fink, in the unstable cvs distribution.
560 @item Get the Fink package manager from @uref{http://fink.sourceforge.net}
561 @item Get the Lilypond package description by enabling the "unstable" tree
562 in fink and executing @command{fink selfupdate-cvs}.
568 fink install lilypond-unstable
572 That's it! The command should compile and install all LilyPond
573 prerequisites (python, TeX, X11, ghostscript) and then LilyPond
577 @subsection compiling on MacOS X
578 LilyPond has been built on Darwin, to be precise, on:
580 Darwin buoux.aspiratie.nl 5.3 Darwin Kernel Version 5.3: Thu Jan 24
581 22:06:02 PST 2002; root:xnu/xnu-201.19.obj~1/RELEASE_PPC Power Macintosh powerpc
587 Apple Computer, Inc. version gcc-932.1, based on gcc version 2.95.2 19991024 (release)
590 To make sure you have all packages needed to build LilyPond installed,
594 apt-get install bash python guile debianutils flex bison texinfo \
595 ghostscript6 netpbm m4 gettext
604 For more information about @file{apt-get} and @file{fink}, see
605 @uref{http://fink.sf.net,fink.sourceforge.net}.
607 @c brokenness of autoconf; don't ask
608 Then, configure, patch, make and install LilyPond using these commands:
611 CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
612 ./configure --prefix=/sw
613 make -C lily out/parser.hh out/parser.cc out/config.h
614 patch -p0 < darwin.patch
615 make -C lily out/parser.o
616 make DEPENDENCIES_OUTPUT=/dev/null all
620 For installing, you must be root, of course.
622 @c Why isn't this in BUGS (where it belongs?)
625 For help and questions use @email{lilypond-user@@gnu.org}. Please
626 consult the FAQ before mailing your problems. If you find bugs, please
627 send bug reports to @email{bug-lilypond@@gnu.org}.
629 Bugs that are not fault of LilyPond are documented here.
631 @subsection Linking to kpathsea
633 If kpathsea and the corresponding header files are installed in some
634 directory where GCC does not search by default, for example in
635 @file{/usr/local/lib/} and @file{/usr/local/include/} respectively,
636 you have to explicitly tell configure where to find it. To do this,
639 @item @code{rm config.cache}
640 @item @code{export LDFLAGS=-L/usr/share/texmf/lib}
641 @item @code{export CPPFLAGS=-I/usr/share/texmf/include}
642 @item @code{./configure}
644 Once configure has found them, the paths are stored in
645 @file{config.make} and will be used even if you don't have the
646 environment variables set during make.
649 @unnumberedsubsec Gcc-3.0.4
651 Gcc 3.0.4, is a bit flaky. Try downgrading to 2.95.x, or if you're
652 adventurous (see below), upgrading to 3.1.x.
654 @unnumberedsubsec Flex-2.5.4a and gcc-3.x
656 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
657 LilyPond with gcc-3.0 you may do:
660 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
661 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
662 patch -p1 < lexer-gcc-3.0.patch
663 make conf=gcc-3.0 -C lily
666 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
668 @unnumberedsubsec Flex-2.5.4a and gcc-3.1.x
670 Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code. To compile
671 LilyPond with gcc-3.1.1 you may do:
674 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
675 CPPFLAGS=$(pwd)/lily/out-gcc-3.1 CC=gcc-3.1 CXX=g++-3.1 \
676 ./configure --enable-config=gcc-3.1
677 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
681 Note that this is @strong{not} fixed in Debian/unstable for flex <=
684 @unnumberedsubsec Linux-2.4.0, Guile-1.4 --with-threads
686 There's a bug in certain kernels around version 2.4.0, that is
687 triggered when using Guile 1.4 compiled with pthreads. You'll see
688 random segmentation fault crashes of LilyPond. Upgrade to a newer
689 version of Linux. If you can't do that, you may try to recompiling
690 Guile without threads (YMMV):
693 guile-1.4$ ./configure --without-threads; make all install
697 @unnumberedsubsec NetBSD
700 @item The flex precompiled in NetBSD-1.4.2 is broken.
701 Download flex-2.5.4a, build, install.
703 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
704 release)) does not include @file{/usr/pkg} paths. Configure using:
707 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
713 @unnumberedsubsec Solaris:
716 @item Sparc64/Solaris 2.6, GNU make-3.77
718 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
720 @item Sparc64/Solaris 2.6, ld
726 @unnumberedsubsec AIX
731 The following is from the gcc install/SPECIFIC file.
733 Some versions of the AIX binder (linker) can fail with a relocation
734 overflow severe error when the -bbigtoc option is used to link
735 GCC-produced object files into an executable that overflows the TOC.
736 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
737 -BBIGTOC) is available from IBM Customer Support and from its
738 27service.boulder.ibm.com website as PTF U455193.
740 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
741 as and GNU ld will not work properly and one should not configure GCC
742 to use those GNU utilities. Use the native AIX tools which do
743 interoperate with GCC.
746 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
748 LDFLAGS='-Wl,-bbigtoc' ./configure