1 \input texinfo @c -*-texinfo-*-
2 @setfilename INSTALL.info
3 @settitle INSTALL - compiling and installing GNU LilyPond
8 @chapter INSTALL - compiling and installing GNU LilyPond
12 You can get the latest version of LilyPond at
13 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/,
14 ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/}.
16 There are three options for downloading sources.
19 @item if you don't have any version, then you can download
20 the entire @file{.tar.gz} file.
22 @item if you have an unpacked source tree of a previous version, you
26 @emph{If you upgrade by patching do remember to rerun autoconf after
30 @item if you have the @code{.tar.gz} file of a previous release, you can
32 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
33 This is much safer than using normal diffs, and is the recommended way.
35 The following command produces @file{lilypond-1.3.122.tar.gz} from
36 @file{lilypond-1.3.121} identical (up to compression dates) to the .122
39 xdelta patch lilypond-1.3.121-1.3.122.xd lilypond-1.3.121.tar.gz
43 @section Build requirements
45 This document describes how to build LilyPond on Unix platforms. It is
46 also known to run and compile on Windows NT/95/98 as well. More
47 information on this topic can be found at the
48 @uref{http://appel.lilypond.org/lilypond/gnu-windows/, LilyPond on Windows
51 You need the following packages to compile Lilypond.
54 @item A reasonably new C++ compiler: EGCS 1.1, GCC 2.95.2 or
55 newer. Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
58 Check out @uref{http://www.python.org, the python website}.
60 @item GUILE 1.3.4 or newer, check out
61 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
62 Version 1.4 is recommended for better performance.
66 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
69 @item Flex (version 2.5.4a or newer).
70 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
72 @item Bison (version 1.25 or newer).
73 Check out @uref{http://www.gnu.org/software/bison/,the bison webpage}
77 @TeX{} is used as an output backend.
79 Also, @TeX{}'s libkpathsea is used to find the fonts (.mf, .afm, .tfm).
80 Make sure you have tetex 1.0 or newer (1.0.6 is known to work). You may
81 need to install a tetex-devel or tetex-dev package too.
83 @item Texinfo (version 4.0 or newer).
84 The documentation of lily is written in texinfo. Check out
85 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
87 @item The geometry package for LaTeX is needed to use ly2dvi.
89 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
90 FTP directory for @code{geometry}}. This package is normally included
91 with the @TeX{} distribution.
93 @item MetaPost, needed for generating PostScript fonts. Please
94 note that tetex-0.4pl8 (included with Red Hat 5.x) does not include
95 @file{mfplain.mp}, which is needed for producing the scalable font
98 If you don't have MetaPost and don't want to use PostScript output, then
99 edit @file{mf/GNUmakefile}, removing the line saying @code{PFA_FILES=}.
101 @item kpathsea, a library for searching (TeX) files. @code{kpathsea} is
102 usually included with your installation of TeX. You may need to install
103 a tetex-devel or tetex-dev package too.
105 In the very unlikely case that kpathsea is not available for your
106 platform (ie, you're not running GNU/Linux, Windows, or any recent
107 UNIX), you can compile LilyPond without kpathsea support. In that case,
108 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
109 configure something like:
112 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
117 @section Running requirements
119 GNU LilyPond does use a lot of resources. For operation you need the
124 @item Xdvi and ghostscript
125 @item GUILE 1.3.4, or newer. Check out
126 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
129 For running LilyPond successfully you have to help TeX and MetaFont find
130 various files. The recommended way of doing so is adjusting the
131 environment variables in the start-up scripts of your shell. Appropriate
132 Csh and bourne sh scripts are left in
133 @file{buildscripts/out/lilypond-profile} and
134 @file{buildscripts/out/lilypond-login} after compilation.
136 LilyPond is a big and slow program. A fast CPU and plenty of RAM is
137 recommended for comfortable use.
139 @section Website requirements
141 The documentation comes in the form of a website. You can view this
142 website on the internet, but you can also build it locally. This process
143 requires a successful compile of lilypond. The website is built
151 Building the website requires some additional tools:
154 @item xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
156 @uref{ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz,the
159 @item pnmtopng. The original is
161 @uref{ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz,in
162 the pnmtopng FTP site}.
164 @item @uref{http://www.lri.fr/~filliatr/ftp/bibtex2html/, Bibtex2html}, or
165 @uref{http://www.uni-koblenz.de/ag-ki/ftp/bib2html/, Bib2html}.
166 Bibtex2html is available in debian, while bib2html is in some rpm based
168 Bib2html, in turn depends on man2html for proper installation.
169 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}.
171 The website will build without bib converter utility, but you will not
172 see our hypertextified bibliography.
176 @section Configuring and compiling
178 to install GNU LilyPond, type:
180 gunzip -c lilypond-x.y.z | tar xf -
182 ./configure # run with --help to see appropriate options
185 sh buildscripts/clean-fonts.sh
188 If you are doing an upgrade, you should remove all @file{feta}
189 @code{.pk} and @file{.tfm} files. A script has been provided to do the
190 work for you, see @file{buildscripts/clean-fonts.sh}.
193 If you are not root, you should choose a @code{--prefix} argument that
194 points into your home directory, eg.
197 ./configure --prefix=$HOME/usr
201 In this case, you have to insert the contents of
202 @code{buildscripts/out/lilypond-login} or
203 @code{buildscripts/out/lilypond-profile} into your start up scripts by
208 @section Configuring for multiple platforms
210 If you want to build multiple versions of LilyPond with different
211 configuration settings, you can use the @code{--enable-config=CONF}
212 option of configure. You should use @samp{make conf=CONF} to generate
213 the output in @file{out-CONF}. Example: suppose I want to build with
214 and without profiling. Then I'd use the following for the normal build,
217 ./configure --prefix=~ --enable-checking
222 and for the profiling version, I specify a different configuration.
226 ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
228 make conf=prof install
240 An emacs mode for LilyPond is included with the source archive as
241 @file{lilypond-mode.el} and @file{lilypond-font-lock.el}. If you have
242 an RPM, it is in @file{/usr/share/doc/lilypond-X/}. You have to install
245 Add this to your ~/.emacs or ~/.emacs.el:
247 (load-library "lilypond-mode.el")
248 (setq auto-mode-alist
249 (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
250 (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
253 If you have the latest LilyPond-1.3.x Debian package, LilyPond-mode is
254 automatically loaded, so you need not modify your @code{~/.emacs} file.
257 @section Red Hat Linux
259 Red Hat 7.0 i386 RPMS are available from
260 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/RedHat/}.
262 You can also compile them yourself. A spec file is in
263 @file{make/out/lilypond.spec}. This file is distributed along with the
264 sources. You can make the rpm by issuing
267 rpm -tb lilypond-x.y.z.tar.gz
268 rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
272 For running on a Red Hat system you need these packages: guile, tetex,
273 tetex-dvips, libstdc++, python, ghostscript.
275 For compilation on a Red Hat system you need these packages, in addition
276 to the those needed for running: glibc-devel, gcc-c++, libstdc++-devel,
277 guile-devel, flex, bison, texinfo, tetex-devel, groff, libgr-progs.
281 [TODO: document this]
283 Install @code{tetex}, @code{te_mpost}, @code{te_kpath}.
290 @section Debian GNU/Linux
292 A Debian package is also available. You may install it easily by using
296 apt-get install lilypond1.3
302 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
303 @item @uref{http://ftp.debian.org/debian/pool/main/l/lilypond1.3/,http://ftp.debian.org/debian/pool/main/l/lilypond1.3/}
304 for latest package uploaded to Debian unstable;
305 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
306 for latest semi-unofficial build of LilyPond 1.3.121 for Debian 2.2r2 (potato) users.
307 The official stable Debian 2.2r2 is stuck with the old LilyPond-1.3.24.
310 You may contact Anthony Fok @email{foka@@debian.org} for more information.
312 The build scripts are in the subdirectory @file{debian/}; you can
313 make the .deb by doing, for example:
317 # dpkg --purge lilypond lilypond1.3
319 $ tar xzf lilypond-1.3.122.tar.gz
320 $ cd lilypond-1.3.122
321 $ dch -p -v 1.3.122-0.local.1 "Local build."
324 # dpkg -i ../lilypond1.3_1.3.122*.deb
329 For compilation on a Debian GNU/Linux system you need these packages,
330 in addition to the those needed for running:
333 @item g++, cpp, libc6-dev, libstdc++<your-libstdc++-version-here>-dev
334 @item libguile<your-libguile-version-here>-dev
335 @item make, m4, flex, bison
337 @item groff, texinfo, bibtex2html (not in 2.2r2)
338 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
339 @item dpkg-dev, debhelper, fakeroot
340 @item gs, netpbm, pnmtopng
343 Most of these are listed on the Build-Depends line in the
344 debian/control file. To ensure the creation of the lilypond deb is
345 trouble-free, we recommend that you first install the following packages
346 before starting dpkg-buildpackage by running apt-get as root.
348 For Debian 2.2 (or 2.2r2, 2.2r3):
351 apt-get install task-debian-devel task-c++-dev \
352 python-base libguile6-dev tetex-bin tetex-dev \
353 tetex-extra flex bison texinfo groff gs \
354 netpbm pnmtopng m4 gettext
357 For Debian in development ("unstable", the future 2.3 or 3.0):
360 apt-get install task-debian-devel task-c++-dev \
361 python-base libguile9-dev tetex-bin libkpathsea-dev \
362 tetex-extra flex bison texinfo bibtex2html groff gs \
363 netpbm pnmtopng m4 gettext
366 And, just so that old fonts from previous versions of LilyPond won't
367 interfere with your build, you may want to do this before the build too:
370 dpkg --purge lilypond lilypond1.3
377 For help and questions use @email{help-gnu-music@@gnu.org} and
378 @email{gnu-music-discuss@@gnu.org}. Please consult the faq before
379 mailing your problems. If you find bugs, please send bug reports to
380 @email{bug-gnu-music@@gnu.org}.
382 Bugs that are not fault of LilyPond are documented here.
387 @item The flex precompiled in NetBSD-1.4.2 is broken.
388 Download flex-2.5.4a, build, install.
390 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
391 release)) does not include @file{/usr/pkg} paths. Configure using:
394 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
403 @item Sparc64/Solaris 2.6, GNU make-3.77
405 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
408 @item Sparc64/Solaris 2.6, ld
419 The following is from the gcc install/SPECIFIC file.
421 Some versions of the AIX binder (linker) can fail with a relocation
422 overflow severe error when the -bbigtoc option is used to link
423 GCC-produced object files into an executable that overflows the TOC.
424 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
425 -BBIGTOC) is available from IBM Customer Support and from its
426 27service.boulder.ibm.com website as PTF U455193.
428 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
429 as and GNU ld will not work properly and one should not configure GCC
430 to use those GNU utilities. Use the native AIX tools which do
431 interoperate with GCC.
434 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
436 LDFLAGS='-Wl,-bbigtoc' ./configure