1 \input texinfo @c -*-texinfo-*-
2 @setfilename INSTALL.info
3 @settitle INSTALL - compiling and installing GNU LilyPond
5 @documentencoding utf-8
13 @chapter Compiling and installing on Unix
17 <a name="download-source">
22 Even numbered minor versions are `stable' (2.6, 2.8, etc), while odd
23 version are development releases (2.7, 2.9, etc). Building LilyPond
24 is an involved process. If possible
25 @uref{http://lilypond.org/install,download a precompiled binary} for
28 @subsection Source code
33 @uref{http://lilypond.org/download/} by HTTP.
35 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
37 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
39 git clone git://git.sv.gnu.org/lilypond.git
42 The repository does not contain generated files. To create
49 For information on packaging, see @uref{http://lilypond.org/devel}.
51 @subsection Precompiled binary packages
53 Check out @uref{http://lilypond.org/web/install/} for up to date
54 information on binary packages for your platform.
60 @subsection Compilation
62 In addition to the packages needed for running Lilypond (see below),
63 you need the following extra packages for building.
65 When installing a binary package FOO, you may need to install the
66 FOO-devel, libFOO-dev or FOO-dev package too.
70 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
72 @item New Century Schoolbook fonts, as PFB files. These are shipped
73 with X11 and Ghostscript, and are named @file{c059033l.pfb}
74 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}
76 @item @uref{http://www.xs4all.nl/~hanwen/mftrace/,mftrace} (1.1.19 or
79 You will need to install some additional packages to get mftrace to
82 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
83 (version 1.8.2 or newer). If you are installing binary packages, you
84 may need to install guile-devel or guile-dev or libguile-dev too.
86 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.8 or newer).
89 @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 4.x or
92 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
94 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
96 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
98 @item @uref{http://www.gnu.org/software/flex/,Flex}
100 @item @uref{http://www.perl.org/,Perl}
102 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}
104 @item All packages required for running, including development packages with
105 header files and libraries.
109 @subsection Running requirements
111 Running LilyPond requires proper installation of the following
116 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
117 @item @uref{http://www.freetype.org/,FontConfig} (version 2.2).
118 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
119 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
120 (version 1.8.2 or newer), or patch 1.8.1 with
121 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
122 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
123 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
124 newer. 8.50 recommended)
125 @item Dejaview. (This is normally installed by default)
128 International fonts are required to create music with international text
132 @subsection Building documentation
134 You can view the documentation online at
135 @uref{http://lilypond.org/doc/}, but you can also build it locally.
136 This process requires a successful compile of lilypond. The
137 documentation is built by issuing
144 Building the website requires some additional tools and packages
147 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
149 @item International fonts (see input/regression/utf-8.ly for hints
150 about which font packages are necessary for your platform)
151 @item Ghostscript, 8.50 with the patch from
152 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
154 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
157 The HTML files can be installed into the standard documentation path
162 make out=www web-install
166 @section Testing LilyPond
169 <a name="testing"></a>
172 LilyPond comes with an extensive suite that excercises the entire
173 program. This suite can be used to automatically check the impact of a
174 change. This is done as follows
178 @emph{## apply your changes, compile}
182 This will leave an HTML page @file{out/test-results/index.html}. This
183 page shows all the important differences that your change introduced,
184 whether in the layout, MIDI, performance or error reporting.
189 make test-redo @emph{## redo files differing from baseline}
190 make test-clean @emph{## remove all test results}
194 and then run @code{make check} again.
196 For tracking memory usage as part of this test, you will need GUILE
197 CVS; especially the following patch:
198 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
200 For checking the coverage of the test suite, do the following
203 ./buildscripts/build-coverage.sh
204 @emph{# uncovered files, least covered first}
205 python ./buildscripts/coverage.py --summary out-cov/*.cc
206 @emph{# consecutive uncovered lines, longest first}
207 python ./buildscripts/coverage.py --uncovered out-cov/*.cc
210 @section Building LilyPond
212 To install GNU LilyPond, type
215 gunzip -c lilypond-x.y.z | tar xf -
217 ./configure # run with --help for applicable options
223 If you are not root, you should choose a @code{--prefix} argument that
224 points into your home directory, e.g.
227 ./configure --prefix=$HOME/usr
232 @subsection Configuring for multiple platforms
234 If you want to build multiple versions of LilyPond with different
235 configuration settings, you can use the @code{--enable-config=CONF}
236 option of configure. You should use @samp{make conf=CONF} to generate
237 the output in @file{out-CONF}. Example: Suppose you want to build
238 with and without profiling, then use the following for the normal
243 ./configure --prefix=$HOME/usr/ --enable-checking
249 and for the profiling version, specify a different configuration
253 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
255 make conf=prof install
262 An Emacs mode for entering music and running LilyPond is contained in
263 the source archive in the @file{elisp} directory. Do @command{make
264 install} to install it to @var{elispdir}. The file @file{lilypond-init.el}
265 should be placed to @var{load-path}@file{/site-start.d/} or appended
266 to your @file{~/.emacs} or @file{~/.emacs.el}.
268 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
269 your @var{load-path} by appending the following line (as modified) to your
271 @c any reason we do not advise: (push "~/site-lisp" load-path)
274 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
281 A Vim mode for entering music and running LilyPond is contained in the
282 source archive in @code{$VIM} directory.
284 The LilyPond file type is detected if the file @file{~/.vim/filetype.vim} @c
285 has the following content
288 if exists("did_load_filetypes")
291 augroup filetypedetect
292 au! BufNewFile,BufRead *.ly setf lilypond
297 Please include this path by appending the following line to your
302 set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
307 where $@{LILYPOND_VERSION@} is your lilypond version. If Lilypond was not
308 installed in @file{/usr/local/}, then change this path accordingly.
313 For help and questions use @email{lilypond-user@@gnu.org}. Send bug
314 reports to @email{bug-lilypond@@gnu.org}.
316 Bugs that are not fault of LilyPond are documented here.
318 @subsection Bison 1.875
320 There is a bug in bison-1.875: compilation fails with "parse error
321 before `goto'" in line 4922 due to a bug in bison. To fix, please
322 recompile bison 1.875 with the following fix
326 $ cd lily; make out/parser.cc
327 $ vi +4919 out/parser.cc
328 # append a semicolon to the line containing "__attribute__ ((__unused__))
335 @unnumberedsubsec MacOS X
337 For Fink, use the following command to compile.
340 export GUILE=guile-1.6
341 export GUILE_CONFIG=guile-1.6-config
342 export PKG_CONFIG_PATH=/sw/lib/freetype219/lib/pkgconfig/:/sw/lib/fontconfig2/lib/pkgconfig/
346 @unnumberedsubsec Solaris
349 @item Solaris7, ./configure
351 @file{./configure} needs a POSIX compliant shell. On Solaris7,
352 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
353 is. Run configure like
356 CONFIG_SHELL=/bin/ksh ksh -c ./configure
362 CONFIG_SHELL=/bin/bash bash -c ./configure
368 To use system fonts, dejaview must be installed. With the default
369 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
371 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
372 following line just after the @code{<fontconfig>} line. (Adjust as necessary
376 <dir>/usr/X11R6/lib/X11/fonts</dir>
382 @section International fonts
384 On MacOs X, all fonts are installed by default. However, finding all
385 system fonts requires a bit of configuration; see
386 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
387 this post} on the @code{lilypond-user} mailing list.
389 On Linux, international fonts are installed by different means on
390 every distribution. We cannot list the exact commands or packages
391 that are necessary, as each distribution is different, and the exact
392 package names within each distribution changes. Here are some
398 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
399 ttfonts-zh_CN fonts-ja fonts-hebrew
403 apt-get install emacs-intl-fonts xfonts-intl-.* \
404 ttf-kochi-gothic ttf-kochi-mincho \
405 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi