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-ppc - Any GNU/Linux distribution, powerpc
51 linux-x86 - Any GNU/Linux distribution, x86
57 If you have MacOS 10.3 or 10.4 and you would like to use Python
58 scripts such as @command{convert-ly} and @command{lilypond-book}, see
59 @ref{Setup for MacOS X,,,lilypond-program,Application Usage}.
62 @node Compiling from source
63 @section Compiling from source
66 You can also compile LilyPond directly from the source code. This
67 requires that you can read English, so this section is not
68 translated. If you really want to compile LilyPond, see
70 @c DO NOT translate the following line at all.
71 @ref{Compiling from source,,,lilypond-program,Application Usage}.
74 @c Please translate the following line (but not the .html file name)
75 the @uref{Compiling-from-source.html,documentation in English}.
80 @c Please **do not** translate anything below this line. Users
81 @c should not be compiling LilyPond themselves; if they really
82 @c want to do so, they should be able to read the English docs,
83 @c because they'll probably need to ask questions in English
84 @c on the -devel list. -gp
85 @c Instead, please uncomment and translate the paragraph above,
86 @c and remove all stuff (menu, nodes, contents) below this line.
89 * Downloading source code::
92 * Building documentation::
97 @node Downloading source code
98 @subsection Downloading source code
104 @uref{http://lilypond.org/download/} by HTTP.
106 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
108 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
111 git clone git://git.sv.gnu.org/lilypond.git
114 The repository does not contain generated files. To create
115 @file{configure}, run
121 For information on packaging, see @uref{http://lilypond.org/devel}.
125 @subsection Requirements
127 @unnumberedsubsubsec Compilation
129 In addition to the packages needed for running LilyPond (see below), you
130 need the following extra packages for building.
132 When installing a binary package FOO, you may need to install the
133 FOO-devel, libFOO-dev or FOO-dev package too.
137 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
139 @item @uref{http://metafont.tutorial.free.fr/,MetaFont} (mf-nowin, mf, mfw or
140 mfont binaries) and @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html,MetaPost}
141 (mpost binary), usually packaged with a @LaTeX{} distribution like
144 @item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils,t1utils}
145 (version 1.33 or newer recommended).
147 @item New Century Schoolbook fonts, as PFB files. These are shipped with
148 X11 and Ghostscript, and are named @file{c059033l.pfb}
149 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}.
151 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
152 1.8.2 or newer). If you are installing binary packages, you may need to
153 install guile-devel or guile-dev or libguile-dev too.
155 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
157 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 3.4 or
158 newer. 4.x is strongly recommended).
160 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
162 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
164 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}
165 (version 0.17 or newer).
167 @item @uref{http://www.gnu.org/software/flex/,Flex}.
169 @item @uref{http://www.perl.org/,Perl}.
171 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}.
173 @item All packages required for running, including development packages with
174 header files and libraries.
179 @unnumberedsubsubsec Running requirements
181 Running LilyPond requires proper installation of the following software
185 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
186 @item @uref{http://fontconfig.org/,FontConfig} (version 2.2 or newer).
187 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
188 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
189 (version 1.8.2 or newer), or patch 1.8.1 with
190 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
191 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
192 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
193 newer. 8.60 recommended)
194 @item Dejaview. (This is normally installed by default)
197 International fonts are required to create music with international text
201 @unnumberedsubsubsec Requirements for building documentation
203 You can view the documentation online at
204 @uref{http://lilypond.org/doc/}, but you can also build it locally.
205 This process requires a successful compile of LilyPond, and some
206 additional tools and packages:
209 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
211 @item International fonts (see input/regression/utf-8.ly for hints
212 about which font packages are necessary for your platform)
213 @item Ghostscript 8.60 or newer, or 8.50 with the patch from
214 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
216 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
217 @item @uref{http://www.nongnu.org/texi2html/,Texi2HTML} 1.79 or newer
218 is strongly recommended to build documentation in HTML; support for
219 building HTML documentation using @command{makeinfo} from GNU Texinfo
224 @node Building LilyPond
225 @subsection Building LilyPond
227 @unnumberedsubsubsec Compiling
229 To install GNU LilyPond, type
232 gunzip -c lilypond-x.y.z | tar xf -
234 ./configure # run with --help for applicable options
240 If you are not root, you should choose a @code{--prefix} argument that
241 points into your home directory, e.g.
244 ./configure --prefix=$HOME/usr
248 @unnumberedsubsubsec Compiling for multiple platforms
250 If you want to build multiple versions of LilyPond with different
251 configuration settings, you can use the @code{--enable-config=CONF}
252 option of @command{configure}. You should use @code{make conf=CONF}
253 to generate the output in @file{out-CONF}. For example, suppose you
254 want to build with and without profiling, then use the following for
258 ./configure --prefix=$HOME/usr/ --enable-checking
263 and for the profiling version, specify a different configuration
266 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
268 make conf=prof install
272 @unnumberedsubsubsec Compiling outside the source tree
274 It is possible to compile LilyPond in a build tree different from the
275 source tree, with @code{--srcdir} option of @command{configure}:
278 mkdir lily-build && cd lily-build
279 @var{sourcedir}/configure --srcdir=@var{sourcedir}
284 @unnumberedsubsubsec Useful @command{make} variables
286 If a less verbose build output if desired, the variable
287 @code{QUIET_BUILD} may be set to @code{1} on @command{make} command
288 line, or in @file{local.make} at top of the build tree.
291 @node Building documentation
292 @subsection Building documentation
294 This requires a successful compile of LilyPond, or using an external
298 * Commands for building documentation:: Compiling and installing the documentation.
299 * Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
302 @node Commands for building documentation
303 @unnumberedsubsubsec Commands for building documentation
305 The documentation is built by issuing
311 After compilation, the HTML documentation tree is available in
312 @file{out-www/offline-root/}, and can be browsed locally.
314 The HTML and PDF files can be installed into the standard documentation
322 This also installs Info documentation with images if the installation
323 prefix is properly set; otherwise, instructions for manual installation
324 of Info documentation are printed on standard output.
326 It is also possible to build a documentation tree in
327 @file{out-www/online-root/}, with special processing, so it can be used
328 on a website with content negotiation for automatic language selection;
329 this can be achieved by issuing
332 make WEB_TARGETS=online web
336 and both @q{offline} and @q{online} targets can be generated by issuing
339 make WEB_TARGETS="offline online" web
342 Several targets are available to clean the documentation build and
343 help with maintaining documentation; an overview of these targets is
351 from every directory in the build tree. Most targets for
352 documentation maintenance are available from @file{Documentation/};
353 for more information, see @file{Documentation/user/README.txt} and
354 @file{Documentation/TRANSLATION}.
356 The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a
357 less verbose build output, just like for building the programs.
361 The most time consuming task for building the documentation is running
362 LilyPond to build images of music, and there cannot be several
363 simultaneously running @command{lilypond-book} instances, so @code{-j}
364 @command{make} option does not significantly speed up the build process.
365 To help speed it up, the makefile variable @var{CPU_COUNT} may be set
366 in @file{local.make} or on the command line to the number of
367 @code{.ly} files that LilyPond should process simultaneously, e.g. on
368 a bi-processor or dual core machine
371 make -j3 CPU_COUNT=3 web
375 The recommended value of @var{CPU_COUNT} is one plus the number of
376 cores or processors, but it is advisable to set it to a smaller value
377 if your system has not enough RAM to run that many simultaneous
380 If source files have changed since last documentation build, output
381 files that need to be rebuilt are normally rebuilt, even if you do not
382 run @code{make web-clean} first. However, building dependencies in the
383 documentation are so complex that rebuilding of some targets may not
384 be triggered as they should be; a workaround is to force rebuilding
385 by touching appropriate files, e.g.
388 touch Documentation/user/*.itely
393 @node Building documentation without compiling LilyPond
394 @unnumberedsubsubsec Building documentation without compiling LilyPond
396 The documentation can be built locally without compiling LilyPond
397 binary, if LilyPond is already installed on your system.
399 From a fresh Git checkout, do
402 ./autogen.sh # ignore any warning messages
403 cp GNUmakefile.in GNUmakefile
405 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
408 Please note that this may break sometimes -- for example, if a new
409 feature is added with a test file in input/regression, even the latest
410 development release of LilyPond will fail to build the docs.
412 You may build the manual without building all the @file{input/*}
413 stuff: change directory, for example to @file{Documentation/user},
414 issue @code{make web}, which will build documentation in a
415 subdirectory @file{out-www} from the source files in current
416 directory. In this case, if you also want to browse the documentation
417 in its post-processed form, change back to top directory and issue
420 make out=www WWW-post
425 You may also need to create a script for @command{pngtopnm} and
426 @code{pnmtopng}. On GNU/Linux, I use this:
429 export LD_LIBRARY_PATH=/usr/lib
430 exec /usr/bin/pngtopnm "$@"
433 On MacOS@tie{}X, I use this:
436 export DYLD_LIBRARY_PATH=/sw/lib
437 exec /sw/bin/pngtopnm "$@"
442 @node Testing LilyPond
443 @subsection Testing LilyPond
446 <a name="testing"></a>
449 LilyPond comes with an extensive suite that exercises the entire
450 program. This suite can be used to automatically check the impact of a
451 change. This is done as follows
455 @emph{## apply your changes, compile}
459 This will leave an HTML page @file{out/test-results/index.html}. This
460 page shows all the important differences that your change introduced,
461 whether in the layout, MIDI, performance or error reporting.
466 make test-redo @emph{## redo files differing from baseline}
467 make test-clean @emph{## remove all test results}
471 and then run @code{make check} again.
473 For tracking memory usage as part of this test, you will need GUILE
474 CVS; especially the following patch:
475 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
477 For checking the coverage of the test suite, do the following
480 ./scripts/auxiliar/build-coverage.sh
481 @emph{# uncovered files, least covered first}
482 ./scripts/auxiliar/coverage.py --summary out-cov/*.cc
483 @emph{# consecutive uncovered lines, longest first}
484 ./scripts/auxiliar/coverage.py --uncovered out-cov/*.cc
491 For help and questions use @email{lilypond-user@@gnu.org}. Send bug
492 reports to @email{bug-lilypond@@gnu.org}.
494 Bugs that are not fault of LilyPond are documented here.
496 @unnumberedsubsubsec Bison 1.875
498 There is a bug in bison-1.875: compilation fails with "parse error
499 before `goto'" in line 4922 due to a bug in bison. To fix, please
500 recompile bison 1.875 with the following fix
503 $ cd lily; make out/parser.cc
504 $ vi +4919 out/parser.cc
505 # append a semicolon to the line containing "__attribute__ ((__unused__))
511 @unnumberedsubsubsec Solaris
513 Solaris7, ./configure
515 @file{./configure} needs a POSIX compliant shell. On Solaris7,
516 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
517 is. Run configure like
520 CONFIG_SHELL=/bin/ksh ksh -c ./configure
527 CONFIG_SHELL=/bin/bash bash -c ./configure
530 @unnumberedsubsubsec FreeBSD
532 To use system fonts, dejaview must be installed. With the default
533 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
535 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
536 following line just after the @code{<fontconfig>} line. (Adjust as necessary
540 <dir>/usr/X11R6/lib/X11/fonts</dir>
544 @unnumberedsubsubsec International fonts
546 On MacOS@tie{}X, all fonts are installed by default. However, finding all
547 system fonts requires a bit of configuration; see
548 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
549 this post} on the @code{lilypond-user} mailing list.
551 On Linux, international fonts are installed by different means on
552 every distribution. We cannot list the exact commands or packages
553 that are necessary, as each distribution is different, and the exact
554 package names within each distribution changes. Here are some
560 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
561 ttfonts-zh_CN fonts-ja fonts-hebrew
565 apt-get install emacs-intl-fonts xfonts-intl-.* \
566 ttf-kochi-gothic ttf-kochi-mincho \
567 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi