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 Building LilyPond is an involved process. We advise to use binary
35 packages if these are available for your platform.
37 @subsection Source code
39 If you want to compile LilyPond from source, download here:
41 @item Download development releases from
42 @c Hmm, these won't show up in lilypond.org/stats
43 @c Otoh, lilypond.org is not updated when release mail arrives
44 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/} by FTP and
45 @uref{http://ftp.cs.uu.nl/pub/GNU/LilyPond/}, by HTTP.
46 @item @uref{ftp://sca.uwaterloo.ca/pub/} by FTP (Canadian mirror)
47 @item at @code{lilypond.org}
48 @uref{ftp://ftp.lilypond.org/pub/LilyPond/} by FTP and
49 @uref{http://www.lilypond.org/ftp/} by HTTP.
53 For Red Hat Linux and SuSE Linux, @file{.spec} files are included in the
54 tarball; see instructions below.
56 Of course, if your platform supports LilyPond, such as Debian GNU/Linux,
57 FreeBSD, OpenBSD or NetBSD, you're encouraged to use the native build
60 The latest development version is also available through anonymous
61 CVS. See @uref{http://savannah.gnu.org/cvs/?group=lilypond}.
63 CVS does not contain generated files. To create @file{configure}, run
71 <a name="download-binaries">
76 @subsection Precompiled binaries
78 If you want to track bleeding edge development, try:
81 @item @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond/, Debian
82 GNU/Linux} usually has the latest binaries for the most useful stable
83 and development versions, while
84 @item @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/,
85 Mandrake Cooker} also provides fairly recent versions.
88 Binaries are made available for other popular platforms, but as we need
89 to compile them ourselves, they are not updated for every version
93 @item @uref{http://www-ccrma.stanford.edu/planetccrma/software/soundapps.html#lilypond,Red Hat i386}
94 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE, SuSE}
95 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/,
98 @uref{http://www.lilypond.org/gnu-windows/, Windows}
101 @subsection Upgrading
103 There are two options for upgrading sources.
106 @item if you have an unpacked source tree of a previous version, you
109 @emph{If you upgrade by patching do remember to rerun autoconf after
112 @item if you have the @code{.tar.gz} file of a previous release, you can
114 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
115 This is much safer than using patches, and is the recommended way.
117 The following command produces @file{lilypond-1.4.3.tar.gz} from
118 @file{lilypond-1.4.2.tar.gz} identical (up to compression dates) to the .3
121 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
125 @subsection Font problems.
127 If you are upgrading from a previous version of LilyPond, be sure to
128 remove all old font files. These include @file{.pk} and @file{.tfm} files
129 that may be located in @file{/var/lib/texmf}, @file{/var/spool/texmf},
130 @file{/var/tmp/texmf} or @file{@var{prefix}/share/lilypond/fonts/}. A
131 script automating this has been included, see
132 @file{buildscripts/clean-fonts.sh}.
137 @section Requirements
139 @subsection Compilation
141 You need the following packages to compile Lilypond.
144 @item The GNU c++ compiler (version 2.95.2 or newer).
145 EGCS 1.1 may work, but is no longer supported.
146 Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
148 WARNING: if you choose to upgrade to GCC 3.x, enquire if your
149 distribution supports g++ 3.x and flex. At the time of writing (Fri
150 Jul 5 2002), @strong{no} distribution that we know of ships a flex
151 that generates gcc-3.1.x compliant C++ code.
153 @item Python (version 1.5 or newer).
154 Check out @uref{http://www.python.org, the python website}.
156 @item GUILE (version 1.4 or newer).
158 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
162 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
165 @item Flex (version 2.5.4a or newer).
166 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
168 WARNING: plain Flex 2.5.4(a) generates invalid C++ code. GCC 3.x
169 chokes on this. If you wish to use GCC 3.x, make sure that your
170 distribution supports g++ 3.x and flex. For workarounds, see
171 lexer-gcc-3.0.patch and lexer-gcc-3.1.sh in the source directory.
173 @item Bison (version 1.25 or newer).
174 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}
178 @TeX{} is used as an output backend.
180 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf},
181 @file{.afm}, @file{.tfm}). Make sure you have tetex 1.0 or newer
182 (1.0.6 is known to work). You may need to install a tetex-devel (or
183 tetex-dev or libkpathsea-dev) package too.
185 @item Texinfo (version 4.2 or newer).
186 The documentation of lily is written in texinfo. Check out
187 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
189 @item The geometry package for LaTeX is needed to use ly2dvi.
191 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
192 FTP directory for @code{geometry}}. This package is normally included
193 with the @TeX{} distribution.
195 @item kpathsea, a library for searching (@TeX{}) files. @code{kpathsea} is
196 usually included with your installation of @TeX{}. You may need to
197 install a tetex-devel or tetex-dev package too. If kpathsea is not
198 installed in a directory where the compiler normally looks, read the
199 hints for Slackware below.
201 In the very unlikely case that kpathsea is not available for your
202 platform (ie, you're not running GNU/Linux, Windows, or any recent
203 UNIX), you can compile LilyPond without kpathsea support. In that case,
204 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
205 configure something like:
209 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
215 @subsection Running requirements
217 GNU LilyPond does use a lot of resources. For operation you need the
222 @item Xdvi and Ghostscript
223 @item GUILE 1.4, or newer.
225 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
228 For running LilyPond successfully you have to help @TeX{} and MetaFont find
229 various files. The recommended way of doing so is adjusting the
230 environment variables in the start-up scripts of your shell. Appropriate
231 Csh and bourne sh scripts are left in
232 @file{buildscripts/out/lilypond-profile} and
233 @file{buildscripts/out/lilypond-login} after compilation.
235 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
236 recommended for comfortable use.
238 @subsection Building documentation
240 You can view the documentation online at
241 @uref{http://www.lilypond.org/stable/Documentation/out-www/}, but you
242 can also build it locally. This process requires a successful compile of
243 lilypond. The documentation is built by issuing
250 Building the website requires some additional tools:
253 @item The netpbm utilities, see @uref{http://netpbm.sourceforge.net/}
254 @item mftrace 1.0 or newer, needed for generating PostScript Type1
255 fonts. Get it from @uref{http://www.cs.uu.nl/~hanwen/mftrace/}. You
256 will need to install some additional packages to get mftrace to work.
259 @section Building LilyPond
261 to install GNU LilyPond, type:
263 gunzip -c lilypond-x.y.z | tar xf -
265 ./configure # run with --help to see appropriate options
268 sh buildscripts/clean-fonts.sh
271 If you are doing an upgrade, you should remove all @file{feta}
272 @code{.pk} and @file{.tfm} files. A script has been provided to do the
273 work for you, see @file{buildscripts/clean-fonts.sh}.
276 If you are not root, you should choose a @code{--prefix} argument that
277 points into your home directory, eg.
280 ./configure --prefix=$HOME/usr
284 In this case, you have to insert the contents of
285 @code{buildscripts/out/lilypond-login} or
286 @code{buildscripts/out/lilypond-profile} into your start up scripts by
291 @subsection Configuring for multiple platforms
293 If you want to build multiple versions of LilyPond with different
294 configuration settings, you can use the @code{--enable-config=CONF}
295 option of configure. You should use @samp{make conf=CONF} to generate
296 the output in @file{out-CONF}. Example: suppose I want to build with
297 and without profiling. Then I'd use the following for the normal
302 ./configure --prefix=$HOME/usr/ --enable-checking
307 and for the profiling version, I specify a different configuration.
311 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
313 make conf=prof install
323 An Emacs mode for entering music and running LilyPond is contained in
324 the source archive as @file{lilypond-mode.el},
325 @file{lilypond-indent.el} and @file{lilypond-font-lock.el}.
326 You should install these files to a directory included in your
327 @var{load-path}. File @file{lilypond-init.el} should be placed to
328 @var{load-path}@file{/site-start.d/} or appended to your @file{~/.emacs}
329 or @file{~/.emacs.el}. If you have installed a precompiled LilyPond
330 package, these files can be found in @file{/usr/share/doc/lilypond-x.y.z/}.
332 As a user, you may want add your source path or, e.g., @file{~/site-lisp/}
333 to your @var{load-path}. Append the following line (modified) to your
337 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
341 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode is
342 automatically loaded, you not even need to modify your @code{~/.emacs}
347 A Vim mode for entering music and running LilyPond is contained in
348 the source archive. Append the content of @file{vimrc} to @file{~/.vimrc}
349 to get shortcuts. Install file @file{lilypond.words} to @file{~/.vim/} to
350 get auto-completion. Syntax highlighting you get by installing
351 @file{lilypond.vim} to @file{~/.vim/syntax/} and appending the following
352 to @file{~/.vim/filetype.vim}:
356 if exists("did_load_filetypes")
359 augroup filetypedetect
360 au! BufRead,BufNewFile *.ly setfiletype lilypond
365 @section Compiling for distributions
367 @subsection Red Hat Linux
369 Red Hat 7.x i386 RPMS are available from
370 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}. For running on
371 a Red Hat system you need these packages: guile, tetex, tetex-latex,
372 tetex-dvips, libstdc++, python, ghostscript.
374 You can also compile them yourself. A spec file is in
375 @file{make/out/lilypond.redhat.spec}. This file is distributed along
376 with the sources. You can make the rpm by issuing
379 cp lilypond-x.y.z.tar.gz /usr/src/redhat/SOURCES/
380 tar xfz lilypond-x.y.z.tar.gz
381 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
382 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
386 For compilation on a Red Hat system you need these packages, in
387 addition to the those needed for running: glibc-devel, gcc-c++,
388 libstdc++-devel, guile-devel, flex, bison, texinfo, groff, mftrace,
389 netpbm-progs, autotrace, t1utils.
396 Some LinuxPPC RPMS should available from
397 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
399 A LinuxPPC RPM can be made using the @file{lilypond.redhat.spec} file.
403 Some SUSE RPMS should available from
404 @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.
406 You can also compile a RPM for SUSE yourself. A spec file is in
407 @file{make/out/lilypond.suse.spec}, see the instructions for building
410 You must have the following packages: guile tcsh tetex te_latex te_kpath
411 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
412 gs_serv gs_lib gs_fonts guile
414 @subsection Slackware
416 No precompiled packages for Slackware are available.
418 Problems have been reported with Slackware 7.0; apparently, it ships
419 with a faulty compiler. Do not compile LilyPond with -O2 on this
422 At least on Slackware 8.0, you have to manually specify the paths to the
423 Kpathsea library, see the section on kpathsea
428 Some binaries are available at rpmfind.net. Refer to
429 @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.
431 You can also compile a RPM for Mandrake yourself. A spec file is in
432 @file{make/out/lilypond.mandrake.spec}, see the instructions for building
435 @subsection Debian GNU/Linux
437 A Debian package is also available. You may install it easily by running
438 @command{apt-get} as root:
441 apt-get install lilypond lilypond-doc
444 You can also compile the .deb for Debian yourself, do:
447 apt-get -b source lilypond
450 If you're real impatient, you may even do:
453 cd lilypond-x.y.z # a previous version
454 uscan # download and build latest directly from upstream
458 Debian's @TeX{} installation is a bit short on memory, you may want to
459 increase it like this:
461 --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
462 +++ texmf.cnf Sun Dec 16 23:46:34 2001
464 main_memory.context = 1500000
465 main_memory.mpost = 1000000
466 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
467 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
468 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
469 +extra_mem_top = 1000000 % extra high memory for chars, tokens, etc.
470 +extra_mem_bot = 1000000 % extra low memory for boxes, glue, breakpoints, etc.
472 obj_tab_size.context = 300000
475 % Max number of characters in all strings, including all error messages,
476 % help texts, font names, control sequences. These values apply to TeX and MP.
477 pool_size.context = 750000
480 % Minimum pool space after TeX/MP's own strings; must be at least
481 % 25000 less than pool_size, but doesn't need to be nearly that large.
482 string_vacancies.context = 45000
485 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
486 environment variables if you do not want to or cannot modify
487 @file{/etc/texmf/texmf.cnf}.
492 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
493 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
494 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
495 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
496 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
497 package is now obsolete.
500 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
503 The build scripts are in the subdirectory @file{debian/}; you can
504 make the .deb by doing, for example:
508 # dpkg --purge lilypond lilypond1.3
510 $ tar xzf lilypond-1.4.3.tar.gz
512 $ dch -p -v 1.4.3-0.local.1 "Local build."
515 # dpkg -i ../lilypond_1.4.3*.deb
520 Use command @command{debuild} instead of @command{debuild -B} if you have
521 a very fast machine and want to build the HTML, PS and DVI documentation
524 For compilation on a Debian GNU/Linux system you need these packages,
525 in addition to the those needed for running:
528 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
529 @item libguile<@var{your-libguile-version-here}>-dev
530 @item make, m4, flex, bison
533 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
534 @item dpkg-dev, debhelper, fakeroot
536 @item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
537 in Debian testing/unstable.)
540 Most of these are listed on the @samp{Build-Depends} line in the
541 @file{debian/control} file. To ensure the creation of the lilypond deb is
542 trouble-free, we recommend that you first install the following packages
543 by running \@command{apt-get} as root before building the package:
548 apt-get install task-debian-devel task-c++-dev \
549 python-base libguile6-dev tetex-bin tetex-dev \
550 tetex-extra flex bison texinfo groff gs \
551 netpbm pnmtopng m4 gettext
554 For Debian in development ("unstable", the future 2.3 or 3.0):
557 apt-get install binutils cpp gcc libc6-dev \
558 g++ libstdc++2.10-dev \
559 python-base libguile-dev tetex-bin libkpathsea-dev \
560 tetex-extra flex bison texinfo groff gs \
564 And, just so that old fonts from previous versions of LilyPond won't
565 interfere with your build, you may want to do this before the build too:
568 dpkg --purge lilypond lilypond1.3
573 LilyPond is available through fink, in the unstable cvs distribution.
577 @item Get the Fink package manager from @uref{http://fink.sourceforge.net}
578 @item Get the Lilypond package description by enabling the "unstable" tree
579 in fink and executing @command{fink selfupdate-cvs}.
585 fink install lilypond-unstable
589 That's it! The command should compile and install all LilyPond
590 prerequisites (python, TeX, X11, ghostscript) and then LilyPond
594 @subsection compiling on MacOS X
595 LilyPond has been built on Darwin, to be precise, on:
597 Darwin buoux.aspiratie.nl 5.3 Darwin Kernel Version 5.3: Thu Jan 24
598 22:06:02 PST 2002; root:xnu/xnu-201.19.obj~1/RELEASE_PPC Power Macintosh powerpc
604 Apple Computer, Inc. version gcc-932.1, based on gcc version 2.95.2 19991024 (release)
607 To make sure you have all packages needed to build LilyPond installed,
611 apt-get install bash python guile debianutils flex bison texinfo \
612 ghostscript6 netpbm m4 gettext
621 For more information about @file{apt-get} and @file{fink}, see
622 @uref{http://fink.sf.net,fink.sourceforge.net}.
624 @c brokenness of autoconf; don't ask
625 Then, configure, patch, make and install LilyPond using these commands:
628 CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
629 ./configure --prefix=/sw
630 make -C lily out/parser.hh out/parser.cc out/config.h
631 patch -p0 < darwin.patch
632 make -C lily out/parser.o
633 make DEPENDENCIES_OUTPUT=/dev/null all
637 For installing, you must be root, of course.
639 @c Why isn't this in BUGS (where it belongs?)
642 For help and questions use @email{lilypond-user@@gnu.org}. Please
643 consult the FAQ before mailing your problems. If you find bugs, please
644 send bug reports to @email{bug-lilypond@@gnu.org}.
646 Bugs that are not fault of LilyPond are documented here.
648 @subsection Linking to kpathsea
650 If kpathsea and the corresponding header files are installed in some
651 directory where GCC does not search by default, for example in
652 @file{/usr/local/lib/} and @file{/usr/local/include/} respectively,
653 you have to explicitly tell configure where to find it. To do this,
656 @item @code{rm config.cache}
657 @item @code{export LDFLAGS=-L/usr/share/texmf/lib}
658 @item @code{export CPPFLAGS=-I/usr/share/texmf/include}
659 @item @code{./configure}
661 Once configure has found them, the paths are stored in
662 @file{config.make} and will be used even if you don't have the
663 environment variables set during make.
666 @unnumberedsubsec Gcc-3.0.4
668 Gcc 3.0.4, is a bit flaky. Try downgrading to 2.95.x, or if you're
669 adventurous (see below), upgrading to 3.1.x.
671 @unnumberedsubsec Flex-2.5.4a and gcc-3.x
673 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
674 LilyPond with gcc-3.0 you may do:
677 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
678 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
679 patch -p1 < lexer-gcc-3.0.patch
680 make conf=gcc-3.0 -C lily
683 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
685 @unnumberedsubsec Flex-2.5.4a and gcc-3.1.x
687 Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code. To compile
688 LilyPond with gcc-3.1.1 you may do:
691 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
692 CPPFLAGS=-I$(pwd)/lily/out-gcc-3.1 CC=gcc-3.1 CXX=g++-3.1 \
693 ./configure --enable-config=gcc-3.1
694 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
698 This assumes that the GCC 3.1 binaries are called gcc-3.1 and g++-3.1.
699 Note that this is @strong{not} fixed in Debian/unstable for flex <=
702 @unnumberedsubsec Linux-2.4.0, Guile-1.4 --with-threads
704 There's a bug in certain kernels around version 2.4.0, that is
705 triggered when using Guile 1.4 compiled with pthreads. You'll see
706 random segmentation fault crashes of LilyPond. Upgrade to a newer
707 version of Linux. If you can't do that, you may try to recompiling
708 Guile without threads (YMMV):
711 guile-1.4$ ./configure --without-threads; make all install
714 @unnumberedsubsec OpenBSD
717 @item By default, gcc on OpenBSD doesn't include
718 @file{/usr/local/include} and @file{/usr/local/lib} in the system
719 paths. Depending upon where/how you installed kpathsea and other
720 libraries, you may need to refer to the section ``Linking to
725 @unnumberedsubsec NetBSD
728 @item The flex precompiled in NetBSD-1.4.2 is broken.
729 Download flex-2.5.4a, build, install.
731 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
732 release)) does not include @file{/usr/pkg} paths. Configure using:
735 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
741 @unnumberedsubsec Solaris
744 @item Solaris7, ./configure
746 @file{./configure} needs a POSIX compliant shell. On Solaris7,
747 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
748 is. Please run configure like:
750 CONFIG_SHELL=/bin/ksh ksh -c ./configure
754 CONFIG_SHELL=/bin/bash bash -c ./configure
757 @item Sparc64/Solaris 2.6, GNU make-3.77
759 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
761 @item Sparc64/Solaris 2.6, ld
767 @unnumberedsubsec AIX
772 The following is from the gcc install/SPECIFIC file.
774 Some versions of the AIX binder (linker) can fail with a relocation
775 overflow severe error when the -bbigtoc option is used to link
776 GCC-produced object files into an executable that overflows the TOC.
777 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
778 -BBIGTOC) is available from IBM Customer Support and from its
779 27service.boulder.ibm.com website as PTF U455193.
781 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
782 as and GNU ld will not work properly and one should not configure GCC
783 to use those GNU utilities. Use the native AIX tools which do
784 interoperate with GCC.
787 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
789 LDFLAGS='-Wl,-bbigtoc' ./configure