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 There are two sets of releases for LilyPond: stable releases, and
18 unstable development releases. Stable versions have an even-numbered
19 @q{minor} version number (i.e. 2.8, 2.10, 2.12, etc). Development
20 versions have an odd-numbered @q{minor} version number (i.e. 2.7, 2.9,
23 Building LilyPond is a very involved process, so we @strong{highly}
24 recommend using the precompiled binaries.
27 * Precompiled binaries::
28 * Compiling from source::
32 @node Precompiled binaries
33 @section Precompiled binaries
35 @unnumberedsubsec Downloading
37 Check out @uref{http://lilypond.org/web/install/} for up to date
38 information on binary packages for your platform. If your operating
39 system is not covered on that general page, please see the complete list
40 at @uref{http://download.linuxaudio.org/lilypond/binaries/}
42 We currently create binaries for
45 darwin-ppc - MacOS X powerpc
46 darwin-x86 - MacOS X intel
47 freebsd-64 - FreeBSD 6.x, x86_64
48 freebsd-x86 - FreeBSD 4.x, x86
49 linux-64 - Any GNU/Linux distribution, x86_64
50 linux-arm - Any GNU/Linux distribution, arm
51 linux-ppc - Any GNU/Linux distribution, powerpc
52 linux-x86 - Any GNU/Linux distribution, x86
58 @c Please **do not** translate anything below this line. Users
59 @c should not be compiling LilyPond themselves; if they really
60 @c want to do so, they should be able to read the English docs,
61 @c because they'll probably need to ask questions in English
62 @c on the -devel list. -gp
64 @node Compiling from source
65 @section Compiling from source
68 * Downloading source code::
71 * Building documentation::
76 @node Downloading source code
77 @subsection Downloading source code
83 @uref{http://lilypond.org/download/} by HTTP.
85 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
87 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
90 git clone git://git.sv.gnu.org/lilypond.git
93 The repository does not contain generated files. To create
100 For information on packaging, see @uref{http://lilypond.org/devel}.
104 @subsection Requirements
106 @unnumberedsubsubsec Compilation
108 In addition to the packages needed for running LilyPond (see below), you
109 need the following extra packages for building.
111 When installing a binary package FOO, you may need to install the
112 FOO-devel, libFOO-dev or FOO-dev package too.
116 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
118 @item @uref{http://metafont.tutorial.free.fr/,MetaFont} (mf-nowin, mf, mfw or
119 mfont binaries) and @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html,MetaPost}
120 (mpost binary), usually packaged with a @LaTeX{} distribution like
123 @item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils,t1utils}
124 (version 1.33 or newer recommended).
126 @item New Century Schoolbook fonts, as PFB files. These are shipped with
127 X11 and Ghostscript, and are named @file{c059033l.pfb}
128 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}.
130 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
131 1.8.2 or newer). If you are installing binary packages, you may need to
132 install guile-devel or guile-dev or libguile-dev too.
134 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
136 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 3.4 or
137 newer. 4.x is strongly recommended).
139 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
141 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
143 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
145 @item @uref{http://www.gnu.org/software/flex/,Flex}.
147 @item @uref{http://www.perl.org/,Perl}.
149 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}.
151 @item All packages required for running, including development packages with
152 header files and libraries.
157 @unnumberedsubsubsec Running requirements
159 Running LilyPond requires proper installation of the following software
163 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
164 @item @uref{http://www.freetype.org/,FontConfig} (version 2.2).
165 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
166 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
167 (version 1.8.2 or newer), or patch 1.8.1 with
168 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
169 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
170 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
171 newer. 8.50 recommended)
172 @item Dejaview. (This is normally installed by default)
175 International fonts are required to create music with international text
179 @unnumberedsubsubsec Requirements for building documentation
181 You can view the documentation online at
182 @uref{http://lilypond.org/doc/}, but you can also build it locally.
183 This process requires a successful compile of LilyPond, and some
184 additional tools and packages:
187 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
189 @item International fonts (see input/regression/utf-8.ly for hints
190 about which font packages are necessary for your platform)
191 @item Ghostscript, 8.50 with the patch from
192 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
194 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}, or use
195 a release of Ghostscript which includes these patches, for example
197 @item @uref{http://www.nongnu.org/texi2html/,Texi2HTML} 1.79 or newer
198 is strongly recommended to build documentation in HTML; support for
199 building HTML documentation using @command{makeinfo} from GNU Texinfo
204 @node Building LilyPond
205 @subsection Building LilyPond
207 @unnumberedsubsubsec Compiling
209 To install GNU LilyPond, type
212 gunzip -c lilypond-x.y.z | tar xf -
214 ./configure # run with --help for applicable options
220 If you are not root, you should choose a @code{--prefix} argument that
221 points into your home directory, e.g.
224 ./configure --prefix=$HOME/usr
228 @unnumberedsubsubsec Compiling for multiple platforms
230 If you want to build multiple versions of LilyPond with different
231 configuration settings, you can use the @code{--enable-config=CONF}
232 option of @command{configure}. You should use @code{make conf=CONF}
233 to generate the output in @file{out-CONF}. For example, suppose you
234 want to build with and without profiling, then use the following for
238 ./configure --prefix=$HOME/usr/ --enable-checking
243 and for the profiling version, specify a different configuration
246 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
248 make conf=prof install
252 @unnumberedsubsubsec Compiling outside the source tree
254 It is possible to compile LilyPond in a build tree different from the
255 source tree, with @code{--srcdir} option of @command{configure}:
258 mkdir lily-build && cd lily-build
259 @var{sourcedir}/configure --srcdir=@var{sourcedir}
264 @unnumberedsubsubsec Useful @command{make} variables
266 If a less verbose build output if desired, the variable
267 @code{QUIET_BUILD} may be set to @code{1} on @command{make} command
268 line, or in @file{local.make} at top of the build tree.
271 @node Building documentation
272 @subsection Building documentation
274 This requires a successful compile of LilyPond, or using an external
278 * Commands for building documentation:: Compiling and installing the documentation.
279 * Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
282 @node Commands for building documentation
283 @unnumberedsubsubsec Commands for building documentation
285 The documentation is built by issuing
291 After compilation, the HTML documentation tree is available in
292 @file{out-www/offline-root/}, and can be browsed locally.
294 The HTML and PDF files can be installed into the standard documentation
302 This also installs Info documentation with images if the installation
303 prefix is properly set; otherwise, instructions for manual installation
304 of Info documentation are printed on standard output.
306 It is also possible to build a documentation tree in
307 @file{out-www/online-root/}, with special processing, so it can be used
308 on a website with content negotiation for automatic language selection;
309 this can be achieved by issuing
312 make WEB_TARGETS=online web
316 and both @q{offline} and @q{online} targets can be generated by issuing
319 make WEB_TARGETS="offline online" web
322 Several targets are available to clean the documentation build and
323 help with maintaining documentation; an overview of these targets is
331 from every directory in the build tree. Most targets for
332 documentation maintenance are available from @file{Documentation/};
333 for more information, see @file{Documentation/user/README.txt} and
334 @file{Documentation/TRANSLATION}.
336 The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a
337 less verbose build output, just like for building the programs.
341 @code{-j} command-line option of @command{make} is unsupported for
342 building the documentation. As the most time consuming task is
343 running LilyPond to build images of music, the makefile variable
344 @code{CPU_COUNT} may be set in @file{local.make} or on the command line
345 to the number of @code{.ly} files that LilyPond should process
346 simultaneously, e.g. on a bi-processor or dual core machine
352 If source files have changed since last documentation build, output
353 files that need to be rebuilt are normally rebuilt, even if you do not
354 run @code{make web-clean} first. However, building dependencies in the
355 documentation are so complex that rebuilding of some targets may not
356 be triggered as they should be; a workaround is to force rebuilding
357 by touching appropriate files, e.g.
360 touch Documentation/user/*.itely
365 @node Building documentation without compiling LilyPond
366 @unnumberedsubsubsec Building documentation without compiling LilyPond
368 The documentation can be built locally without compiling LilyPond
369 binary, if LilyPond is already installed on your system.
371 From a fresh Git checkout, do
374 ./autogen.sh # ignore any warning messages
375 cp GNUmakefile.in GNUmakefile
377 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
380 Please note that this may break sometimes -- for example, if a new
381 feature is added with a test file in input/regression, even the latest
382 development release of LilyPond will fail to build the docs.
384 You may build the manual without building all the @file{input/*}
385 stuff: change directory, for example to @file{Documentation/user},
386 issue @code{make web}, which will build documentation in a
387 subdirectory @file{out-www} from the source files in current
388 directory. In this case, if you also want to browse the documentation
389 in its post-processed form, change back to top directory and issue
392 make out=www WWW-post
397 You may also need to create a script for @command{pngtopnm} and
398 @code{pnmtopng}. On GNU/Linux, I use this:
401 export LD_LIBRARY_PATH=/usr/lib
402 exec /usr/bin/pngtopnm "$@"
405 On MacOS@tie{}X, I use this:
408 export DYLD_LIBRARY_PATH=/sw/lib
409 exec /sw/bin/pngtopnm "$@"
414 @node Testing LilyPond
415 @subsection Testing LilyPond
418 <a name="testing"></a>
421 LilyPond comes with an extensive suite that exercises the entire
422 program. This suite can be used to automatically check the impact of a
423 change. This is done as follows
427 @emph{## apply your changes, compile}
431 This will leave an HTML page @file{out/test-results/index.html}. This
432 page shows all the important differences that your change introduced,
433 whether in the layout, MIDI, performance or error reporting.
438 make test-redo @emph{## redo files differing from baseline}
439 make test-clean @emph{## remove all test results}
443 and then run @code{make check} again.
445 For tracking memory usage as part of this test, you will need GUILE
446 CVS; especially the following patch:
447 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
449 For checking the coverage of the test suite, do the following
452 ./buildscripts/build-coverage.sh
453 @emph{# uncovered files, least covered first}
454 python ./buildscripts/coverage.py --summary out-cov/*.cc
455 @emph{# consecutive uncovered lines, longest first}
456 python ./buildscripts/coverage.py --uncovered out-cov/*.cc
463 For help and questions use @email{lilypond-user@@gnu.org}. Send bug
464 reports to @email{bug-lilypond@@gnu.org}.
466 Bugs that are not fault of LilyPond are documented here.
468 @unnumberedsubsubsec Bison 1.875
470 There is a bug in bison-1.875: compilation fails with "parse error
471 before `goto'" in line 4922 due to a bug in bison. To fix, please
472 recompile bison 1.875 with the following fix
475 $ cd lily; make out/parser.cc
476 $ vi +4919 out/parser.cc
477 # append a semicolon to the line containing "__attribute__ ((__unused__))
483 @unnumberedsubsubsec Solaris
485 Solaris7, ./configure
487 @file{./configure} needs a POSIX compliant shell. On Solaris7,
488 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
489 is. Run configure like
492 CONFIG_SHELL=/bin/ksh ksh -c ./configure
499 CONFIG_SHELL=/bin/bash bash -c ./configure
502 @unnumberedsubsubsec FreeBSD
504 To use system fonts, dejaview must be installed. With the default
505 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
507 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
508 following line just after the @code{<fontconfig>} line. (Adjust as necessary
512 <dir>/usr/X11R6/lib/X11/fonts</dir>
516 @unnumberedsubsubsec International fonts
518 On MacOS@tie{}X, all fonts are installed by default. However, finding all
519 system fonts requires a bit of configuration; see
520 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
521 this post} on the @code{lilypond-user} mailing list.
523 On Linux, international fonts are installed by different means on
524 every distribution. We cannot list the exact commands or packages
525 that are necessary, as each distribution is different, and the exact
526 package names within each distribution changes. Here are some
532 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
533 ttfonts-zh_CN fonts-ja fonts-hebrew
537 apt-get install emacs-intl-fonts xfonts-intl-.* \
538 ttf-kochi-gothic ttf-kochi-mincho \
539 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi