1 \input texinfo @c -*-texinfo-*-
2 @setfilename INSTALL.info
3 @settitle INSTALL - compiling and installing GNU LilyPond
10 @chapter INSTALL - compiling and installing GNU LilyPond
13 This document describes how to build LilyPond on Unix platforms. It is
14 also known to run and compile on Windows NT/95/98 as well. More
15 information on this topic can be found at the
16 @uref{http://www.lilypond.org/gnu-windows/, LilyPond on Windows page}.
20 <a name="download-source">
25 Even numbered versions are `stable'. The webpages for the stable version
26 (1.2) reside @uref{http://www.gnu.org/software/lilypond, on the GNU
27 servers}. Big enhancements go into the latest odd numbered version
28 (1.3), whose webpages are on @uref{http://www.lilypond.org/,the lilypond
31 @subsection Source code
33 If you want to compile LilyPond from source, download here:
35 @item Download development releases from
36 @c Hmm, these won't show up in lilypond.org/stats
37 @c Otoh, lilypond.org is not updated when release mail arrives
38 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/} by FTP and
39 @uref{http://ftp.cs.uu.nl/pub/GNU/LilyPond/}, by HTTP.
40 @item @uref{ftp://sca.uwaterloo.ca/pub/} by FTP (Canadian mirror)
41 @item at @code{lilypond.org}
42 @uref{ftp://ftp.lilypond.org/pub/LilyPond/} by FTP and
43 @uref{http://www.lilypond.org/ftp/} by HTTP.
46 Of course, if your platform supports LilyPond, such as Debian GNU/Linux,
47 FreeBSD, OpenBSD or NetBSD, you're encouraged to use the native build
50 For Red Hat Linux and SuSE Linux, @file{.spec} files are included in the
51 tarball; see instructions below.
54 <a name="download-binaries">
59 @subsection Precompiled binaries
61 If you want to track bleeding edge development, try:
64 @item @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond/, Debian
65 GNU/Linux} usually has the latest binaries for the most useful stable
66 and development versions, while
67 @item @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/,
68 Mandrake Cooker} also provides fairly recent versions.
71 Binaries are made available for other popular platforms, but as we need
72 to compile them ourselves, they are not updated for every version
76 @item @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/, Red Hat i386}
77 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE, SuSE}
78 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/,
81 @uref{http://www.lilypond.org/gnu-windows/, Windows}
86 There are two options for upgrading sources.
89 @item if you have an unpacked source tree of a previous version, you
92 @emph{If you upgrade by patching do remember to rerun autoconf after
95 @item if you have the @code{.tar.gz} file of a previous release, you can
97 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
98 This is much safer than using patches, and is the recommended way.
100 The following command produces @file{lilypond-1.4.3.tar.gz} from
101 @file{lilypond-1.4.2.tar.gz} identical (up to compression dates) to the .3
104 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
108 @section Requirements
110 @subsection Compilation
112 You need the following packages to compile Lilypond.
115 @item A reasonably new C++ compiler: EGCS 1.1, GCC 2.95.2 or
116 newer. Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
119 Check out @uref{http://www.python.org, the python website}.
121 @item GUILE 1.3.4 or newer, check out
122 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
123 Version 1.4 is recommended for better performance.
127 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
130 @item Flex (version 2.5.4a or newer).
131 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
133 @item Bison (version 1.25 or newer).
134 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}
138 @TeX{} is used as an output backend.
140 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf}, @file{.afm}, @file{.tfm}).
141 Make sure you have tetex 1.0 or newer (1.0.6 is known to work). You may
142 need to install a tetex-devel or tetex-dev package too.
144 @item Texinfo (version 4.0 or newer).
145 The documentation of lily is written in texinfo. Check out
146 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
148 @item The geometry package for LaTeX is needed to use ly2dvi.
150 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
151 FTP directory for @code{geometry}}. This package is normally included
152 with the @TeX{} distribution.
154 @item MetaPost, needed for generating PostScript fonts. Please
155 note that tetex-0.4pl8 (included with Red Hat 5.x) does not include
156 @file{mfplain.mp}, which is needed for producing the scalable font
159 If you don't have MetaPost and don't want to use PostScript output, then
160 edit @file{mf/GNUmakefile}, removing the line saying @code{PFA_FILES=}.
162 @item kpathsea, a library for searching (@TeX{}) files. @code{kpathsea} is
163 usually included with your installation of @TeX{}. You may need to install
164 a tetex-devel or tetex-dev package too.
166 In the very unlikely case that kpathsea is not available for your
167 platform (ie, you're not running GNU/Linux, Windows, or any recent
168 UNIX), you can compile LilyPond without kpathsea support. In that case,
169 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
170 configure something like:
173 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
178 @subsection Running requirements
180 GNU LilyPond does use a lot of resources. For operation you need the
185 @item Xdvi and Ghostscript
186 @item GUILE 1.3.4, or newer. Check out
187 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
190 For running LilyPond successfully you have to help @TeX{} and MetaFont find
191 various files. The recommended way of doing so is adjusting the
192 environment variables in the start-up scripts of your shell. Appropriate
193 Csh and bourne sh scripts are left in
194 @file{buildscripts/out/lilypond-profile} and
195 @file{buildscripts/out/lilypond-login} after compilation.
197 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
198 recommended for comfortable use.
200 @subsection Website requirements
202 The documentation comes in the form of a website. You can view this
203 website on the internet, but you can also build it locally. This process
204 requires a successful compile of lilypond. The website is built
212 Building the website requires some additional tools:
215 @item xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
217 @uref{ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz,the
220 @item pnmtopng. The original is
222 @uref{ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz,in
223 the pnmtopng FTP site}.
225 @item @uref{http://www.lri.fr/~filliatr/ftp/bibtex2html/, Bibtex2html}, or
226 @uref{http://www.uni-koblenz.de/ag-ki/ftp/bib2html/, Bib2html}.
227 Bibtex2html is available in debian, while bib2html is in some rpm based
229 Bib2html, in turn depends on man2html for proper installation.
230 man2html can be had from @uref{http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05,http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05}.
232 The website will build without bib converter utility, but you will not
233 see our hypertextified bibliography.
235 @item texinfo (a development release)
236 The documentation will build with texinfo-4.0, but if you want split
237 html pages, you're best off using the lates pretest version from
238 @uref{ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz,
240 @uref{ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz,texinfo-4.0b}
243 @section Building LilyPond
245 to install GNU LilyPond, type:
247 gunzip -c lilypond-x.y.z | tar xf -
249 ./configure # run with --help to see appropriate options
252 sh buildscripts/clean-fonts.sh
255 If you are doing an upgrade, you should remove all @file{feta}
256 @code{.pk} and @file{.tfm} files. A script has been provided to do the
257 work for you, see @file{buildscripts/clean-fonts.sh}.
260 If you are not root, you should choose a @code{--prefix} argument that
261 points into your home directory, eg.
264 ./configure --prefix=$HOME/usr
268 In this case, you have to insert the contents of
269 @code{buildscripts/out/lilypond-login} or
270 @code{buildscripts/out/lilypond-profile} into your start up scripts by
275 @subsection Configuring for multiple platforms
277 If you want to build multiple versions of LilyPond with different
278 configuration settings, you can use the @code{--enable-config=CONF}
279 option of configure. You should use @samp{make conf=CONF} to generate
280 the output in @file{out-CONF}. Example: suppose I want to build with
281 and without profiling. Then I'd use the following for the normal build,
284 ./configure --prefix=~ --enable-checking
289 and for the profiling version, I specify a different configuration.
293 ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
295 make conf=prof install
305 An Emacs mode for entering music and running LilyPond is included with
306 the source archive as @file{lilypond-mode.el} and
307 @file{lilypond-font-lock.el}. You should install these files somewhere
308 in your @var{load-path}. If you have installed a precompiled LilyPond
309 package, these files can be found in
310 @file{/usr/share/doc/lilypond-x.y.z/}.
312 Add this to your @file{~/.emacs} or @file{~/.emacs.el}, or install this
313 file in Emacs' @file{site-start.d}:
315 ;;; lilypond-init.el --- Startup code for LilyPond mode
317 (load-library "lilypond-mode.el")
318 (setq auto-mode-alist
319 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
320 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
323 If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode is
324 automatically loaded, you not even need to modify your @code{~/.emacs}
327 @section Compiling for distributions
329 @subsection Red Hat Linux
331 Red Hat 7.0 i386 RPMS are available from
332 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
334 You can also compile them yourself. A spec file is in
335 @file{make/out/lilypond.redhat.spec}. This file is distributed along
336 with the sources. You can make the rpm by issuing
339 tar xfz lilypond-x.y.z.tar.gz
340 rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
341 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
345 For running on a Red Hat system you need these packages: guile, tetex,
346 tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
348 For compilation on a Red Hat system you need these packages, in addition
349 to the those needed for running: glibc-devel, gcc-c++, libstdc++-devel,
350 guile-devel, flex, bison, texinfo, tetex-devel, groff,
356 There appears to be a problem with the Xdvi shipped with Red Hat 7.1.
357 Symptoms: Xdvi responds very sluggishly or hangs while viewing
358 lilypond output. The cause for this problem is unknown; you are advised
359 to recompile Xdvi from source.
364 Some LinuxPPC RPMS should available from
365 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
367 A LinuxPPC RPM can be made using the @file{lilypond.redhat.spec} file.
371 Some SUSE RPMS should available from
372 @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.
374 You can also compile a RPM for SUSE yourself. A spec file is in
375 @file{make/out/lilypond.suse.spec}, see the instructions for building
378 You must have the following packages: guile tcsh tetex te_latex te_kpath
379 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
380 gs_serv gs_lib gs_fonts guile
382 @subsection Slackware
384 No precompiled packages for Slackware are available.
386 Problems have been reported with Slackware 7.0; apparently, it ships
387 with a faulty compiler. Do not compile LilyPond with -O2 on this
392 Some binaries are available at rpmfind.net. Refer to
393 @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.
395 You can also compile a RPM for Mandrake yourself. A spec file is in
396 @file{make/out/lilypond.mandrake.spec}, see the instructions for building
399 @subsection Debian GNU/Linux
401 A Debian package is also available. You may install it easily by running
402 @command{apt-get} as root:
405 apt-get install lilypond lilypond-doc
408 You can also compile the .deb for Debian yourself, do:
411 apt-get -b source lilypond
414 If you're real impatient, you may even do:
417 cd lilypond-x.y.z # a previous version
418 uscan # download and build latest directly from upstream
422 Debian's @TeX{} installation is a bit short on memory, you may want to
423 increase it like this:
425 --- /etc/texmf/texmf.cnf.dpkg Sun Jan 28 14:12:14 2001
426 +++ /etc/texmf/texmf.cnf Fri Apr 27 11:09:35 2001
428 main_memory.context = 1500000
429 main_memory.mpost = 1000000
430 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
431 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
432 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
433 +extra_mem_top = 100000 % extra high memory for chars, tokens, etc.
434 +extra_mem_bot = 100000 % extra low memory for boxes, glue, breakpoints, etc.
436 obj_tab_size.context = 256000
440 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
441 environment variables if you do not want to or cannot modify
442 @file{/etc/texmf/texmf.cnf}.
447 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
448 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
449 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
450 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
451 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
452 package is now obsolete.
455 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
458 The build scripts are in the subdirectory @file{debian/}; you can
459 make the .deb by doing, for example:
463 # dpkg --purge lilypond lilypond1.3
465 $ tar xzf lilypond-1.4.3.tar.gz
467 $ dch -p -v 1.4.3-0.local.1 "Local build."
470 # dpkg -i ../lilypond_1.4.3*.deb
475 Use command @command{debuild} instead of @command{debuild -B} if you have
476 a very fast machine and want to build the HTML, PS and DVI documentation
479 For compilation on a Debian GNU/Linux system you need these packages,
480 in addition to the those needed for running:
483 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
484 @item libguile<@var{your-libguile-version-here}>-dev
485 @item make, m4, flex, bison
488 @item bibtex2html (not in Debian 2.2)
489 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
490 @item dpkg-dev, debhelper, fakeroot
492 @item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
493 in Debian testing/unstable.)
496 Most of these are listed on the @samp{Build-Depends} line in the
497 @file{debian/control} file. To ensure the creation of the lilypond deb is
498 trouble-free, we recommend that you first install the following packages
499 by running \@command{apt-get} as root before building the package:
504 apt-get install task-debian-devel task-c++-dev \
505 python-base libguile6-dev tetex-bin tetex-dev \
506 tetex-extra flex bison texinfo groff gs \
507 netpbm pnmtopng m4 gettext
510 For Debian in development ("unstable", the future 2.3 or 3.0):
513 apt-get install task-debian-devel task-c++-dev \
514 python-base libguile9-dev tetex-bin libkpathsea-dev \
515 tetex-extra flex bison texinfo bibtex2html groff gs \
519 And, just so that old fonts from previous versions of LilyPond won't
520 interfere with your build, you may want to do this before the build too:
523 dpkg --purge lilypond lilypond1.3
530 For help and questions use @email{lilypond-user@@gnu.org}. Please
531 consult the FAQ before mailing your problems. If you find bugs, please
532 send bug reports to @email{bug-lilypond@@gnu.org}.
534 Bugs that are not fault of LilyPond are documented here.
536 @unnumberedsubsec FLex-2.5.4a and gcc-3.0
538 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
539 LilyPond with gcc-3.0 you may do:
542 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
543 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
544 patch -p1 < lexer-gcc-3.0.patch
545 make conf=gcc-3.0 -C lily
548 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
550 @unnumberedsubsec NetBSD
553 @item The flex precompiled in NetBSD-1.4.2 is broken.
554 Download flex-2.5.4a, build, install.
556 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
557 release)) does not include @file{/usr/pkg} paths. Configure using:
560 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
566 @unnumberedsubsec Solaris:
569 @item Sparc64/Solaris 2.6, GNU make-3.77
571 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
573 @item Sparc64/Solaris 2.6, ld
579 @unnumberedsubsec AIX
584 The following is from the gcc install/SPECIFIC file.
586 Some versions of the AIX binder (linker) can fail with a relocation
587 overflow severe error when the -bbigtoc option is used to link
588 GCC-produced object files into an executable that overflows the TOC.
589 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
590 -BBIGTOC) is available from IBM Customer Support and from its
591 27service.boulder.ibm.com website as PTF U455193.
593 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
594 as and GNU ld will not work properly and one should not configure GCC
595 to use those GNU utilities. Use the native AIX tools which do
596 interoperate with GCC.
599 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
601 LDFLAGS='-Wl,-bbigtoc' ./configure