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{ftp://ftp.lilypond.org/pub/LilyPond/gnu-windows/, LilyPond on Windows
21 <a name="download-source">
26 @subsection source code
29 If you want to compile LilyPond from source, download here:
31 @item Download development releases from
32 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/development/, by FTP} and
33 @uref{http://ftp.cs.uu.nl/pub/GNU/LilyPond/development/, by HTTP}.
34 @item @uref{ftp://sca.uwaterloo.ca/pub/, ftp (Canadian mirror)}
35 @item at @code{lilypond.org} by
36 @uref{ftp://ftp.lilypond.org/pub/LilyPond/, FTP} and
37 @uref{http://www.lilypond.org/ftp/, HTTP}.
40 Installing and compiling requires many additional packages, which are
41 listed in the @uref{Documentation/topdocs/out-www/INSTALL.html,
42 installation instructions}.
45 <a name="download-binaries">
52 Binaries are available, but are not updated for every version released.
54 @item @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/, RedHat i386}
55 @item @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc, LinuxPPC}
57 @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond,
58 Debian GNU/Linux Stable}
60 @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond1.3,
61 Debian GNU/Linux Unstable}
62 @item @uref{http://home.austin.rr.com/jbr/jeff/lilypond/, Windows Stable}
63 @c @item @uref{ftp://ftp.lilypond.org/pub/lilypond/gnu-windows, Windows
65 @uref{http://www.lilypond.org/gnu-windows, Windows Testing}
71 There are two options for upgrading sources.
74 @item if you have an unpacked source tree of a previous version, you
77 @emph{If you upgrade by patching do remember to rerun autoconf after
80 @item if you have the @code{.tar.gz} file of a previous release, you can
82 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
83 This is much safer than using patches, and is the recommended way.
85 The following command produces @file{lilypond-1.3.122.tar.gz} from
86 @file{lilypond-1.3.121} identical (up to compression dates) to the .122
89 xdelta patch lilypond-1.3.121-1.3.122.xd lilypond-1.3.121.tar.gz
95 @subsection Compilation
97 You need the following packages to compile Lilypond.
100 @item A reasonably new C++ compiler: EGCS 1.1, GCC 2.95.2 or
101 newer. Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
104 Check out @uref{http://www.python.org, the python website}.
106 @item GUILE 1.3.4 or newer, check out
107 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
108 Version 1.4 is recommended for better performance.
112 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
115 @item Flex (version 2.5.4a or newer).
116 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
118 @item Bison (version 1.25 or newer).
119 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}
123 @TeX{} is used as an output backend.
125 Also, @TeX{}'s libkpathsea is used to find the fonts (.mf, .afm, .tfm).
126 Make sure you have tetex 1.0 or newer (1.0.6 is known to work). You may
127 need to install a tetex-devel or tetex-dev package too.
129 @item Texinfo (version 4.0 or newer).
130 The documentation of lily is written in texinfo. Check out
131 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
133 @item The geometry package for LaTeX is needed to use ly2dvi.
135 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
136 FTP directory for @code{geometry}}. This package is normally included
137 with the @TeX{} distribution.
139 @item MetaPost, needed for generating PostScript fonts. Please
140 note that tetex-0.4pl8 (included with Red Hat 5.x) does not include
141 @file{mfplain.mp}, which is needed for producing the scalable font
144 If you don't have MetaPost and don't want to use PostScript output, then
145 edit @file{mf/GNUmakefile}, removing the line saying @code{PFA_FILES=}.
147 @item kpathsea, a library for searching (TeX) files. @code{kpathsea} is
148 usually included with your installation of TeX. You may need to install
149 a tetex-devel or tetex-dev package too.
151 In the very unlikely case that kpathsea is not available for your
152 platform (ie, you're not running GNU/Linux, Windows, or any recent
153 UNIX), you can compile LilyPond without kpathsea support. In that case,
154 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
155 configure something like:
158 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
163 @subsection Running requirements
165 GNU LilyPond does use a lot of resources. For operation you need the
170 @item Xdvi and ghostscript
171 @item GUILE 1.3.4, or newer. Check out
172 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
175 For running LilyPond successfully you have to help TeX and MetaFont find
176 various files. The recommended way of doing so is adjusting the
177 environment variables in the start-up scripts of your shell. Appropriate
178 Csh and bourne sh scripts are left in
179 @file{buildscripts/out/lilypond-profile} and
180 @file{buildscripts/out/lilypond-login} after compilation.
182 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
183 recommended for comfortable use.
185 @subsection Website requirements
187 The documentation comes in the form of a website. You can view this
188 website on the internet, but you can also build it locally. This process
189 requires a successful compile of lilypond. The website is built
197 Building the website requires some additional tools:
200 @item xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
202 @uref{ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz,the
205 @item pnmtopng. The original is
207 @uref{ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz,in
208 the pnmtopng FTP site}.
210 @item @uref{http://www.lri.fr/~filliatr/ftp/bibtex2html/, Bibtex2html}, or
211 @uref{http://www.uni-koblenz.de/ag-ki/ftp/bib2html/, Bib2html}.
212 Bibtex2html is available in debian, while bib2html is in some rpm based
214 Bib2html, in turn depends on man2html for proper installation.
215 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}.
217 The website will build without bib converter utility, but you will not
218 see our hypertextified bibliography.
222 @section Building LilyPond
224 to install GNU LilyPond, type:
226 gunzip -c lilypond-x.y.z | tar xf -
228 ./configure # run with --help to see appropriate options
231 sh buildscripts/clean-fonts.sh
234 If you are doing an upgrade, you should remove all @file{feta}
235 @code{.pk} and @file{.tfm} files. A script has been provided to do the
236 work for you, see @file{buildscripts/clean-fonts.sh}.
239 If you are not root, you should choose a @code{--prefix} argument that
240 points into your home directory, eg.
243 ./configure --prefix=$HOME/usr
247 In this case, you have to insert the contents of
248 @code{buildscripts/out/lilypond-login} or
249 @code{buildscripts/out/lilypond-profile} into your start up scripts by
254 @subsection Configuring for multiple platforms
256 If you want to build multiple versions of LilyPond with different
257 configuration settings, you can use the @code{--enable-config=CONF}
258 option of configure. You should use @samp{make conf=CONF} to generate
259 the output in @file{out-CONF}. Example: suppose I want to build with
260 and without profiling. Then I'd use the following for the normal build,
263 ./configure --prefix=~ --enable-checking
268 and for the profiling version, I specify a different configuration.
272 ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
274 make conf=prof install
284 An emacs mode for LilyPond is included with the source archive as
285 @file{lilypond-mode.el} and @file{lilypond-font-lock.el}. If you have
286 an RPM, it is in @file{/usr/share/doc/lilypond-X/}. You have to install
289 Add this to your @file{~/.emacs} or @file{~/.emacs.el}:
291 (load-library "lilypond-mode.el")
292 (setq auto-mode-alist
293 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
294 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
297 If you have the latest LilyPond-1.3.x Debian package, LilyPond-mode is
298 automatically loaded, so you need not modify your @code{~/.emacs} file.
300 @section Compiling for distributions
302 @subsection Red Hat Linux
304 Red Hat 7.0 i386 RPMS are available from
305 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/RedHat/}.
307 You can also compile them yourself. A spec file is in
308 @file{make/out/redhat.spec}. This file is distributed along with the
309 sources. You can make the rpm by issuing
312 rpm -tb lilypond-x.y.z.tar.gz
313 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
317 For running on a Red Hat system you need these packages: guile, tetex,
318 tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
320 For compilation on a Red Hat system you need these packages, in addition
321 to the those needed for running: glibc-devel, gcc-c++, libstdc++-devel,
322 guile-devel, flex, bison, texinfo, tetex-devel, groff,
327 You can also compile them yourself. A spec file is in
328 @file{make/out/suse.spec}. This file is distributed along with the
331 You must have the following packages: guile tcsh tetex te_latex te_kpath
332 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
333 gs_serv gs_lib gs_fonts guile
339 @subsection Debian GNU/Linux
341 A Debian package is also available. You may install it easily by using
345 apt-get install lilypond1.3
351 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
352 @item @uref{http://ftp.debian.org/debian/pool/main/l/lilypond1.3/,http://ftp.debian.org/debian/pool/main/l/lilypond1.3/}
353 for latest package uploaded to Debian unstable;
354 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
355 for latest semi-unofficial build of LilyPond 1.3.121 for Debian 2.2r2 (potato) users.
356 The official stable Debian 2.2r2 is stuck with the old LilyPond-1.3.24.
359 You may contact Anthony Fok @email{foka@@debian.org} for more information.
361 The build scripts are in the subdirectory @file{debian/}; you can
362 make the .deb by doing, for example:
366 # dpkg --purge lilypond lilypond1.3
368 $ tar xzf lilypond-1.3.122.tar.gz
369 $ cd lilypond-1.3.122
370 $ dch -p -v 1.3.122-0.local.1 "Local build."
373 # dpkg -i ../lilypond1.3_1.3.122*.deb
378 For compilation on a Debian GNU/Linux system you need these packages,
379 in addition to the those needed for running:
382 @item g++, cpp, libc6-dev, libstdc++<your-libstdc++-version-here>-dev
383 @item libguile<your-libguile-version-here>-dev
384 @item make, m4, flex, bison
386 @item groff, texinfo, bibtex2html (not in 2.2r2)
387 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
388 @item dpkg-dev, debhelper, fakeroot
389 @item gs, netpbm, pnmtopng
392 Most of these are listed on the Build-Depends line in the
393 debian/control file. To ensure the creation of the lilypond deb is
394 trouble-free, we recommend that you first install the following packages
395 before starting dpkg-buildpackage by running apt-get as root.
397 For Debian 2.2 (or 2.2r2, 2.2r3):
400 apt-get install task-debian-devel task-c++-dev \
401 python-base libguile6-dev tetex-bin tetex-dev \
402 tetex-extra flex bison texinfo groff gs \
403 netpbm pnmtopng m4 gettext
406 For Debian in development ("unstable", the future 2.3 or 3.0):
409 apt-get install task-debian-devel task-c++-dev \
410 python-base libguile9-dev tetex-bin libkpathsea-dev \
411 tetex-extra flex bison texinfo bibtex2html groff gs \
412 netpbm pnmtopng m4 gettext
415 And, just so that old fonts from previous versions of LilyPond won't
416 interfere with your build, you may want to do this before the build too:
419 dpkg --purge lilypond lilypond1.3
426 For help and questions use @email{help-gnu-music@@gnu.org} and
427 @email{gnu-music-discuss@@gnu.org}. Please consult the faq before
428 mailing your problems. If you find bugs, please send bug reports to
429 @email{bug-gnu-music@@gnu.org}.
431 Bugs that are not fault of LilyPond are documented here.
433 @unnumberedsubsec NetBSD
436 @item The flex precompiled in NetBSD-1.4.2 is broken.
437 Download flex-2.5.4a, build, install.
439 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
440 release)) does not include @file{/usr/pkg} paths. Configure using:
443 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
449 @unnumberedsubsec Solaris:
452 @item Sparc64/Solaris 2.6, GNU make-3.77
454 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
456 @item Sparc64/Solaris 2.6, ld
462 @unnumberedsubsec AIX
467 The following is from the gcc install/SPECIFIC file.
469 Some versions of the AIX binder (linker) can fail with a relocation
470 overflow severe error when the -bbigtoc option is used to link
471 GCC-produced object files into an executable that overflows the TOC.
472 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
473 -BBIGTOC) is available from IBM Customer Support and from its
474 27service.boulder.ibm.com website as PTF U455193.
476 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
477 as and GNU ld will not work properly and one should not configure GCC
478 to use those GNU utilities. Use the native AIX tools which do
479 interoperate with GCC.
482 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
484 LDFLAGS='-Wl,-bbigtoc' ./configure