1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-program.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
15 @c I don't know what this comment does. Remove? -gp
18 <a name="download-source">
22 There are two sets of releases for LilyPond: stable releases, and
23 unstable development releases. Stable versions have an even-numbered
24 @q{minor} version number (i.e. 2.8, 2.10, 2.12, etc). Development
25 versions have an odd-numbered @q{minor} version number (i.e. 2.7, 2.9,
28 Building LilyPond is a very involved process, so we @strong{highly}
29 recommend using the precompiled binaries.
32 * Precompiled binaries::
33 * Compiling from source::
37 @node Precompiled binaries
38 @section Precompiled binaries
40 @subsection Downloading
42 Check out @uref{http://lilypond.org/web/install/} for up to date
43 information on binary packages for your platform. If your operating
44 system is not covered on that general page, please see the complete list
45 at @uref{http://download.linuxaudio.org/lilypond/binaries/}
47 We currently create binaries for
50 darwin-ppc - MacOS X powerpc
51 darwin-x86 - MacOS X intel
52 freebsd-64 - FreeBSD 6.x, x86_64
53 freebsd-x86 - FreeBSD 4.x, x86
54 linux-64 - Any GNU/Linux distribution, x86_64
55 linux-arm - Any GNU/Linux distribution, arm
56 linux-ppc - Any GNU/Linux distribution, powerpc
57 linux-x86 - Any GNU/Linux distribution, x86
63 @c Please **do not** translate anything below this line. Users
64 @c should not be compiling LilyPond themselves; if they really
65 @c want to do so, they should be able to read the English docs,
66 @c because they'll probably need to ask questions in English
67 @c on the -devel list. -gp
69 @node Compiling from source
70 @section Compiling from source
73 * Downloading source code::
76 * Building documentation without compiling LilyPond::
81 @node Downloading source code
82 @subsection Downloading source code
88 @uref{http://lilypond.org/download/} by HTTP.
90 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
92 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
95 git clone git://git.sv.gnu.org/lilypond.git
98 The repository does not contain generated files. To create
105 For information on packaging, see @uref{http://lilypond.org/devel}.
109 @subsection Requirements
111 @unnumberedsubsubsec Compilation
113 In addition to the packages needed for running LilyPond (see below), you
114 need the following extra packages for building.
116 When installing a binary package FOO, you may need to install the
117 FOO-devel, libFOO-dev or FOO-dev package too.
121 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
123 @item New Century Schoolbook fonts, as PFB files. These are shipped with
124 X11 and Ghostscript, and are named @file{c059033l.pfb}
125 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}
127 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
128 1.8.2 or newer). If you are installing binary packages, you may need to
129 install guile-devel or guile-dev or libguile-dev too.
131 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
133 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 4.x or
136 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
138 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
140 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
142 @item @uref{http://www.gnu.org/software/flex/,Flex}
144 @item @uref{http://www.perl.org/,Perl}
146 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}
148 @item All packages required for running, including development packages with
149 header files and libraries.
154 @unnumberedsubsubsec Running requirements
156 Running LilyPond requires proper installation of the following software
160 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
161 @item @uref{http://www.freetype.org/,FontConfig} (version 2.2).
162 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
163 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
164 (version 1.8.2 or newer), or patch 1.8.1 with
165 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
166 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
167 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
168 newer. 8.50 recommended)
169 @item Dejaview. (This is normally installed by default)
172 International fonts are required to create music with international text
176 @unnumberedsubsubsec Building documentation
178 You can view the documentation online at
179 @uref{http://lilypond.org/doc/}, but you can also build it locally.
180 This process requires a successful compile of LilyPond, and some
181 additional tools and packages
184 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
186 @item International fonts (see input/regression/utf-8.ly for hints
187 about which font packages are necessary for your platform)
188 @item Ghostscript, 8.50 with the patch from
189 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
191 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
194 The documentation is built by issuing
200 After compilation, the HTML documentation tree is available in
201 @file{out-www/offline-root/}, and can be browsed locally.
203 The HTML and PDF files can be installed into the standard documentation
207 make out=www web-install
210 It is also possible to build a documentation tree in
211 @file{out-www/online-root/}, with special processing, so it can be used
212 on a website with content negotiation for automatic language selection;
213 this can be achieved by issuing
216 make WEB_TARGETS=online web
220 and both @q{offline} and @q{online} targets can be generated by issuing
223 make WEB_TARGETS="offline online" web
227 @node Building LilyPond
228 @subsection Building LilyPond
230 @unnumberedsubsubsec Compiling
232 To install GNU LilyPond, type
235 gunzip -c lilypond-x.y.z | tar xf -
237 ./configure # run with --help for applicable options
242 If you are not root, you should choose a @code{--prefix} argument that
243 points into your home directory, e.g.
246 ./configure --prefix=$HOME/usr
250 @unnumberedsubsubsec Compiling for multiple platforms
252 If you want to build multiple versions of LilyPond with different
253 configuration settings, you can use the @code{--enable-config=CONF}
254 option of configure. You should use @code{make conf=CONF} to generate
255 the output in @file{out-CONF}. Example: Suppose you want to build
256 with and without profiling, then use the following for the normal
260 ./configure --prefix=$HOME/usr/ --enable-checking
265 and for the profiling version, specify a different configuration
268 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
270 make conf=prof install
274 @node Building documentation without compiling LilyPond
275 @subsection Building documentation without compiling LilyPond
277 The documentation can be built locally without compiling LilyPond from
280 From a fresh git checkout, do
283 ./autogen.sh % ignore any warning messages
284 cp GNUmakefile.in GNUmakefile
286 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
287 % change the lilypond directory as appropriate
290 Please note that this may break sometimes -- for example, if a new
291 feature is added with a test file in input/regression, even the latest
292 unstable Lily will fail to build the docs.
294 You may build the manual ( Documentation/user/ ) without building all
299 You may also need to create a script for @command{pngtopnm} and
300 @code{pnmtopng}. On Linux, I use this:
303 export LD_LIBRARY_PATH=/usr/lib
304 exec /usr/bin/pngtopnm "$@"
307 On MacOS@tie{}X, I use this:
310 export DYLD_LIBRARY_PATH=/sw/lib
311 exec /sw/bin/pngtopnm "$@"
314 In order to force make to build a complete manual (this does not
315 rebuild all examples, only things which are changed), I recommend
316 writing a script like this:
319 ### run from Documentation/user/
320 # possibly required on OS X and/or old texinfo
322 if [ -e out-www/lilypond.texi ]; then rm out-www/lilypond.* ; fi;
323 if [ -e out-www/lilypond-program.texi ]; then rm
324 out-www/lilypond-program.* ; fi;
325 if [ -e out-www/lilypond-learning.texi ]; then rm
326 out-www/lilypond-learning.* ; fi;
327 nice make LILYPOND_EXTERNAL_BINARY=~/usr/bin/lilypond web
330 To rebuild the complete HTML docs, run the above script from the
331 @file{Documentation/user/} directory, then run the final line (the
332 @code{nice make}) from the top source dir.
336 @node Testing LilyPond
337 @subsection Testing LilyPond
340 <a name="testing"></a>
343 LilyPond comes with an extensive suite that exercises the entire
344 program. This suite can be used to automatically check the impact of a
345 change. This is done as follows
349 @emph{## apply your changes, compile}
353 This will leave an HTML page @file{out/test-results/index.html}. This
354 page shows all the important differences that your change introduced,
355 whether in the layout, MIDI, performance or error reporting.
360 make test-redo @emph{## redo files differing from baseline}
361 make test-clean @emph{## remove all test results}
365 and then run @code{make check} again.
367 For tracking memory usage as part of this test, you will need GUILE
368 CVS; especially the following patch:
369 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
371 For checking the coverage of the test suite, do the following
374 ./buildscripts/build-coverage.sh
375 @emph{# uncovered files, least covered first}
376 python ./buildscripts/coverage.py --summary out-cov/*.cc
377 @emph{# consecutive uncovered lines, longest first}
378 python ./buildscripts/coverage.py --uncovered out-cov/*.cc
385 For help and questions use @email{lilypond-user@@gnu.org}. Send bug
386 reports to @email{bug-lilypond@@gnu.org}.
388 Bugs that are not fault of LilyPond are documented here.
390 @unnumberedsubsubsec Bison 1.875
392 There is a bug in bison-1.875: compilation fails with "parse error
393 before `goto'" in line 4922 due to a bug in bison. To fix, please
394 recompile bison 1.875 with the following fix
397 $ cd lily; make out/parser.cc
398 $ vi +4919 out/parser.cc
399 # append a semicolon to the line containing "__attribute__ ((__unused__))
405 @unnumberedsubsubsec Solaris
407 Solaris7, ./configure
409 @file{./configure} needs a POSIX compliant shell. On Solaris7,
410 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
411 is. Run configure like
414 CONFIG_SHELL=/bin/ksh ksh -c ./configure
421 CONFIG_SHELL=/bin/bash bash -c ./configure
424 @unnumberedsubsubsec FreeBSD
426 To use system fonts, dejaview must be installed. With the default
427 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
429 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
430 following line just after the @code{<fontconfig>} line. (Adjust as necessary
434 <dir>/usr/X11R6/lib/X11/fonts</dir>
438 @unnumberedsubsubsec International fonts
440 On MacOS@tie{}X, all fonts are installed by default. However, finding all
441 system fonts requires a bit of configuration; see
442 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
443 this post} on the @code{lilypond-user} mailing list.
445 On Linux, international fonts are installed by different means on
446 every distribution. We cannot list the exact commands or packages
447 that are necessary, as each distribution is different, and the exact
448 package names within each distribution changes. Here are some
454 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
455 ttfonts-zh_CN fonts-ja fonts-hebrew
459 apt-get install emacs-intl-fonts xfonts-intl-.* \
460 ttf-kochi-gothic ttf-kochi-mincho \
461 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi