3 @comment node-name, next, previous, up\input texinfo @c -*-texinfo-*-
4 @setfilename INSTALL.info
5 @settitle INSTALL - compiling and installing GNU LilyPond
9 @chapter Compiling and installing on Unix
13 <a name="download-source">
18 Even numbered versions are `stable'. The webpages for the stable version
19 (1.4) reside @uref{http://www.gnu.org/software/lilypond, on the GNU
20 servers}. Big enhancements go into the latest odd numbered version
21 (1.5), whose webpages are on @uref{http://www.lilypond.org/,the lilypond
24 Building LilyPond is an involved process. We advise to use binary
25 packages if these are available for your platform.
29 @subsection Source code
31 Download source tarballs from here:
33 @item Download development releases from
34 @uref{ftp://ftp.lilypond.org/pub/LilyPond/} by FTP and
35 @uref{http://www.lilypond.org/ftp/} by HTTP.
36 @item @uref{ftp://sca.uwaterloo.ca/pub/} by FTP (Canadian mirror).
40 Use Xdelta to patch tarballs, e.g. to patch
41 @file{lilypond-1.4.2.tar.gz} to @file{lilypond-1.4.3.tar.gz}, do
43 xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
46 For information on packaging and CVS, see
47 @uref{http://lilypond.org/}, under ``develoment''.
50 @subsection Precompiled binaries
52 Check out @uref{http://lilypond.org} for up to date information on
56 @subsection Font problems
58 If you are upgrading from a previous version of LilyPond, be sure to
59 remove all old font files. These include @file{.pk} and @file{.tfm} files
60 that may be located in @file{/var/lib/texmf}, @file{/var/spool/texmf},
61 @file{/var/tmp/texmf} or @file{@var{prefix}/share/lilypond/fonts/}. A
62 script automating this has been included, see
63 @file{buildscripts/clean-fonts.sh}.
70 @subsection Compilation
72 You need the following packages to compile LilyPond:
76 @uref{http://gcc.gnu.org/,
77 The GNU c++ compiler} (version 3.1 or newer).
78 EGCS and 2.x are known to cause crashes.
80 @item @uref{http://www.python.org,Python} (version 2.1 or newer).
82 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version 1.6.0 or newer).
84 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
86 @item @uref{http://www.gnu.org/software/flex/,Flex} (version 2.5.4a or newer).
88 WARNING: plain Flex 2.5.4(a) generates invalid C++ code. GCC 3.x
89 chokes on this. If you wish to use GCC 3.x, make sure that your
90 distribution supports g++ 3.x and flex. For workarounds, see
91 lexer-gcc-3.1.sh in the source directory.
93 @item @uref{http://www.gnu.org/software/bison/,Bison} (version 1.25 or
94 newer, but not 1.50 or 1.75).
98 @TeX{} is used as an output backend.
100 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf},
101 @file{.afm}, @file{.tfm}). Make sure you have tetex 1.0 or newer
102 (1.0.6 is known to work). You may need to install a tetex-devel (or
103 tetex-dev or libkpathsea-dev) package too.
105 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.2 or newer).
108 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,geometry
111 This package is normally included with the @TeX{} distribution.
113 @item kpathsea, a library for searching (@TeX{}) files.
117 usually included with your installation of @TeX{}. You may need to
118 install a tetex-devel or tetex-dev package too. If kpathsea is not
119 installed in a directory where the compiler normally looks, read the
120 hints for Slackware below.
122 In the very unlikely case that kpathsea is not available for your
123 platform (i.e., you're not running GNU/Linux, Windows, or any recent
124 UNIX), you can compile LilyPond without kpathsea support. In that case,
125 you'll probably have to indicate where @TeX{}'s tfm files live. Invoke
126 configure something like:
130 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
137 @subsection Running requirements
139 GNU LilyPond does use a lot of resources. For operation you need the
144 @item Xdvi and Ghostscript.
145 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} 1.6.0, or newer.
148 For running LilyPond successfully
150 You have to help @TeX{} and MetaFont find LilyPond support
151 files. After compiling, scripts to do this can be found in
152 @file{buildscripts/out/lilypond-profile} and
153 @file{buildscripts/out/lilypond-login}.
155 @subsection Building documentation
157 You can view the documentation online at
158 @uref{http://www.lilypond.org/doc/}, but you can also build it
159 locally. This process requires a successful compile of lilypond. The
160 documentation is built by issuing:
165 Building the website requires some additional tools:
168 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities} see
170 @item @uref{http://www.cs.uu.nl/~hanwen/mftrace/,mftrace} (1.0.17 or
173 You will need to install some additional packages to get mftrace to
177 The HTML files can be installed into the standard documentation path
181 make out=www web-install
185 @section Building LilyPond
187 To install GNU LilyPond, type
189 gunzip -c lilypond-x.y.z | tar xf -
191 ./configure # run with --help to see appropriate options
194 sh buildscripts/clean-fonts.sh
197 If, in addition, you want to generate PDF files of your scores and have
198 installed mftrace, type
201 make install-pfa-fonts
205 PFA versions of the fonts for the latest LilyPond version can also be
206 obtained from the internet: download the .deb file that corresponds to
210 wget http://ftp.us.debian.org/debian/pool/main/l/lilypond/lilypond_1.8.0-1_i386.deb
211 @c ar p lilypond_1.8.0-1_i386.deb data.tar.gz | tar -C / -zxf - '.*.pfa' '.*.map'
212 ar x lilypond_1.8.0-1_i386.deb data.tar.gz
213 tar -C / -zxf data.tar.gz /usr/share/lilypond/1.8.0/fonts/type1/
214 tar -C / -zxf data.tar.gz /usr/share/lilypond/1.8.0/dvips/
217 If you are installing LilyPond somewhere else, unpack the appropriate
218 files as shown, and move them to the appropriate paths. Of course, the
219 .deb version number should correspond to what you are installing.
221 If you are doing an upgrade, you should remove all @file{feta}
222 @code{.pk} and @code{.tfm} files. A script has been provided to do the
223 work for you, see @file{buildscripts/clean-fonts.sh}.
225 If you are not root, you should choose a @code{--prefix} argument that
226 points into your home directory, e.g.:
228 ./configure --prefix=$HOME/usr
231 In this case, you have to insert the contents of
232 @code{buildscripts/out/lilypond-login} or
233 @code{buildscripts/out/lilypond-profile} into your start up scripts by
238 @subsection Configuring for multiple platforms
240 If you want to build multiple versions of LilyPond with different
241 configuration settings, you can use the @code{--enable-config=CONF}
242 option of configure. You should use @samp{make conf=CONF} to generate
243 the output in @file{out-CONF}. Example: Suppose I want to build with
244 and without profiling. Then I'd use the following for the normal
248 ./configure --prefix=$HOME/usr/ --enable-checking
253 and for the profiling version, I specify a different configuration:
256 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
258 make conf=prof install
265 An Emacs mode for entering music and running LilyPond is contained in
266 the source archive as @file{lilypond-mode.el},
267 @file{lilypond-indent.el}, @file{lilypond-font-lock.el} and
268 @file{lilypond.words}. You should install these files to a directory
269 included in your @var{load-path}. File @file{lilypond-init.el} should
270 be placed to @var{load-path}@file{/site-start.d/} or appended to your
271 @file{~/.emacs} or @file{~/.emacs.el}.
273 As a user, you may want add your source path or, e.g., @file{~/site-lisp/}
274 to your @var{load-path}. Append the following line (modified) to your
278 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
285 A Vim mode for entering music and running LilyPond is contained in
286 the source archive. Append the content of @file{vimrc} to @file{~/.vimrc}
287 to get shortcuts. Install file @file{lilypond.words} to @file{~/.vim/} to
288 get auto-completion. Syntax highlighting you get by installing
289 @file{lilypond.vim} to @file{~/.vim/syntax/} and appending the following
290 to @file{~/.vim/filetype.vim}:
294 if exists("did_load_filetypes")
297 augroup filetypedetect
298 au! BufRead,BufNewFile *.ly setfiletype lilypond
307 For help and questions use @email{lilypond-user@@gnu.org}. Please
308 consult the FAQ before mailing your problems. If you find bugs, please
309 send bug reports to @email{bug-lilypond@@gnu.org}.
311 Bugs that are not fault of LilyPond are documented here.
313 @subsection Linking to kpathsea
315 If kpathsea and the corresponding header files are installed in some
316 directory where GCC does not search by default, for example in
317 @file{/usr/local/lib/} and @file{/usr/local/include/} respectively,
318 you have to explicitly tell configure where to find it. To do this:
321 @item @code{rm config.cache}
322 @item @code{export LDFLAGS=-L/usr/share/texmf/lib}
323 @item @code{export CPPFLAGS=-I/usr/share/texmf/include}
324 @item @code{./configure}
326 Once configure has found them, the paths are stored in
327 @file{config.make} and will be used even if you don't have the
328 environment variables set during make.
331 @unnumberedsubsec Gcc-3.0.4
333 Gcc 3.0.4 is flaky; upgrade GCC.
335 @unnumberedsubsec Flex-2.5.4a and gcc-3.x
337 Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code. To compile
338 LilyPond with gcc-3.1.1 you may do
341 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
342 CPPFLAGS=-I$(pwd)/lily/out-gcc-3.1 CC=gcc-3.1 CXX=g++-3.1 \
343 ./configure --enable-config=gcc-3.1
344 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
349 @unnumberedsubsec OpenBSD
353 Refer to the section ``Linking to kpathsea'': GCC on OpenBSD doesn't
354 set include paths for kpathsea.
357 @unnumberedsubsec NetBSD
360 @item The flex precompiled in NetBSD-1.4.2 is broken.
361 Upgrade to flex-2.5.4a.
365 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
366 release)) does not include @file{/usr/pkg} paths. Configure it using:
369 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
376 @unnumberedsubsec Solaris
379 @item Solaris7, ./configure
381 @file{./configure} needs a POSIX compliant shell. On Solaris7,
382 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
383 is. Please run configure like:
385 CONFIG_SHELL=/bin/ksh ksh -c ./configure
389 CONFIG_SHELL=/bin/bash bash -c ./configure
392 @item Sparc64/Solaris 2.6, ld
398 @unnumberedsubsec AIX
403 The following is from the gcc install/SPECIFIC file:
405 Some versions of the AIX binder (linker) can fail with a relocation
406 overflow severe error when the -bbigtoc option is used to link
407 GCC-produced object files into an executable that overflows the TOC.
408 A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
409 -BBIGTOC) is available from IBM Customer Support and from its
410 27service.boulder.ibm.com website as PTF U455193.
412 Binutils does not support AIX 4.3 (at least through release 2.9). GNU
413 as and GNU ld will not work properly and one should not configure GCC
414 to use those GNU utilities. Use the native AIX tools which do
415 interoperate with GCC.
418 add -Wl,-bbigtoc to USER_LDFLAGS, i.e.:
420 LDFLAGS='-Wl,-bbigtoc' ./configure