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 makefilesapplying the patch}.
108 @item If you have the @code{.tar.gz} file of a previous release, you can
110 @uref{http://sourceforge.net/projects/xdelta/, xdelta}.
111 This is much safer than using patches, and is the recommended way.
113 The following command produces @file{lilypond-1.4.3.tar.gz} from
114 @file{lilypond-1.4.2.tar.gz} identical (up to compression dates) to the .3
117 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
121 @subsection Font problems
123 If you are upgrading from a previous version of LilyPond, be sure to
124 remove all old font files. These include @file{.pk} and @file{.tfm} files
125 that may be located in @file{/var/lib/texmf}, @file{/var/spool/texmf},
126 @file{/var/tmp/texmf} or @file{@var{prefix}/share/lilypond/fonts/}. A
127 script automating this has been included, see
128 @file{buildscripts/clean-fonts.sh}.
133 @section Requirements
135 @subsection Compilation
137 You need the following packages to compile Lilypond:
140 @item The GNU c++ compiler (version 2.95.2 or newer).
141 EGCS 1.1 may work, but is no longer supported.
142 Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
144 WARNING: if you choose to upgrade to GCC 3.x, enquire if your
145 distribution supports g++ 3.x and flex. At the time of writing (Fri
146 Jul 5 2002), @strong{no} distribution that we know of ships a flex
147 that generates gcc-3.1.x compliant C++ code.
149 @item Python (version 2.1 or newer).
150 Check out @uref{http://www.python.org, the python website}.
152 @item GUILE (version 1.6.4 or newer).
154 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
156 @item GNU Make (version 3.78 or newer).
158 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
161 @item Flex (version 2.5.4a or newer).
162 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
164 WARNING: plain Flex 2.5.4(a) generates invalid C++ code. GCC 3.x
165 chokes on this. If you wish to use GCC 3.x, make sure that your
166 distribution supports g++ 3.x and flex. For workarounds, see
167 lexer-gcc-3.0.patch and lexer-gcc-3.1.sh in the source directory.
169 @item Bison (version 1.25 or newer).
170 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}.
174 @TeX{} is used as an output backend.
176 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf},
177 @file{.afm}, @file{.tfm}). Make sure you have tetex 1.0 or newer
178 (1.0.6 is known to work). You may need to install a tetex-devel (or
179 tetex-dev or libkpathsea-dev) package too.
181 @item Texinfo (version 4.2 or newer).
182 The documentation of lily is written in texinfo. Check out
183 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
185 @item The geometry package for LaTeX is needed to use ly2dvi.
187 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
188 FTP directory for @code{geometry}}. This package is normally included
189 with the @TeX{} distribution.
191 @item kpathsea, a library for searching (@TeX{}) files. @code{kpathsea} is
192 usually included with your installation of @TeX{}. You may need to
193 install a tetex-devel or tetex-dev package too. If kpathsea is not
194 installed in a directory where the compiler normally looks, read the
195 hints for Slackware below.
197 In the very unlikely case that kpathsea is not available for your
198 platform (i.e., you're not running GNU/Linux, Windows, or any recent
199 UNIX), you can compile LilyPond without kpathsea support. In that case,
200 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
201 configure something like:
205 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
211 @subsection Running requirements
213 GNU LilyPond does use a lot of resources. For operation you need the
218 @item Xdvi and Ghostscript.
219 @item GUILE 1.4, or newer.
221 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
224 For running LilyPond successfully you have to help @TeX{} and MetaFont find
225 various files. The recommended way of doing so is adjusting the
226 environment variables in the start-up scripts of your shell. Appropriate
227 Csh and bourne sh scripts are left in
228 @file{buildscripts/out/lilypond-profile} and
229 @file{buildscripts/out/lilypond-login} after compilation.
231 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
232 recommended for comfortable use.
234 @subsection Building documentation
236 You can view the documentation online at
237 @uref{http://www.lilypond.org/stable/Documentation/out-www/}, but you
238 can also build it locally. This process requires a successful compile of
239 lilypond. The documentation is built by issuing:
244 Building the website requires some additional tools:
247 @item The netpbm utilities, see @uref{http://netpbm.sourceforge.net/}
248 @item mftrace 1.0 or newer, needed for generating PostScript Type1
249 fonts. Get it from @uref{http://www.cs.uu.nl/~hanwen/mftrace/}. You
250 will need to install some additional packages to get mftrace to work.
253 @section Building LilyPond
255 To install GNU LilyPond, type:
257 gunzip -c lilypond-x.y.z | tar xf -
259 ./configure # run with --help to see appropriate options
262 sh buildscripts/clean-fonts.sh
265 If you are doing an upgrade, you should remove all @file{feta}
266 @code{.pk} and @file{.tfm} files. A script has been provided to do the
267 work for you, see @file{buildscripts/clean-fonts.sh}.
270 If you are not root, you should choose a @code{--prefix} argument that
271 points into your home directory, e.g.:
273 ./configure --prefix=$HOME/usr
276 In this case, you have to insert the contents of
277 @code{buildscripts/out/lilypond-login} or
278 @code{buildscripts/out/lilypond-profile} into your start up scripts by
283 @subsection Configuring for multiple platforms
285 If you want to build multiple versions of LilyPond with different
286 configuration settings, you can use the @code{--enable-config=CONF}
287 option of configure. You should use @samp{make conf=CONF} to generate
288 the output in @file{out-CONF}. Example: Suppose I want to build with
289 and without profiling. Then I'd use the following for the normal
293 ./configure --prefix=$HOME/usr/ --enable-checking
298 and for the profiling version, I specify a different configuration:
301 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
303 make conf=prof install
312 An Emacs mode for entering music and running LilyPond is contained in
313 the source archive as @file{lilypond-mode.el},
314 @file{lilypond-indent.el}, @file{lilypond-font-lock.el} and
315 @file{lilypond.words}.
316 You should install these files to a directory included in your
317 @var{load-path}. File @file{lilypond-init.el} should be placed to
318 @var{load-path}@file{/site-start.d/} or appended to your @file{~/.emacs}
319 or @file{~/.emacs.el}. If you have installed a precompiled LilyPond
320 package, these files can be found in @file{/usr/share/doc/lilypond-x.y.z/}.
322 As a user, you may want add your source path or, e.g., @file{~/site-lisp/}
323 to your @var{load-path}. Append the following line (modified) to your
327 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
331 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode is
332 automatically loaded, you not even need to modify your @code{~/.emacs}
337 A Vim mode for entering music and running LilyPond is contained in
338 the source archive. Append the content of @file{vimrc} to @file{~/.vimrc}
339 to get shortcuts. Install file @file{lilypond.words} to @file{~/.vim/} to
340 get auto-completion. Syntax highlighting you get by installing
341 @file{lilypond.vim} to @file{~/.vim/syntax/} and appending the following
342 to @file{~/.vim/filetype.vim}:
346 if exists("did_load_filetypes")
349 augroup filetypedetect
350 au! BufRead,BufNewFile *.ly setfiletype lilypond
355 @section Compiling for distributions
357 @subsection Red Hat Linux
360 You can compile RPMS yourself. For running on a Red Hat system you
361 need these packages: guile, tetex, tetex-latex, tetex-dvips,
362 libstdc++, python, ghostscript. A spec file is in
363 @file{make/out/lilypond.redhat.spec}. This file is distributed along
364 with the sources. You can make the rpm by issuing:
366 cp lilypond-x.y.z.tar.gz /usr/src/redhat/SOURCES/
367 tar xfz lilypond-x.y.z.tar.gz
368 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
369 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
372 For compilation on a Red Hat system you need these packages, in
373 addition to the those needed for running: glibc-devel, gcc-c++,
374 libstdc++-devel, guile-devel, flex, bison, texinfo, groff, mftrace,
375 netpbm-progs, autotrace, t1utils.
379 Some SUSE RPMS should available from
380 @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.
382 You can also compile a RPM for SUSE yourself. A spec file is in
383 @file{make/out/lilypond.suse.spec}, see the instructions for building
386 You must have the following packages: guile tcsh tetex te_latex te_kpath
387 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
388 gs_serv gs_lib gs_fonts guile
390 @subsection Slackware
392 No precompiled packages for Slackware are available.
394 Problems have been reported with Slackware 7.0; apparently, it ships
395 with a faulty compiler. Do not compile LilyPond with -O2 on this
398 At least on Slackware 8.0, you have to manually specify the paths to the
399 Kpathsea library, see the section on kpathsea.
404 Some binaries are available at rpmfind.net. Refer to
405 @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.
407 You can also compile a RPM for Mandrake yourself. A spec file is in
408 @file{make/out/lilypond.mandrake.spec}, see the instructions for building
411 @subsection Debian GNU/Linux
413 A Debian package is also available. You may install it easily by running
414 @command{apt-get} as root:
417 apt-get install lilypond lilypond-doc
420 You can also compile the .deb for Debian yourself, do:
423 apt-get -b source lilypond
426 If you're real impatient, you may even do:
429 cd lilypond-x.y.z # a previous version
430 uscan # download and build latest directly from upstream
434 Debian's @TeX{} installation is a bit short on memory, you may want to
435 increase it like this:
437 --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
438 +++ texmf.cnf Sun Dec 16 23:46:34 2001
440 main_memory.context = 1500000
441 main_memory.mpost = 1000000
442 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
443 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
444 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
445 +extra_mem_top = 1000000 % extra high memory for chars, tokens, etc.
446 +extra_mem_bot = 1000000 % extra low memory for boxes, glue, breakpoints, etc.
448 obj_tab_size.context = 300000
451 % Max number of characters in all strings, including all error messages,
452 % help texts, font names, control sequences. These values apply to TeX and MP.
453 pool_size.context = 750000
456 % Minimum pool space after TeX/MP's own strings; must be at least
457 % 25000 less than pool_size, but doesn't need to be nearly that large.
458 string_vacancies.context = 45000
461 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
462 environment variables if you do not want to or cannot modify
463 @file{/etc/texmf/texmf.cnf}.
465 Alternatively, visit:
468 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
469 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
470 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
471 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
472 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
473 package is now obsolete.
476 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
479 The build scripts are in the subdirectory @file{debian/}; you can
480 make the .deb by doing, for example:
484 # dpkg --purge lilypond lilypond1.3
486 $ tar xzf lilypond-1.4.3.tar.gz
488 $ dch -p -v 1.4.3-0.local.1 "Local build."
491 # dpkg -i ../lilypond_1.4.3*.deb
496 Use command @command{debuild} instead of @command{debuild -B} if you have
497 a very fast machine and want to build the HTML, PS and DVI documentation
500 For compilation on a Debian GNU/Linux system you need these packages,
501 in addition to the those needed for running:
504 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
505 @item libguile<@var{your-libguile-version-here}>-dev
506 @item make, m4, flex, bison
509 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
510 @item dpkg-dev, debhelper, fakeroot
512 @item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
513 in Debian testing/unstable.)
516 Most of these are listed on the @samp{Build-Depends} line in the
517 @file{debian/control} file. To ensure the creation of the lilypond deb is
518 trouble-free, we recommend that you first install the following packages
519 by running \@command{apt-get} as root before building the package:
524 apt-get install task-debian-devel task-c++-dev \
525 python-base libguile6-dev tetex-bin tetex-dev \
526 tetex-extra flex bison texinfo groff gs \
527 netpbm pnmtopng m4 gettext
530 For Debian in development ("unstable", the future 2.3 or 3.0):
533 apt-get install binutils cpp gcc libc6-dev \
534 g++ libstdc++2.10-dev \
535 python-base libguile-dev tetex-bin libkpathsea-dev \
536 tetex-extra flex bison texinfo groff gs \
540 And, just so that old fonts from previous versions of LilyPond won't
541 interfere with your build, you may want to do this before the build too:
544 dpkg --purge lilypond lilypond1.3
549 LilyPond is available through fink, in the unstable cvs distribution.
553 @item Get the Fink package manager from @uref{http://fink.sourceforge.net}.
554 @item Get the Lilypond package description by enabling the "unstable" tree
555 in fink and executing @command{fink selfupdate-cvs}.
561 fink install lilypond-unstable
565 That's it! The command should compile and install all LilyPond
566 prerequisites (python, TeX, X11, ghostscript) and then LilyPond
570 @subsection Compiling on MacOS X
571 LilyPond has been built on Darwin, to be precise, on:
573 Darwin buoux.aspiratie.nl 5.3 Darwin Kernel Version 5.3: Thu Jan 24
574 22:06:02 PST 2002; root:xnu/xnu-201.19.obj~1/RELEASE_PPC Power Macintosh powerpc
580 Apple Computer, Inc. version gcc-932.1, based on gcc version 2.95.2 19991024 (release)
583 To make sure you have all packages needed to build LilyPond installed,
587 apt-get install bash python guile debianutils flex bison texinfo \
588 ghostscript6 netpbm m4 gettext
597 For more information about @file{apt-get} and @file{fink}, see
598 @uref{http://fink.sf.net,fink.sourceforge.net}.
600 @c brokenness of autoconf; don't ask
601 Then, configure, patch, make and install LilyPond using these commands:
604 CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
605 ./configure --prefix=/sw
606 make -C lily out/parser.hh out/parser.cc out/config.h
607 patch -p0 < darwin.patch
608 make -C lily out/parser.o
609 make DEPENDENCIES_OUTPUT=/dev/null all
613 For installing, you must be root, of course.
615 @c Why isn't this in BUGS (where it belongs?)
618 For help and questions use @email{lilypond-user@@gnu.org}. Please
619 consult the FAQ before mailing your problems. If you find bugs, please
620 send bug reports to @email{bug-lilypond@@gnu.org}.
622 Bugs that are not fault of LilyPond are documented here.
624 @subsection Linking to kpathsea
626 If kpathsea and the corresponding header files are installed in some
627 directory where GCC does not search by default, for example in
628 @file{/usr/local/lib/} and @file{/usr/local/include/} respectively,
629 you have to explicitly tell configure where to find it. To do this:
632 @item @code{rm config.cache}
633 @item @code{export LDFLAGS=-L/usr/share/texmf/lib}
634 @item @code{export CPPFLAGS=-I/usr/share/texmf/include}
635 @item @code{./configure}
637 Once configure has found them, the paths are stored in
638 @file{config.make} and will be used even if you don't have the
639 environment variables set during make.
642 @unnumberedsubsec Gcc-3.0.4
644 Gcc 3.0.4, is a bit flaky. Try downgrading to 2.95.x, or if you're
645 adventurous (see below), upgrading to 3.1.x.
647 @unnumberedsubsec Flex-2.5.4a and gcc-3.x
649 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
650 LilyPond with gcc-3.0 you may do:
653 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
654 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
655 patch -p1 < lexer-gcc-3.0.patch
656 make conf=gcc-3.0 -C lily
659 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
661 @unnumberedsubsec Flex-2.5.4a and gcc-3.1.x
663 Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code. To compile
664 LilyPond with gcc-3.1.1 you may do:
667 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
668 CPPFLAGS=-I$(pwd)/lily/out-gcc-3.1 CC=gcc-3.1 CXX=g++-3.1 \
669 ./configure --enable-config=gcc-3.1
670 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
674 This assumes that the GCC 3.1 binaries are called gcc-3.1 and g++-3.1.
675 Note that this is @strong{not} fixed in Debian/unstable for flex <=
678 @unnumberedsubsec Linux-2.4.0, Guile-1.4 --with-threads
680 There's a bug in certain kernels around version 2.4.0, that is
681 triggered when using Guile 1.4 compiled with pthreads. You'll see
682 random segmentation fault crashes of LilyPond. Upgrade to a newer
683 version of Linux. If you can't do that, you may try to recompiling
684 Guile without threads (YMMV):
687 guile-1.4$ ./configure --without-threads; make all install
690 @unnumberedsubsec OpenBSD
693 @item By default, gcc on OpenBSD doesn't include
694 @file{/usr/local/include} and @file{/usr/local/lib} in the system
695 paths. Depending upon where/how you installed kpathsea and other
696 libraries, you may need to refer to the section ``Linking to
701 @unnumberedsubsec NetBSD
704 @item The flex precompiled in NetBSD-1.4.2 is broken.
705 Download flex-2.5.4a, build, install.
707 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
708 release)) does not include @file{/usr/pkg} paths. Configure using:
711 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
717 @unnumberedsubsec Solaris
720 @item Solaris7, ./configure
722 @file{./configure} needs a POSIX compliant shell. On Solaris7,
723 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
724 is. Please run configure like:
726 CONFIG_SHELL=/bin/ksh ksh -c ./configure
730 CONFIG_SHELL=/bin/bash bash -c ./configure
733 @item Sparc64/Solaris 2.6, GNU make-3.77
735 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
737 @item Sparc64/Solaris 2.6, ld
743 @unnumberedsubsec AIX
748 The following is from the gcc install/SPECIFIC file:
750 Some versions of the AIX binder (linker) can fail with a relocation
751 overflow severe error when the -bbigtoc option is used to link
752 GCC-produced object files into an executable that overflows the TOC.
753 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
754 -BBIGTOC) is available from IBM Customer Support and from its
755 27service.boulder.ibm.com website as PTF U455193.
757 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
758 as and GNU ld will not work properly and one should not configure GCC
759 to use those GNU utilities. Use the native AIX tools which do
760 interoperate with GCC.
763 add -Wl,-bbigtoc to USER_LDFLAGS, i.e.:
765 LDFLAGS='-Wl,-bbigtoc' ./configure