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.
17 @c I don't know what this comment does. Remove? -gp
20 <a name="download-source">
24 There are two sets of releases for LilyPond: stable releases, and
25 unstable development releases. Stable versions have an even-numbered
26 @q{minor} version number (i.e. 2.8, 2.10, 2.12, etc). Development
27 versions have an odd-numbered @q{minor} version number (i.e. 2.7, 2.9,
30 Building LilyPond is a very involved process, so we @strong{highly}
31 recommend using the precompiled binaries.
34 * Precompiled binaries::
35 * Compiling from source::
39 @node Precompiled binaries
40 @section Precompiled binaries
42 @unnumberedsubsec Downloading
44 Check out @uref{http://lilypond.org/web/install/} for up to date
45 information on binary packages for your platform. If your operating
46 system is not covered on that general page, please see the complete list
47 at @uref{http://download.linuxaudio.org/lilypond/binaries/}
49 We currently create binaries for
52 darwin-ppc - MacOS X powerpc
53 darwin-x86 - MacOS X intel
54 freebsd-64 - FreeBSD 6.x, x86_64
55 freebsd-x86 - FreeBSD 4.x, x86
56 linux-64 - Any GNU/Linux distribution, x86_64
57 linux-arm - Any GNU/Linux distribution, arm
58 linux-ppc - Any GNU/Linux distribution, powerpc
59 linux-x86 - Any GNU/Linux distribution, x86
65 @c Please **do not** translate anything below this line. Users
66 @c should not be compiling LilyPond themselves; if they really
67 @c want to do so, they should be able to read the English docs,
68 @c because they'll probably need to ask questions in English
69 @c on the -devel list. -gp
71 @node Compiling from source
72 @section Compiling from source
75 * Downloading source code::
78 * Building documentation::
83 @node Downloading source code
84 @subsection Downloading source code
90 @uref{http://lilypond.org/download/} by HTTP.
92 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
94 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
97 git clone git://git.sv.gnu.org/lilypond.git
100 The repository does not contain generated files. To create
101 @file{configure}, run
107 For information on packaging, see @uref{http://lilypond.org/devel}.
111 @subsection Requirements
113 @unnumberedsubsubsec Compilation
115 In addition to the packages needed for running LilyPond (see below), you
116 need the following extra packages for building.
118 When installing a binary package FOO, you may need to install the
119 FOO-devel, libFOO-dev or FOO-dev package too.
123 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
125 @item MetaFont (mf-nowin, mf, mfw or mfont binaries), usually packaged with
126 a @LaTeX{} distribution like tetex or texlive.
128 @item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils,t1utils}
129 (version 1.33 or newer recommended).
131 @item New Century Schoolbook fonts, as PFB files. These are shipped with
132 X11 and Ghostscript, and are named @file{c059033l.pfb}
133 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}.
135 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
136 1.8.2 or newer). If you are installing binary packages, you may need to
137 install guile-devel or guile-dev or libguile-dev too.
139 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
141 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 3.4 or
142 newer. 4.x is strongly recommended).
144 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
146 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
148 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
150 @item @uref{http://www.gnu.org/software/flex/,Flex}.
152 @item @uref{http://www.perl.org/,Perl}.
154 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}.
156 @item All packages required for running, including development packages with
157 header files and libraries.
162 @unnumberedsubsubsec Running requirements
164 Running LilyPond requires proper installation of the following software
168 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
169 @item @uref{http://www.freetype.org/,FontConfig} (version 2.2).
170 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
171 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
172 (version 1.8.2 or newer), or patch 1.8.1 with
173 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
174 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
175 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
176 newer. 8.50 recommended)
177 @item Dejaview. (This is normally installed by default)
180 International fonts are required to create music with international text
184 @unnumberedsubsubsec Requirements for building documentation
186 You can view the documentation online at
187 @uref{http://lilypond.org/doc/}, but you can also build it locally.
188 This process requires a successful compile of LilyPond, and some
189 additional tools and packages
192 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
194 @item International fonts (see input/regression/utf-8.ly for hints
195 about which font packages are necessary for your platform)
196 @item Ghostscript, 8.50 with the patch from
197 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
199 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}, or use
200 a release of Ghostscript which includes these patches, for example
205 @node Building LilyPond
206 @subsection Building LilyPond
208 @unnumberedsubsubsec Compiling
210 To install GNU LilyPond, type
213 gunzip -c lilypond-x.y.z | tar xf -
215 ./configure # run with --help for applicable options
221 If you are not root, you should choose a @code{--prefix} argument that
222 points into your home directory, e.g.
225 ./configure --prefix=$HOME/usr
229 @unnumberedsubsubsec Compiling for multiple platforms
231 If you want to build multiple versions of LilyPond with different
232 configuration settings, you can use the @code{--enable-config=CONF}
233 option of @command{configure}. You should use @code{make conf=CONF}
234 to generate the output in @file{out-CONF}. For example, suppose you
235 want to build with and without profiling, then use the following for
239 ./configure --prefix=$HOME/usr/ --enable-checking
244 and for the profiling version, specify a different configuration
247 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
249 make conf=prof install
253 @unnumberedsubsubsec Compiling outside the source tree
255 It is possible to compile LilyPond in a build tree different from the
256 source tree, with @code{--srcdir} option of @command{configure}:
259 mkdir lily-build && cd lily-build
260 @var{sourcedir}/configure --srcdir=@var{sourcedir}
264 @node Building documentation
265 @subsection Building documentation
267 This requires a successful compile of LilyPond, or using an external
271 * Commands for building documentation:: Compiling and installing the documentation.
272 * Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
275 @node Commands for building documentation
276 @unnumberedsubsubsec Commands for building documentation
278 The documentation is built by issuing
284 After compilation, the HTML documentation tree is available in
285 @file{out-www/offline-root/}, and can be browsed locally.
287 The HTML and PDF files can be installed into the standard documentation
295 This also installs Info documentation with images if the installation
296 prefix is properly set; otherwise, instructions for manual installation
297 of Info documentation are printed on standard output.
299 It is also possible to build a documentation tree in
300 @file{out-www/online-root/}, with special processing, so it can be used
301 on a website with content negotiation for automatic language selection;
302 this can be achieved by issuing
305 make WEB_TARGETS=online web
309 and both @q{offline} and @q{online} targets can be generated by issuing
312 make WEB_TARGETS="offline online" web
315 Several targets are available to clean the documentation build and
316 help with maintaining documentation; an overview of these targets is
324 from every directory in the build tree. Most targets for
325 documentation maintenance are available from @file{Documentation/};
326 for more information, see @file{Documentation/user/README.txt} and
327 @file{Documentation/TRANSLATION}.
331 @code{-j} command-line option of @command{make} is unsupported for
332 building the documentation. As the most time consuming task is
333 running LilyPond to build images of music, the makefile variable
334 @code{CPU_COUNT} may be set in @file{local.make} or on the command line
335 to the number of @code{.ly} files that LilyPond should process
336 simultaneously, e.g. on a bi-processor or Dual core machine
342 If source files have changed since last documentation build, output
343 files that need to be rebuilt are normally rebuilt, even if you do not
344 run @code{make web-clean} first. However, building dependencies in the
345 documentation are so complex that rebuilding of some targets may not
346 be triggered as they should be; a workaround is to force rebuilding
347 by touching appropriate files, e.g.
350 touch Documentation/user/*.itely
355 @node Building documentation without compiling LilyPond
356 @unnumberedsubsubsec Building documentation without compiling LilyPond
358 The documentation can be built locally without compiling LilyPond
359 binary, if LilyPond is already installed on your system.
361 From a fresh Git checkout, do
364 ./autogen.sh # ignore any warning messages
365 cp GNUmakefile.in GNUmakefile
367 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
370 Please note that this may break sometimes -- for example, if a new
371 feature is added with a test file in input/regression, even the latest
372 development release of LilyPond will fail to build the docs.
374 You may build the manual without building all the @file{input/*}
375 stuff: change directory, for example to @file{Documentation/user},
376 issue @code{make web}, which will build documentation in a
377 subdirectory @file{out-www} from the source files in current
378 directory. In this case, if you also want to browse the documentation
379 in its post-processed form, change back to top directory and issue
382 make out=www WWW-post
387 You may also need to create a script for @command{pngtopnm} and
388 @code{pnmtopng}. On GNU/Linux, I use this:
391 export LD_LIBRARY_PATH=/usr/lib
392 exec /usr/bin/pngtopnm "$@"
395 On MacOS@tie{}X, I use this:
398 export DYLD_LIBRARY_PATH=/sw/lib
399 exec /sw/bin/pngtopnm "$@"
404 @node Testing LilyPond
405 @subsection Testing LilyPond
408 <a name="testing"></a>
411 LilyPond comes with an extensive suite that exercises the entire
412 program. This suite can be used to automatically check the impact of a
413 change. This is done as follows
417 @emph{## apply your changes, compile}
421 This will leave an HTML page @file{out/test-results/index.html}. This
422 page shows all the important differences that your change introduced,
423 whether in the layout, MIDI, performance or error reporting.
428 make test-redo @emph{## redo files differing from baseline}
429 make test-clean @emph{## remove all test results}
433 and then run @code{make check} again.
435 For tracking memory usage as part of this test, you will need GUILE
436 CVS; especially the following patch:
437 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
439 For checking the coverage of the test suite, do the following
442 ./buildscripts/build-coverage.sh
443 @emph{# uncovered files, least covered first}
444 python ./buildscripts/coverage.py --summary out-cov/*.cc
445 @emph{# consecutive uncovered lines, longest first}
446 python ./buildscripts/coverage.py --uncovered out-cov/*.cc
453 For help and questions use @email{lilypond-user@@gnu.org}. Send bug
454 reports to @email{bug-lilypond@@gnu.org}.
456 Bugs that are not fault of LilyPond are documented here.
458 @unnumberedsubsubsec Bison 1.875
460 There is a bug in bison-1.875: compilation fails with "parse error
461 before `goto'" in line 4922 due to a bug in bison. To fix, please
462 recompile bison 1.875 with the following fix
465 $ cd lily; make out/parser.cc
466 $ vi +4919 out/parser.cc
467 # append a semicolon to the line containing "__attribute__ ((__unused__))
473 @unnumberedsubsubsec Solaris
475 Solaris7, ./configure
477 @file{./configure} needs a POSIX compliant shell. On Solaris7,
478 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
479 is. Run configure like
482 CONFIG_SHELL=/bin/ksh ksh -c ./configure
489 CONFIG_SHELL=/bin/bash bash -c ./configure
492 @unnumberedsubsubsec FreeBSD
494 To use system fonts, dejaview must be installed. With the default
495 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
497 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
498 following line just after the @code{<fontconfig>} line. (Adjust as necessary
502 <dir>/usr/X11R6/lib/X11/fonts</dir>
506 @unnumberedsubsubsec International fonts
508 On MacOS@tie{}X, all fonts are installed by default. However, finding all
509 system fonts requires a bit of configuration; see
510 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
511 this post} on the @code{lilypond-user} mailing list.
513 On Linux, international fonts are installed by different means on
514 every distribution. We cannot list the exact commands or packages
515 that are necessary, as each distribution is different, and the exact
516 package names within each distribution changes. Here are some
522 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
523 ttfonts-zh_CN fonts-ja fonts-hebrew
527 apt-get install emacs-intl-fonts xfonts-intl-.* \
528 ttf-kochi-gothic ttf-kochi-mincho \
529 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi