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.lilypond.org/pub/LilyPond/} by FTP and
45 @uref{http://www.lilypond.org/ftp/} by HTTP.
46 @item @uref{ftp://sca.uwaterloo.ca/pub/} by FTP (Canadian mirror)
50 For Red Hat Linux and SuSE Linux, @file{.spec} files are included in the
51 tarball; see instructions below.
53 Of course, if your platform supports LilyPond, such as Debian GNU/Linux,
54 FreeBSD, OpenBSD or NetBSD, you're encouraged to use the native build
57 The latest development version is also available through anonymous
58 CVS. See @uref{http://savannah.gnu.org/cvs/?group=lilypond}.
60 CVS does not contain generated files. To create @file{configure}, run
68 <a name="download-binaries">
73 @subsection Precompiled binaries
75 If you want to track bleeding edge development, try:
78 @item @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond/, Debian
79 GNU/Linux} usually has the latest binaries for the most useful stable
80 and development versions, while
81 @item @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/,
82 Mandrake Cooker} also provides fairly recent versions.
85 Binaries are made available for other popular platforms, but as we need
86 to compile them ourselves, they are not updated for every version
90 @item @uref{http://www-ccrma.stanford.edu/planetccrma/software/soundapps.html#lilypond,Red Hat i386}
91 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE, SuSE}
92 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/,
95 @uref{http://www.lilypond.org/gnu-windows/, Windows}
100 There are two options for upgrading sources.
103 @item if you have an unpacked source tree of a previous version, you
106 @emph{If you upgrade by patching do remember to rerun autoconf after
109 @item if you have the @code{.tar.gz} file of a previous release, you can
111 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
112 This is much safer than using patches, and is the recommended way.
114 The following command produces @file{lilypond-1.4.3.tar.gz} from
115 @file{lilypond-1.4.2.tar.gz} identical (up to compression dates) to the .3
118 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
122 @subsection Font problems.
124 If you are upgrading from a previous version of LilyPond, be sure to
125 remove all old font files. These include @file{.pk} and @file{.tfm} files
126 that may be located in @file{/var/lib/texmf}, @file{/var/spool/texmf},
127 @file{/var/tmp/texmf} or @file{@var{prefix}/share/lilypond/fonts/}. A
128 script automating this has been included, see
129 @file{buildscripts/clean-fonts.sh}.
134 @section Requirements
136 @subsection Compilation
138 You need the following packages to compile Lilypond.
141 @item The GNU c++ compiler (version 2.95.2 or newer).
142 EGCS 1.1 may work, but is no longer supported.
143 Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
145 WARNING: if you choose to upgrade to GCC 3.x, enquire if your
146 distribution supports g++ 3.x and flex. At the time of writing (Fri
147 Jul 5 2002), @strong{no} distribution that we know of ships a flex
148 that generates gcc-3.1.x compliant C++ code.
150 @item Python (version 2.1 or newer).
151 Check out @uref{http://www.python.org, the python website}.
153 @item GUILE (version 1.6 or newer).
155 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
159 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
162 @item Flex (version 2.5.4a or newer).
163 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
165 WARNING: plain Flex 2.5.4(a) generates invalid C++ code. GCC 3.x
166 chokes on this. If you wish to use GCC 3.x, make sure that your
167 distribution supports g++ 3.x and flex. For workarounds, see
168 lexer-gcc-3.0.patch and lexer-gcc-3.1.sh in the source directory.
170 @item Bison (version 1.25 or newer).
171 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}
175 @TeX{} is used as an output backend.
177 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf},
178 @file{.afm}, @file{.tfm}). Make sure you have tetex 1.0 or newer
179 (1.0.6 is known to work). You may need to install a tetex-devel (or
180 tetex-dev or libkpathsea-dev) package too.
182 @item Texinfo (version 4.2 or newer).
183 The documentation of lily is written in texinfo. Check out
184 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
186 @item The geometry package for LaTeX is needed to use ly2dvi.
188 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
189 FTP directory for @code{geometry}}. This package is normally included
190 with the @TeX{} distribution.
192 @item kpathsea, a library for searching (@TeX{}) files. @code{kpathsea} is
193 usually included with your installation of @TeX{}. You may need to
194 install a tetex-devel or tetex-dev package too. If kpathsea is not
195 installed in a directory where the compiler normally looks, read the
196 hints for Slackware below.
198 In the very unlikely case that kpathsea is not available for your
199 platform (ie, you're not running GNU/Linux, Windows, or any recent
200 UNIX), you can compile LilyPond without kpathsea support. In that case,
201 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
202 configure something like:
206 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
212 @subsection Running requirements
214 GNU LilyPond does use a lot of resources. For operation you need the
219 @item Xdvi and Ghostscript
220 @item GUILE 1.4, or newer.
222 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
225 For running LilyPond successfully you have to help @TeX{} and MetaFont find
226 various files. The recommended way of doing so is adjusting the
227 environment variables in the start-up scripts of your shell. Appropriate
228 Csh and bourne sh scripts are left in
229 @file{buildscripts/out/lilypond-profile} and
230 @file{buildscripts/out/lilypond-login} after compilation.
232 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
233 recommended for comfortable use.
235 @subsection Building documentation
237 You can view the documentation online at
238 @uref{http://www.lilypond.org/stable/Documentation/out-www/}, but you
239 can also build it locally. This process requires a successful compile of
240 lilypond. The documentation is built by issuing
247 Building the website requires some additional tools:
250 @item The netpbm utilities, see @uref{http://netpbm.sourceforge.net/}
251 @item mftrace 1.0 or newer, needed for generating PostScript Type1
252 fonts. Get it from @uref{http://www.cs.uu.nl/~hanwen/mftrace/}. You
253 will need to install some additional packages to get mftrace to work.
256 @section Building LilyPond
258 to install GNU LilyPond, type:
260 gunzip -c lilypond-x.y.z | tar xf -
262 ./configure # run with --help to see appropriate options
265 sh buildscripts/clean-fonts.sh
268 If you are doing an upgrade, you should remove all @file{feta}
269 @code{.pk} and @file{.tfm} files. A script has been provided to do the
270 work for you, see @file{buildscripts/clean-fonts.sh}.
273 If you are not root, you should choose a @code{--prefix} argument that
274 points into your home directory, eg.
277 ./configure --prefix=$HOME/usr
281 In this case, you have to insert the contents of
282 @code{buildscripts/out/lilypond-login} or
283 @code{buildscripts/out/lilypond-profile} into your start up scripts by
288 @subsection Configuring for multiple platforms
290 If you want to build multiple versions of LilyPond with different
291 configuration settings, you can use the @code{--enable-config=CONF}
292 option of configure. You should use @samp{make conf=CONF} to generate
293 the output in @file{out-CONF}. Example: suppose I want to build with
294 and without profiling. Then I'd use the following for the normal
299 ./configure --prefix=$HOME/usr/ --enable-checking
304 and for the profiling version, I specify a different configuration.
308 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
310 make conf=prof install
320 An Emacs mode for entering music and running LilyPond is contained in
321 the source archive as @file{lilypond-mode.el},
322 @file{lilypond-indent.el}, @file{lilypond-font-lock.el} and
323 @file{lilypond.words}.
324 You should install these files to a directory included in your
325 @var{load-path}. File @file{lilypond-init.el} should be placed to
326 @var{load-path}@file{/site-start.d/} or appended to your @file{~/.emacs}
327 or @file{~/.emacs.el}. If you have installed a precompiled LilyPond
328 package, these files can be found in @file{/usr/share/doc/lilypond-x.y.z/}.
330 As a user, you may want add your source path or, e.g., @file{~/site-lisp/}
331 to your @var{load-path}. Append the following line (modified) to your
335 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
339 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode is
340 automatically loaded, you not even need to modify your @code{~/.emacs}
345 A Vim mode for entering music and running LilyPond is contained in
346 the source archive. Append the content of @file{vimrc} to @file{~/.vimrc}
347 to get shortcuts. Install file @file{lilypond.words} to @file{~/.vim/} to
348 get auto-completion. Syntax highlighting you get by installing
349 @file{lilypond.vim} to @file{~/.vim/syntax/} and appending the following
350 to @file{~/.vim/filetype.vim}:
354 if exists("did_load_filetypes")
357 augroup filetypedetect
358 au! BufRead,BufNewFile *.ly setfiletype lilypond
363 @section Compiling for distributions
365 @subsection Red Hat Linux
367 Red Hat 7.x i386 RPMS are available from
368 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}. For running on
369 a Red Hat system you need these packages: guile, tetex, tetex-latex,
370 tetex-dvips, libstdc++, python, ghostscript.
372 You can also compile them yourself. A spec file is in
373 @file{make/out/lilypond.redhat.spec}. This file is distributed along
374 with the sources. You can make the rpm by issuing
377 cp lilypond-x.y.z.tar.gz /usr/src/redhat/SOURCES/
378 tar xfz lilypond-x.y.z.tar.gz
379 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
380 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
384 For compilation on a Red Hat system you need these packages, in
385 addition to the those needed for running: glibc-devel, gcc-c++,
386 libstdc++-devel, guile-devel, flex, bison, texinfo, groff, mftrace,
387 netpbm-progs, autotrace, t1utils.
394 Some LinuxPPC RPMS should available from
395 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
397 A LinuxPPC RPM can be made using the @file{lilypond.redhat.spec} file.
401 Some SUSE RPMS should available from
402 @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.
404 You can also compile a RPM for SUSE yourself. A spec file is in
405 @file{make/out/lilypond.suse.spec}, see the instructions for building
408 You must have the following packages: guile tcsh tetex te_latex te_kpath
409 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
410 gs_serv gs_lib gs_fonts guile
412 @subsection Slackware
414 No precompiled packages for Slackware are available.
416 Problems have been reported with Slackware 7.0; apparently, it ships
417 with a faulty compiler. Do not compile LilyPond with -O2 on this
420 At least on Slackware 8.0, you have to manually specify the paths to the
421 Kpathsea library, see the section on kpathsea
426 Some binaries are available at rpmfind.net. Refer to
427 @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.
429 You can also compile a RPM for Mandrake yourself. A spec file is in
430 @file{make/out/lilypond.mandrake.spec}, see the instructions for building
433 @subsection Debian GNU/Linux
435 A Debian package is also available. You may install it easily by running
436 @command{apt-get} as root:
439 apt-get install lilypond lilypond-doc
442 You can also compile the .deb for Debian yourself, do:
445 apt-get -b source lilypond
448 If you're real impatient, you may even do:
451 cd lilypond-x.y.z # a previous version
452 uscan # download and build latest directly from upstream
456 Debian's @TeX{} installation is a bit short on memory, you may want to
457 increase it like this:
459 --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
460 +++ texmf.cnf Sun Dec 16 23:46:34 2001
462 main_memory.context = 1500000
463 main_memory.mpost = 1000000
464 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
465 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
466 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
467 +extra_mem_top = 1000000 % extra high memory for chars, tokens, etc.
468 +extra_mem_bot = 1000000 % extra low memory for boxes, glue, breakpoints, etc.
470 obj_tab_size.context = 300000
473 % Max number of characters in all strings, including all error messages,
474 % help texts, font names, control sequences. These values apply to TeX and MP.
475 pool_size.context = 750000
478 % Minimum pool space after TeX/MP's own strings; must be at least
479 % 25000 less than pool_size, but doesn't need to be nearly that large.
480 string_vacancies.context = 45000
483 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
484 environment variables if you do not want to or cannot modify
485 @file{/etc/texmf/texmf.cnf}.
490 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
491 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
492 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
493 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
494 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
495 package is now obsolete.
498 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
501 The build scripts are in the subdirectory @file{debian/}; you can
502 make the .deb by doing, for example:
506 # dpkg --purge lilypond lilypond1.3
508 $ tar xzf lilypond-1.4.3.tar.gz
510 $ dch -p -v 1.4.3-0.local.1 "Local build."
513 # dpkg -i ../lilypond_1.4.3*.deb
518 Use command @command{debuild} instead of @command{debuild -B} if you have
519 a very fast machine and want to build the HTML, PS and DVI documentation
522 For compilation on a Debian GNU/Linux system you need these packages,
523 in addition to the those needed for running:
526 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
527 @item libguile<@var{your-libguile-version-here}>-dev
528 @item make, m4, flex, bison
531 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
532 @item dpkg-dev, debhelper, fakeroot
534 @item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
535 in Debian testing/unstable.)
538 Most of these are listed on the @samp{Build-Depends} line in the
539 @file{debian/control} file. To ensure the creation of the lilypond deb is
540 trouble-free, we recommend that you first install the following packages
541 by running \@command{apt-get} as root before building the package:
546 apt-get install task-debian-devel task-c++-dev \
547 python-base libguile6-dev tetex-bin tetex-dev \
548 tetex-extra flex bison texinfo groff gs \
549 netpbm pnmtopng m4 gettext
552 For Debian in development ("unstable", the future 2.3 or 3.0):
555 apt-get install binutils cpp gcc libc6-dev \
556 g++ libstdc++2.10-dev \
557 python-base libguile-dev tetex-bin libkpathsea-dev \
558 tetex-extra flex bison texinfo groff gs \
562 And, just so that old fonts from previous versions of LilyPond won't
563 interfere with your build, you may want to do this before the build too:
566 dpkg --purge lilypond lilypond1.3
571 LilyPond is available through fink, in the unstable cvs distribution.
575 @item Get the Fink package manager from @uref{http://fink.sourceforge.net}
576 @item Get the Lilypond package description by enabling the "unstable" tree
577 in fink and executing @command{fink selfupdate-cvs}.
583 fink install lilypond-unstable
587 That's it! The command should compile and install all LilyPond
588 prerequisites (python, TeX, X11, ghostscript) and then LilyPond
592 @subsection compiling on MacOS X
593 LilyPond has been built on Darwin, to be precise, on:
595 Darwin buoux.aspiratie.nl 5.3 Darwin Kernel Version 5.3: Thu Jan 24
596 22:06:02 PST 2002; root:xnu/xnu-201.19.obj~1/RELEASE_PPC Power Macintosh powerpc
602 Apple Computer, Inc. version gcc-932.1, based on gcc version 2.95.2 19991024 (release)
605 To make sure you have all packages needed to build LilyPond installed,
609 apt-get install bash python guile debianutils flex bison texinfo \
610 ghostscript6 netpbm m4 gettext
619 For more information about @file{apt-get} and @file{fink}, see
620 @uref{http://fink.sf.net,fink.sourceforge.net}.
622 @c brokenness of autoconf; don't ask
623 Then, configure, patch, make and install LilyPond using these commands:
626 CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
627 ./configure --prefix=/sw
628 make -C lily out/parser.hh out/parser.cc out/config.h
629 patch -p0 < darwin.patch
630 make -C lily out/parser.o
631 make DEPENDENCIES_OUTPUT=/dev/null all
635 For installing, you must be root, of course.
637 @c Why isn't this in BUGS (where it belongs?)
640 For help and questions use @email{lilypond-user@@gnu.org}. Please
641 consult the FAQ before mailing your problems. If you find bugs, please
642 send bug reports to @email{bug-lilypond@@gnu.org}.
644 Bugs that are not fault of LilyPond are documented here.
646 @subsection Linking to kpathsea
648 If kpathsea and the corresponding header files are installed in some
649 directory where GCC does not search by default, for example in
650 @file{/usr/local/lib/} and @file{/usr/local/include/} respectively,
651 you have to explicitly tell configure where to find it. To do this,
654 @item @code{rm config.cache}
655 @item @code{export LDFLAGS=-L/usr/share/texmf/lib}
656 @item @code{export CPPFLAGS=-I/usr/share/texmf/include}
657 @item @code{./configure}
659 Once configure has found them, the paths are stored in
660 @file{config.make} and will be used even if you don't have the
661 environment variables set during make.
664 @unnumberedsubsec Gcc-3.0.4
666 Gcc 3.0.4, is a bit flaky. Try downgrading to 2.95.x, or if you're
667 adventurous (see below), upgrading to 3.1.x.
669 @unnumberedsubsec Flex-2.5.4a and gcc-3.x
671 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
672 LilyPond with gcc-3.0 you may do:
675 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
676 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
677 patch -p1 < lexer-gcc-3.0.patch
678 make conf=gcc-3.0 -C lily
681 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
683 @unnumberedsubsec Flex-2.5.4a and gcc-3.1.x
685 Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code. To compile
686 LilyPond with gcc-3.1.1 you may do:
689 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
690 CPPFLAGS=-I$(pwd)/lily/out-gcc-3.1 CC=gcc-3.1 CXX=g++-3.1 \
691 ./configure --enable-config=gcc-3.1
692 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
696 This assumes that the GCC 3.1 binaries are called gcc-3.1 and g++-3.1.
697 Note that this is @strong{not} fixed in Debian/unstable for flex <=
700 @unnumberedsubsec Linux-2.4.0, Guile-1.4 --with-threads
702 There's a bug in certain kernels around version 2.4.0, that is
703 triggered when using Guile 1.4 compiled with pthreads. You'll see
704 random segmentation fault crashes of LilyPond. Upgrade to a newer
705 version of Linux. If you can't do that, you may try to recompiling
706 Guile without threads (YMMV):
709 guile-1.4$ ./configure --without-threads; make all install
712 @unnumberedsubsec OpenBSD
715 @item By default, gcc on OpenBSD doesn't include
716 @file{/usr/local/include} and @file{/usr/local/lib} in the system
717 paths. Depending upon where/how you installed kpathsea and other
718 libraries, you may need to refer to the section ``Linking to
723 @unnumberedsubsec NetBSD
726 @item The flex precompiled in NetBSD-1.4.2 is broken.
727 Download flex-2.5.4a, build, install.
729 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
730 release)) does not include @file{/usr/pkg} paths. Configure using:
733 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
739 @unnumberedsubsec Solaris
742 @item Solaris7, ./configure
744 @file{./configure} needs a POSIX compliant shell. On Solaris7,
745 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
746 is. Please run configure like:
748 CONFIG_SHELL=/bin/ksh ksh -c ./configure
752 CONFIG_SHELL=/bin/bash bash -c ./configure
755 @item Sparc64/Solaris 2.6, GNU make-3.77
757 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
759 @item Sparc64/Solaris 2.6, ld
765 @unnumberedsubsec AIX
770 The following is from the gcc install/SPECIFIC file.
772 Some versions of the AIX binder (linker) can fail with a relocation
773 overflow severe error when the -bbigtoc option is used to link
774 GCC-produced object files into an executable that overflows the TOC.
775 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
776 -BBIGTOC) is available from IBM Customer Support and from its
777 27service.boulder.ibm.com website as PTF U455193.
779 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
780 as and GNU ld will not work properly and one should not configure GCC
781 to use those GNU utilities. Use the native AIX tools which do
782 interoperate with GCC.
785 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
787 LDFLAGS='-Wl,-bbigtoc' ./configure