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 is
19 also known to run and compile on Windows NT/95/98 as well. More
20 information on this topic can be found at the
21 @uref{http://www.lilypond.org/gnu-windows/, LilyPond on Windows page}.
25 <a name="download-source">
30 Even numbered versions are `stable'. The webpages for the stable version
31 (1.2) reside @uref{http://www.gnu.org/software/lilypond, on the GNU
32 servers}. Big enhancements go into the latest odd numbered version
33 (1.3), 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.
51 Of course, if your platform supports LilyPond, such as Debian GNU/Linux,
52 FreeBSD, OpenBSD or NetBSD, you're encouraged to use the native build
55 For Red Hat Linux and SuSE Linux, @file{.spec} files are included in the
56 tarball; see instructions below.
59 <a name="download-binaries">
64 @subsection Precompiled binaries
66 If you want to track bleeding edge development, try:
69 @item @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond/, Debian
70 GNU/Linux} usually has the latest binaries for the most useful stable
71 and development versions, while
72 @item @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/,
73 Mandrake Cooker} also provides fairly recent versions.
76 Binaries are made available for other popular platforms, but as we need
77 to compile them ourselves, they are not updated for every version
81 @item @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/, Red Hat i386}
82 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE, SuSE}
83 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/,
86 @uref{http://www.lilypond.org/gnu-windows/, Windows}
91 There are two options for upgrading sources.
94 @item if you have an unpacked source tree of a previous version, you
97 @emph{If you upgrade by patching do remember to rerun autoconf after
100 @item if you have the @code{.tar.gz} file of a previous release, you can
102 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
103 This is much safer than using patches, and is the recommended way.
105 The following command produces @file{lilypond-1.4.3.tar.gz} from
106 @file{lilypond-1.4.2.tar.gz} identical (up to compression dates) to the .3
109 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
113 @section Requirements
115 @subsection Compilation
117 You need the following packages to compile Lilypond.
120 @item A reasonably new version of the GNU C++ compiler: EGCS 1.1, GCC 2.95.2 or
121 newer. Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
123 @item Python (version 1.5 or newer).
124 Check out @uref{http://www.python.org, the python website}.
126 @item GUILE (version 1.4 or newer).
128 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
129 Version 1.4 is recommended for better performance.
133 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
136 @item Flex (version 2.5.4a or newer).
137 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
139 @item Bison (version 1.25 or newer).
140 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}
144 @TeX{} is used as an output backend.
146 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf}, @file{.afm}, @file{.tfm}).
147 Make sure you have tetex 1.0 or newer (1.0.6 is known to work). You may
148 need to install a tetex-devel or tetex-dev package too.
150 @item Texinfo (version 4.0 or newer).
151 The documentation of lily is written in texinfo. Check out
152 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
154 @item The geometry package for LaTeX is needed to use ly2dvi.
156 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
157 FTP directory for @code{geometry}}. This package is normally included
158 with the @TeX{} distribution.
160 @item kpathsea, a library for searching (@TeX{}) files. @code{kpathsea} is
161 usually included with your installation of @TeX{}. You may need to install
162 a tetex-devel or tetex-dev package too.
164 In the very unlikely case that kpathsea is not available for your
165 platform (ie, you're not running GNU/Linux, Windows, or any recent
166 UNIX), you can compile LilyPond without kpathsea support. In that case,
167 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
168 configure something like:
171 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
175 @item pktrace, [OPTIONAL], needed for generating PostScript Type1
176 fonts. Get it from @uref{http://www.cs.uu.nl/~hanwen/pktrace/}. You
177 will need to install some additional packages to get pktrace to work.
181 @subsection Running requirements
183 GNU LilyPond does use a lot of resources. For operation you need the
188 @item Xdvi and Ghostscript
189 @item GUILE 1.3.4, or newer. Check out
190 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
193 For running LilyPond successfully you have to help @TeX{} and MetaFont find
194 various files. The recommended way of doing so is adjusting the
195 environment variables in the start-up scripts of your shell. Appropriate
196 Csh and bourne sh scripts are left in
197 @file{buildscripts/out/lilypond-profile} and
198 @file{buildscripts/out/lilypond-login} after compilation.
200 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
201 recommended for comfortable use.
203 @subsection Website requirements
205 The documentation comes in the form of a website. You can view this
206 website on the internet, but you can also build it locally. This process
207 requires a successful compile of lilypond. The website is built
215 Building the website requires some additional tools:
218 @item xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
220 @uref{ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz,the
223 @item pnmtopng. The original is
225 @uref{ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz,in
226 the pnmtopng FTP site}.
228 @item texinfo (a development release)
229 The documentation will build with texinfo-4.0, but if you want split
230 html pages, you're best off using the lates pretest version from
231 @uref{ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz,
233 @uref{ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz,texinfo-4.0b}
236 @section Building LilyPond
238 to install GNU LilyPond, type:
240 gunzip -c lilypond-x.y.z | tar xf -
242 ./configure # run with --help to see appropriate options
245 sh buildscripts/clean-fonts.sh
248 If you are doing an upgrade, you should remove all @file{feta}
249 @code{.pk} and @file{.tfm} files. A script has been provided to do the
250 work for you, see @file{buildscripts/clean-fonts.sh}.
253 If you are not root, you should choose a @code{--prefix} argument that
254 points into your home directory, eg.
257 ./configure --prefix=$HOME/usr
261 In this case, you have to insert the contents of
262 @code{buildscripts/out/lilypond-login} or
263 @code{buildscripts/out/lilypond-profile} into your start up scripts by
268 @subsection Configuring for multiple platforms
270 If you want to build multiple versions of LilyPond with different
271 configuration settings, you can use the @code{--enable-config=CONF}
272 option of configure. You should use @samp{make conf=CONF} to generate
273 the output in @file{out-CONF}. Example: suppose I want to build with
274 and without profiling. Then I'd use the following for the normal build,
277 ./configure --prefix=~ --enable-checking
282 and for the profiling version, I specify a different configuration.
286 ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
288 make conf=prof install
298 An Emacs mode for entering music and running LilyPond is included with
299 the source archive as @file{lilypond-mode.el} and
300 @file{lilypond-font-lock.el}. You should install these files somewhere
301 in your @var{load-path}. If you have installed a precompiled LilyPond
302 package, these files can be found in
303 @file{/usr/share/doc/lilypond-x.y.z/}.
305 Add this to your @file{~/.emacs} or @file{~/.emacs.el}, or install this
306 file in Emacs' @file{site-start.d}:
308 ;;; lilypond-init.el --- Startup code for LilyPond mode
310 (load-library "lilypond-mode.el")
311 (setq auto-mode-alist
312 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
313 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
316 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode is
317 automatically loaded, you not even need to modify your @code{~/.emacs}
320 @section Compiling for distributions
322 @subsection Red Hat Linux
324 Red Hat 7.0 i386 RPMS are available from
325 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
327 You can also compile them yourself. A spec file is in
328 @file{make/out/lilypond.redhat.spec}. This file is distributed along
329 with the sources. You can make the rpm by issuing
332 tar xfz lilypond-x.y.z.tar.gz
333 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
334 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
338 For running on a Red Hat system you need these packages: guile, tetex,
339 tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
341 For compilation on a Red Hat system you need these packages, in addition
342 to the those needed for running: glibc-devel, gcc-c++, libstdc++-devel,
343 guile-devel, flex, bison, texinfo, groff, pktrace.
350 Some LinuxPPC RPMS should available from
351 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
353 A LinuxPPC RPM can be made using the @file{lilypond.redhat.spec} file.
357 Some SUSE RPMS should available from
358 @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.
360 You can also compile a RPM for SUSE yourself. A spec file is in
361 @file{make/out/lilypond.suse.spec}, see the instructions for building
364 You must have the following packages: guile tcsh tetex te_latex te_kpath
365 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
366 gs_serv gs_lib gs_fonts guile
368 @subsection Slackware
370 No precompiled packages for Slackware are available.
372 Problems have been reported with Slackware 7.0; apparently, it ships
373 with a faulty compiler. Do not compile LilyPond with -O2 on this
378 Some binaries are available at rpmfind.net. Refer to
379 @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.
381 You can also compile a RPM for Mandrake yourself. A spec file is in
382 @file{make/out/lilypond.mandrake.spec}, see the instructions for building
385 @subsection Debian GNU/Linux
387 A Debian package is also available. You may install it easily by running
388 @command{apt-get} as root:
391 apt-get install lilypond lilypond-doc
394 You can also compile the .deb for Debian yourself, do:
397 apt-get -b source lilypond
400 If you're real impatient, you may even do:
403 cd lilypond-x.y.z # a previous version
404 uscan # download and build latest directly from upstream
408 Debian's @TeX{} installation is a bit short on memory, you may want to
409 increase it like this:
411 --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
412 +++ texmf.cnf Sun Dec 16 23:46:34 2001
414 main_memory.context = 1500000
415 main_memory.mpost = 1000000
416 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
417 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
418 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
419 +extra_mem_top = 1000000 % extra high memory for chars, tokens, etc.
420 +extra_mem_bot = 1000000 % extra low memory for boxes, glue, breakpoints, etc.
422 obj_tab_size.context = 300000
425 % Max number of characters in all strings, including all error messages,
426 % help texts, font names, control sequences. These values apply to TeX and MP.
427 pool_size.context = 750000
430 % Minimum pool space after TeX/MP's own strings; must be at least
431 % 25000 less than pool_size, but doesn't need to be nearly that large.
432 string_vacancies.context = 45000
435 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
436 environment variables if you do not want to or cannot modify
437 @file{/etc/texmf/texmf.cnf}.
442 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
443 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
444 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
445 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
446 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
447 package is now obsolete.
450 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
453 The build scripts are in the subdirectory @file{debian/}; you can
454 make the .deb by doing, for example:
458 # dpkg --purge lilypond lilypond1.3
460 $ tar xzf lilypond-1.4.3.tar.gz
462 $ dch -p -v 1.4.3-0.local.1 "Local build."
465 # dpkg -i ../lilypond_1.4.3*.deb
470 Use command @command{debuild} instead of @command{debuild -B} if you have
471 a very fast machine and want to build the HTML, PS and DVI documentation
474 For compilation on a Debian GNU/Linux system you need these packages,
475 in addition to the those needed for running:
478 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
479 @item libguile<@var{your-libguile-version-here}>-dev
480 @item make, m4, flex, bison
483 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
484 @item dpkg-dev, debhelper, fakeroot
486 @item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
487 in Debian testing/unstable.)
490 Most of these are listed on the @samp{Build-Depends} line in the
491 @file{debian/control} file. To ensure the creation of the lilypond deb is
492 trouble-free, we recommend that you first install the following packages
493 by running \@command{apt-get} as root before building the package:
498 apt-get install task-debian-devel task-c++-dev \
499 python-base libguile6-dev tetex-bin tetex-dev \
500 tetex-extra flex bison texinfo groff gs \
501 netpbm pnmtopng m4 gettext
504 For Debian in development ("unstable", the future 2.3 or 3.0):
507 apt-get install binutils cpp gcc libc6-dev \
508 g++ libstdc++2.10-dev \
509 python-base libguile-dev tetex-bin libkpathsea-dev \
510 tetex-extra flex bison texinfo groff gs \
514 And, just so that old fonts from previous versions of LilyPond won't
515 interfere with your build, you may want to do this before the build too:
518 dpkg --purge lilypond lilypond1.3
523 LilyPond has been built on Darwin, to be precise, on:
525 Darwin buoux.aspiratie.nl 5.3 Darwin Kernel Version 5.3: Thu Jan 24
526 22:06:02 PST 2002; root:xnu/xnu-201.19.obj~1/RELEASE_PPC Power Macintosh powerpc
532 Apple Computer, Inc. version gcc-932.1, based on gcc version 2.95.2 19991024 (release)
535 To make sure you have all packages needed to build LilyPond installed,
539 apt-get install bash python guile debianutils flex bison texinfo \
540 ghostscript6 netpbm m4 gettext
549 For more information about @file{apt-get} and @file{fink}, see
550 @uref{http://fink.sf.net,fink.sourceforge.net}.
552 @c brokenness of autoconf; don't ask
553 Then, configure, patch, make and install LilyPond using these commands:
556 CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
557 ./configure --prefix=/sw
558 make -C lily out/parser.hh out/parser.cc out/config.h
559 patch -p0 < darwin.patch
560 make -C lily out/parser.o
561 make DEPENDENCIES_OUTPUT=/dev/null all
565 For installing, you must be root, of course.
567 @c Why isn't this in BUGS (where it belongs?)
570 For help and questions use @email{lilypond-user@@gnu.org}. Please
571 consult the FAQ before mailing your problems. If you find bugs, please
572 send bug reports to @email{bug-lilypond@@gnu.org}.
574 Bugs that are not fault of LilyPond are documented here.
576 @unnumberedsubsec FLex-2.5.4a and gcc-3.0
578 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
579 LilyPond with gcc-3.0 you may do:
582 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
583 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
584 patch -p1 < lexer-gcc-3.0.patch
585 make conf=gcc-3.0 -C lily
588 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
590 @unnumberedsubsec Linux-2.4.0, Guile-1.4 --with-threads
592 There's a bug in certain kernels around version 2.4.0, that is
593 triggered when using Guile 1.4 compiled with pthreads. You'll see
594 random segmentation fault crashes of LilyPond. Upgrade to a newer
595 version of Linux. If you can't do that, you may try to recompiling
596 Guile without threads (YMMV):
599 guile-1.4$ ./configure --without-threads; make all install
603 @unnumberedsubsec NetBSD
606 @item The flex precompiled in NetBSD-1.4.2 is broken.
607 Download flex-2.5.4a, build, install.
609 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
610 release)) does not include @file{/usr/pkg} paths. Configure using:
613 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
619 @unnumberedsubsec Solaris:
622 @item Sparc64/Solaris 2.6, GNU make-3.77
624 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
626 @item Sparc64/Solaris 2.6, ld
632 @unnumberedsubsec AIX
637 The following is from the gcc install/SPECIFIC file.
639 Some versions of the AIX binder (linker) can fail with a relocation
640 overflow severe error when the -bbigtoc option is used to link
641 GCC-produced object files into an executable that overflows the TOC.
642 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
643 -BBIGTOC) is available from IBM Customer Support and from its
644 27service.boulder.ibm.com website as PTF U455193.
646 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
647 as and GNU ld will not work properly and one should not configure GCC
648 to use those GNU utilities. Use the native AIX tools which do
649 interoperate with GCC.
652 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
654 LDFLAGS='-Wl,-bbigtoc' ./configure