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/}.
396 @subsection Debian GNU/Linux
398 A Debian package is also available. You may install it easily by running
399 @command{apt-get} as root:
402 apt-get install lilypond lilypond-doc
406 Debian's @TeX{} installation is a bit short on memory, you may want to
407 increase it like this:
409 --- /etc/texmf/texmf.cnf.dpkg Sun Jan 28 14:12:14 2001
410 +++ /etc/texmf/texmf.cnf Fri Apr 27 11:09:35 2001
412 main_memory.context = 1500000
413 main_memory.mpost = 1000000
414 main_memory = 263000 % words of inimemory available; also applies to inimf&mp
415 -extra_mem_top = 0 % extra high memory for chars, tokens, etc.
416 -extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
417 +extra_mem_top = 100000 % extra high memory for chars, tokens, etc.
418 +extra_mem_bot = 100000 % extra low memory for boxes, glue, breakpoints, etc.
420 obj_tab_size.context = 256000
424 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
425 environment variables if you do not want to or cannot modify
426 @file{/etc/texmf/texmf.cnf}.
431 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
432 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
433 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
434 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
435 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
436 package is now obsolete.
439 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
442 The build scripts are in the subdirectory @file{debian/}; you can
443 make the .deb by doing, for example:
447 # dpkg --purge lilypond lilypond1.3
449 $ tar xzf lilypond-1.4.3.tar.gz
451 $ dch -p -v 1.4.3-0.local.1 "Local build."
454 # dpkg -i ../lilypond_1.4.3*.deb
459 Use command @command{debuild} instead of @command{debuild -B} if you have
460 a very fast machine and want to build the HTML, PS and DVI documentation
463 For compilation on a Debian GNU/Linux system you need these packages,
464 in addition to the those needed for running:
467 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
468 @item libguile<@var{your-libguile-version-here}>-dev
469 @item make, m4, flex, bison
472 @item bibtex2html (not in Debian 2.2)
473 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
474 @item dpkg-dev, debhelper, fakeroot
476 @item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
477 in Debian testing/unstable.)
480 Most of these are listed on the @samp{Build-Depends} line in the
481 @file{debian/control} file. To ensure the creation of the lilypond deb is
482 trouble-free, we recommend that you first install the following packages
483 by running \@command{apt-get} as root before building the package:
488 apt-get install task-debian-devel task-c++-dev \
489 python-base libguile6-dev tetex-bin tetex-dev \
490 tetex-extra flex bison texinfo groff gs \
491 netpbm pnmtopng m4 gettext
494 For Debian in development ("unstable", the future 2.3 or 3.0):
497 apt-get install task-debian-devel task-c++-dev \
498 python-base libguile9-dev tetex-bin libkpathsea-dev \
499 tetex-extra flex bison texinfo bibtex2html groff gs \
503 And, just so that old fonts from previous versions of LilyPond won't
504 interfere with your build, you may want to do this before the build too:
507 dpkg --purge lilypond lilypond1.3
514 For help and questions use @email{lilypond-user@@gnu.org}. Please
515 consult the FAQ before mailing your problems. If you find bugs, please
516 send bug reports to @email{bug-lilypond@@gnu.org}.
518 Bugs that are not fault of LilyPond are documented here.
520 @unnumberedsubsec FLex-2.5.4a and gcc-3.0
522 Flex 2.5.4a does not produce g++-3.0 compliant C++ code. To compile
523 LilyPond with gcc-3.0 you may do:
526 CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
527 make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
528 patch -p1 < lexer-gcc-3.0.patch
529 make conf=gcc-3.0 -C lily
532 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
534 @unnumberedsubsec NetBSD
537 @item The flex precompiled in NetBSD-1.4.2 is broken.
538 Download flex-2.5.4a, build, install.
540 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
541 release)) does not include @file{/usr/pkg} paths. Configure using:
544 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
550 @unnumberedsubsec Solaris:
553 @item Sparc64/Solaris 2.6, GNU make-3.77
555 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
557 @item Sparc64/Solaris 2.6, ld
563 @unnumberedsubsec AIX
568 The following is from the gcc install/SPECIFIC file.
570 Some versions of the AIX binder (linker) can fail with a relocation
571 overflow severe error when the -bbigtoc option is used to link
572 GCC-produced object files into an executable that overflows the TOC.
573 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
574 -BBIGTOC) is available from IBM Customer Support and from its
575 27service.boulder.ibm.com website as PTF U455193.
577 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
578 as and GNU ld will not work properly and one should not configure GCC
579 to use those GNU utilities. Use the native AIX tools which do
580 interoperate with GCC.
583 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
585 LDFLAGS='-Wl,-bbigtoc' ./configure