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
57 @node Compiling from source
58 @section Compiling from source
61 You can also compile LilyPond directly from the source code. This
62 requires that you can read English, so this section is not
63 translated. If you really want to compile LilyPond, see
65 @c DO NOT translate the following line at all.
66 @ref{Compiling from source,,,lilypond-program,Application Usage}.
69 @c Please translate the following line (but not the .html file name)
70 the @uref{Compiling-from-source.html,documentation in English}.
75 @c Please **do not** translate anything below this line. Users
76 @c should not be compiling LilyPond themselves; if they really
77 @c want to do so, they should be able to read the English docs,
78 @c because they'll probably need to ask questions in English
79 @c on the -devel list. -gp
80 @c Instead, please uncomment and translate the paragraph above,
81 @c and remove all stuff (menu, nodes, contents) below this line.
84 * Downloading source code::
87 * Building documentation::
92 @node Downloading source code
93 @subsection Downloading source code
99 @uref{http://lilypond.org/download/} by HTTP.
101 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
103 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
106 git clone git://git.sv.gnu.org/lilypond.git
109 The repository does not contain generated files. To create
110 @file{configure}, run
116 For information on packaging, see @uref{http://lilypond.org/devel}.
120 @subsection Requirements
122 @unnumberedsubsubsec Compilation
124 In addition to the packages needed for running LilyPond (see below), you
125 need the following extra packages for building.
127 When installing a binary package FOO, you may need to install the
128 FOO-devel, libFOO-dev or FOO-dev package too.
132 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
134 @item @uref{http://metafont.tutorial.free.fr/,MetaFont} (mf-nowin, mf, mfw or
135 mfont binaries) and @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html,MetaPost}
136 (mpost binary), usually packaged with a @LaTeX{} distribution like
139 @item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils,t1utils}
140 (version 1.33 or newer recommended).
142 @item New Century Schoolbook fonts, as PFB files. These are shipped with
143 X11 and Ghostscript, and are named @file{c059033l.pfb}
144 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}.
146 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
147 1.8.2 or newer). If you are installing binary packages, you may need to
148 install guile-devel or guile-dev or libguile-dev too.
150 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
152 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 3.4 or
153 newer. 4.x is strongly recommended).
155 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
157 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
159 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
161 @item @uref{http://www.gnu.org/software/flex/,Flex}.
163 @item @uref{http://www.perl.org/,Perl}.
165 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}.
167 @item All packages required for running, including development packages with
168 header files and libraries.
173 @unnumberedsubsubsec Running requirements
175 Running LilyPond requires proper installation of the following software
179 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
180 @item @uref{http://www.freetype.org/,FontConfig} (version 2.2).
181 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
182 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
183 (version 1.8.2 or newer), or patch 1.8.1 with
184 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
185 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
186 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
187 newer. 8.50 recommended)
188 @item Dejaview. (This is normally installed by default)
191 International fonts are required to create music with international text
195 @unnumberedsubsubsec Requirements for building documentation
197 You can view the documentation online at
198 @uref{http://lilypond.org/doc/}, but you can also build it locally.
199 This process requires a successful compile of LilyPond, and some
200 additional tools and packages:
203 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
205 @item International fonts (see input/regression/utf-8.ly for hints
206 about which font packages are necessary for your platform)
207 @item Ghostscript, 8.50 with the patch from
208 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
210 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}, or use
211 a release of Ghostscript which includes these patches, for example
213 @item @uref{http://www.nongnu.org/texi2html/,Texi2HTML} 1.79 or newer
214 is strongly recommended to build documentation in HTML; support for
215 building HTML documentation using @command{makeinfo} from GNU Texinfo
220 @node Building LilyPond
221 @subsection Building LilyPond
223 @unnumberedsubsubsec Compiling
225 To install GNU LilyPond, type
228 gunzip -c lilypond-x.y.z | tar xf -
230 ./configure # run with --help for applicable options
236 If you are not root, you should choose a @code{--prefix} argument that
237 points into your home directory, e.g.
240 ./configure --prefix=$HOME/usr
244 @unnumberedsubsubsec Compiling for multiple platforms
246 If you want to build multiple versions of LilyPond with different
247 configuration settings, you can use the @code{--enable-config=CONF}
248 option of @command{configure}. You should use @code{make conf=CONF}
249 to generate the output in @file{out-CONF}. For example, suppose you
250 want to build with and without profiling, then use the following for
254 ./configure --prefix=$HOME/usr/ --enable-checking
259 and for the profiling version, specify a different configuration
262 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
264 make conf=prof install
268 @unnumberedsubsubsec Compiling outside the source tree
270 It is possible to compile LilyPond in a build tree different from the
271 source tree, with @code{--srcdir} option of @command{configure}:
274 mkdir lily-build && cd lily-build
275 @var{sourcedir}/configure --srcdir=@var{sourcedir}
280 @unnumberedsubsubsec Useful @command{make} variables
282 If a less verbose build output if desired, the variable
283 @code{QUIET_BUILD} may be set to @code{1} on @command{make} command
284 line, or in @file{local.make} at top of the build tree.
287 @node Building documentation
288 @subsection Building documentation
290 This requires a successful compile of LilyPond, or using an external
294 * Commands for building documentation:: Compiling and installing the documentation.
295 * Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
298 @node Commands for building documentation
299 @unnumberedsubsubsec Commands for building documentation
301 The documentation is built by issuing
307 After compilation, the HTML documentation tree is available in
308 @file{out-www/offline-root/}, and can be browsed locally.
310 The HTML and PDF files can be installed into the standard documentation
318 This also installs Info documentation with images if the installation
319 prefix is properly set; otherwise, instructions for manual installation
320 of Info documentation are printed on standard output.
322 It is also possible to build a documentation tree in
323 @file{out-www/online-root/}, with special processing, so it can be used
324 on a website with content negotiation for automatic language selection;
325 this can be achieved by issuing
328 make WEB_TARGETS=online web
332 and both @q{offline} and @q{online} targets can be generated by issuing
335 make WEB_TARGETS="offline online" web
338 Several targets are available to clean the documentation build and
339 help with maintaining documentation; an overview of these targets is
347 from every directory in the build tree. Most targets for
348 documentation maintenance are available from @file{Documentation/};
349 for more information, see @file{Documentation/user/README.txt} and
350 @file{Documentation/TRANSLATION}.
352 The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a
353 less verbose build output, just like for building the programs.
357 @code{-j} command-line option of @command{make} is unsupported for
358 building the documentation. As the most time consuming task is
359 running LilyPond to build images of music, the makefile variable
360 @code{CPU_COUNT} may be set in @file{local.make} or on the command line
361 to the number of @code{.ly} files that LilyPond should process
362 simultaneously, e.g. on a bi-processor or dual core machine
368 If source files have changed since last documentation build, output
369 files that need to be rebuilt are normally rebuilt, even if you do not
370 run @code{make web-clean} first. However, building dependencies in the
371 documentation are so complex that rebuilding of some targets may not
372 be triggered as they should be; a workaround is to force rebuilding
373 by touching appropriate files, e.g.
376 touch Documentation/user/*.itely
381 @node Building documentation without compiling LilyPond
382 @unnumberedsubsubsec Building documentation without compiling LilyPond
384 The documentation can be built locally without compiling LilyPond
385 binary, if LilyPond is already installed on your system.
387 From a fresh Git checkout, do
390 ./autogen.sh # ignore any warning messages
391 cp GNUmakefile.in GNUmakefile
393 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
396 Please note that this may break sometimes -- for example, if a new
397 feature is added with a test file in input/regression, even the latest
398 development release of LilyPond will fail to build the docs.
400 You may build the manual without building all the @file{input/*}
401 stuff: change directory, for example to @file{Documentation/user},
402 issue @code{make web}, which will build documentation in a
403 subdirectory @file{out-www} from the source files in current
404 directory. In this case, if you also want to browse the documentation
405 in its post-processed form, change back to top directory and issue
408 make out=www WWW-post
413 You may also need to create a script for @command{pngtopnm} and
414 @code{pnmtopng}. On GNU/Linux, I use this:
417 export LD_LIBRARY_PATH=/usr/lib
418 exec /usr/bin/pngtopnm "$@"
421 On MacOS@tie{}X, I use this:
424 export DYLD_LIBRARY_PATH=/sw/lib
425 exec /sw/bin/pngtopnm "$@"
430 @node Testing LilyPond
431 @subsection Testing LilyPond
434 <a name="testing"></a>
437 LilyPond comes with an extensive suite that exercises the entire
438 program. This suite can be used to automatically check the impact of a
439 change. This is done as follows
443 @emph{## apply your changes, compile}
447 This will leave an HTML page @file{out/test-results/index.html}. This
448 page shows all the important differences that your change introduced,
449 whether in the layout, MIDI, performance or error reporting.
454 make test-redo @emph{## redo files differing from baseline}
455 make test-clean @emph{## remove all test results}
459 and then run @code{make check} again.
461 For tracking memory usage as part of this test, you will need GUILE
462 CVS; especially the following patch:
463 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
465 For checking the coverage of the test suite, do the following
468 ./buildscripts/build-coverage.sh
469 @emph{# uncovered files, least covered first}
470 python ./buildscripts/coverage.py --summary out-cov/*.cc
471 @emph{# consecutive uncovered lines, longest first}
472 python ./buildscripts/coverage.py --uncovered out-cov/*.cc
479 For help and questions use @email{lilypond-user@@gnu.org}. Send bug
480 reports to @email{bug-lilypond@@gnu.org}.
482 Bugs that are not fault of LilyPond are documented here.
484 @unnumberedsubsubsec Bison 1.875
486 There is a bug in bison-1.875: compilation fails with "parse error
487 before `goto'" in line 4922 due to a bug in bison. To fix, please
488 recompile bison 1.875 with the following fix
491 $ cd lily; make out/parser.cc
492 $ vi +4919 out/parser.cc
493 # append a semicolon to the line containing "__attribute__ ((__unused__))
499 @unnumberedsubsubsec Solaris
501 Solaris7, ./configure
503 @file{./configure} needs a POSIX compliant shell. On Solaris7,
504 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
505 is. Run configure like
508 CONFIG_SHELL=/bin/ksh ksh -c ./configure
515 CONFIG_SHELL=/bin/bash bash -c ./configure
518 @unnumberedsubsubsec FreeBSD
520 To use system fonts, dejaview must be installed. With the default
521 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
523 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
524 following line just after the @code{<fontconfig>} line. (Adjust as necessary
528 <dir>/usr/X11R6/lib/X11/fonts</dir>
532 @unnumberedsubsubsec International fonts
534 On MacOS@tie{}X, all fonts are installed by default. However, finding all
535 system fonts requires a bit of configuration; see
536 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
537 this post} on the @code{lilypond-user} mailing list.
539 On Linux, international fonts are installed by different means on
540 every distribution. We cannot list the exact commands or packages
541 that are necessary, as each distribution is different, and the exact
542 package names within each distribution changes. Here are some
548 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
549 ttfonts-zh_CN fonts-ja fonts-hebrew
553 apt-get install emacs-intl-fonts xfonts-intl-.* \
554 ttf-kochi-gothic ttf-kochi-mincho \
555 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi