1 @c -*- coding: us-ascii; mode: texinfo; -*-
2 @node Compiling from source
3 @chapter Compiling from source
6 You can also compile LilyPond directly from the source code. This
7 requires that you can read English, so this section is not
8 translated. If you really want to compile LilyPond, see
10 @c DO NOT translate the following line at all.
11 @ref{Compiling from source,,,lilypond-program,Application Usage}.
14 @c Please translate the following line (but not the .html file name)
15 the @uref{Compiling-from-source.html,documentation in English}.
20 @c Please **do not** translate anything below this line. Users
21 @c should not be compiling LilyPond themselves; if they really
22 @c want to do so, they should be able to read the English docs,
23 @c because they'll probably need to ask questions in English
24 @c on the -devel list. -gp
25 @c Instead, please uncomment and translate the paragraph above,
26 @c and remove all stuff (menu, nodes, contents) below this line.
29 * Downloading source code::
32 * Building documentation::
37 @node Downloading source code
38 @subsection Downloading source code
44 @uref{http://lilypond.org/download/} by HTTP.
46 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
48 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
51 git clone git://git.sv.gnu.org/lilypond.git
54 The repository does not contain generated files. To create
61 For information on packaging, see @uref{http://lilypond.org/devel}.
65 @subsection Requirements
67 @unnumberedsubsubsec Compilation
69 In addition to the packages needed for running LilyPond (see below), you
70 need the following extra packages for building.
72 When installing a binary package FOO, you may need to install the
73 FOO-devel, libFOO-dev or FOO-dev package too.
77 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
79 @item @uref{http://metafont.tutorial.free.fr/,MetaFont} (mf-nowin, mf, mfw or
80 mfont binaries) and @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html,MetaPost}
81 (mpost binary), usually packaged with a @LaTeX{} distribution like
84 @item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils,t1utils}
85 (version 1.33 or newer recommended).
87 @item New Century Schoolbook fonts, as PFB files. These are shipped with
88 X11 and Ghostscript, and are named @file{c059033l.pfb}
89 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}.
91 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
92 1.8.2 or newer). If you are installing binary packages, you may need to
93 install guile-devel or guile-dev or libguile-dev too.
95 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
97 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 3.4 or
98 newer. 4.x is strongly recommended).
100 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
102 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
104 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}
105 (version 0.17 or newer).
107 @item @uref{http://www.gnu.org/software/flex/,Flex}.
109 @item @uref{http://www.perl.org/,Perl}.
111 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}.
113 @item All packages required for running, including development packages with
114 header files and libraries.
119 @unnumberedsubsubsec Running requirements
121 Running LilyPond requires proper installation of the following software
125 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
126 @item @uref{http://fontconfig.org/,FontConfig} (version 2.2 or newer).
127 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
128 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
129 (version 1.8.2 or newer), or patch 1.8.1 with
130 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
131 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
132 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
133 newer. 8.60 recommended)
134 @item Dejaview. (This is normally installed by default)
137 International fonts are required to create music with international text
141 @unnumberedsubsubsec Requirements for building documentation
143 You can view the documentation online at
144 @uref{http://lilypond.org/doc/}, but you can also build it locally.
145 This process requires a successful compile of LilyPond, and some
146 additional tools and packages:
149 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
151 @item International fonts (see input/regression/utf-8.ly for hints
152 about which font packages are necessary for your platform)
153 @item Ghostscript 8.60 or newer, or 8.50 with the patch from
154 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
156 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
157 @item @uref{http://www.nongnu.org/texi2html/,Texi2HTML} 1.80 or newer
162 @node Building LilyPond
163 @subsection Building LilyPond
165 @unnumberedsubsubsec Compiling
167 To install GNU LilyPond, type
170 gunzip -c lilypond-x.y.z | tar xf -
172 ./configure # run with --help for applicable options
178 If you are not root, you should choose a @code{--prefix} argument that
179 points into your home directory, e.g.
182 ./configure --prefix=$HOME/usr
186 @unnumberedsubsubsec Compiling for multiple platforms
188 If you want to build multiple versions of LilyPond with different
189 configuration settings, you can use the @code{--enable-config=CONF}
190 option of @command{configure}. You should use @code{make conf=CONF}
191 to generate the output in @file{out-CONF}. For example, suppose you
192 want to build with and without profiling, then use the following for
196 ./configure --prefix=$HOME/usr/ --enable-checking
201 and for the profiling version, specify a different configuration
204 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
206 make conf=prof install
210 @unnumberedsubsubsec Compiling outside the source tree
212 It is possible to compile LilyPond in a build tree different from the
213 source tree, with @code{--srcdir} option of @command{configure}:
216 mkdir lily-build && cd lily-build
217 @var{sourcedir}/configure --srcdir=@var{sourcedir}
222 @unnumberedsubsubsec Useful @command{make} variables
224 If a less verbose build output if desired, the variable
225 @code{QUIET_BUILD} may be set to @code{1} on @command{make} command
226 line, or in @file{local.make} at top of the build tree.
229 @node Building documentation
230 @subsection Building documentation
232 This requires a successful compile of LilyPond, or using an external
236 * Commands for building documentation:: Compiling and installing the documentation.
237 * Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
240 @node Commands for building documentation
241 @unnumberedsubsubsec Commands for building documentation
243 The documentation is built by issuing
249 After compilation, the HTML documentation tree is available in
250 @file{out-www/offline-root/}, and can be browsed locally.
252 The HTML and PDF files can be installed into the standard documentation
260 This also installs Info documentation with images if the installation
261 prefix is properly set; otherwise, instructions for manual installation
262 of Info documentation are printed on standard output.
264 It is also possible to build a documentation tree in
265 @file{out-www/online-root/}, with special processing, so it can be used
266 on a website with content negotiation for automatic language selection;
267 this can be achieved by issuing
270 make WEB_TARGETS=online web
274 and both @q{offline} and @q{online} targets can be generated by issuing
277 make WEB_TARGETS="offline online" web
280 Several targets are available to clean the documentation build and
281 help with maintaining documentation; an overview of these targets is
289 from every directory in the build tree. Most targets for
290 documentation maintenance are available from @file{Documentation/};
291 for more information, see @file{Documentation/user/README.txt} and
292 @file{Documentation/TRANSLATION}.
294 The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a
295 less verbose build output, just like for building the programs.
299 The most time consuming task for building the documentation is running
300 LilyPond to build images of music, and there cannot be several
301 simultaneously running @command{lilypond-book} instances, so @code{-j}
302 @command{make} option does not significantly speed up the build process.
303 To help speed it up, the makefile variable @var{CPU_COUNT} may be set
304 in @file{local.make} or on the command line to the number of
305 @code{.ly} files that LilyPond should process simultaneously, e.g. on
306 a bi-processor or dual core machine
309 make -j3 CPU_COUNT=3 web
313 The recommended value of @var{CPU_COUNT} is one plus the number of
314 cores or processors, but it is advisable to set it to a smaller value
315 if your system has not enough RAM to run that many simultaneous
318 If source files have changed since last documentation build, output
319 files that need to be rebuilt are normally rebuilt, even if you do not
320 run @code{make web-clean} first. However, building dependencies in the
321 documentation are so complex that rebuilding of some targets may not
322 be triggered as they should be; a workaround is to force rebuilding
323 by touching appropriate files, e.g.
326 touch Documentation/user/*.itely
331 @node Building documentation without compiling LilyPond
332 @unnumberedsubsubsec Building documentation without compiling LilyPond
334 The documentation can be built locally without compiling LilyPond
335 binary, if LilyPond is already installed on your system.
337 From a fresh Git checkout, do
340 ./autogen.sh # ignore any warning messages
341 cp GNUmakefile.in GNUmakefile
343 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
346 Please note that this may break sometimes -- for example, if a new
347 feature is added with a test file in input/regression, even the latest
348 development release of LilyPond will fail to build the docs.
350 You may build the manual without building all the @file{input/*}
351 stuff: change directory, for example to @file{Documentation/user},
352 issue @code{make web}, which will build documentation in a
353 subdirectory @file{out-www} from the source files in current
354 directory. In this case, if you also want to browse the documentation
355 in its post-processed form, change back to top directory and issue
358 make out=www WWW-post
363 You may also need to create a script for @command{pngtopnm} and
364 @code{pnmtopng}. On GNU/Linux, I use this:
367 export LD_LIBRARY_PATH=/usr/lib
368 exec /usr/bin/pngtopnm "$@"
371 On MacOS@tie{}X, I use this:
374 export DYLD_LIBRARY_PATH=/sw/lib
375 exec /sw/bin/pngtopnm "$@"
380 @node Testing LilyPond
381 @subsection Testing LilyPond
384 <a name="testing"></a>
387 LilyPond comes with an extensive suite that exercises the entire
388 program. This suite can be used to automatically check the impact of a
389 change. This is done as follows
393 @emph{## apply your changes, compile}
397 This will leave an HTML page @file{out/test-results/index.html}. This
398 page shows all the important differences that your change introduced,
399 whether in the layout, MIDI, performance or error reporting.
404 make test-redo @emph{## redo files differing from baseline}
405 make test-clean @emph{## remove all test results}
409 and then run @code{make check} again.
411 For tracking memory usage as part of this test, you will need GUILE
412 CVS; especially the following patch:
413 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
415 For checking the coverage of the test suite, do the following
418 ./scripts/auxiliar/build-coverage.sh
419 @emph{# uncovered files, least covered first}
420 ./scripts/auxiliar/coverage.py --summary out-cov/*.cc
421 @emph{# consecutive uncovered lines, longest first}
422 ./scripts/auxiliar/coverage.py --uncovered out-cov/*.cc
429 For help and questions use @email{lilypond-user@@gnu.org}. Send bug
430 reports to @email{bug-lilypond@@gnu.org}.
432 Bugs that are not fault of LilyPond are documented here.
434 @unnumberedsubsubsec Bison 1.875
436 There is a bug in bison-1.875: compilation fails with "parse error
437 before `goto'" in line 4922 due to a bug in bison. To fix, please
438 recompile bison 1.875 with the following fix
441 $ cd lily; make out/parser.cc
442 $ vi +4919 out/parser.cc
443 # append a semicolon to the line containing "__attribute__ ((__unused__))
449 @unnumberedsubsubsec Solaris
451 Solaris7, ./configure
453 @file{./configure} needs a POSIX compliant shell. On Solaris7,
454 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
455 is. Run configure like
458 CONFIG_SHELL=/bin/ksh ksh -c ./configure
465 CONFIG_SHELL=/bin/bash bash -c ./configure
468 @unnumberedsubsubsec FreeBSD
470 To use system fonts, dejaview must be installed. With the default
471 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
473 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
474 following line just after the @code{<fontconfig>} line. (Adjust as necessary
478 <dir>/usr/X11R6/lib/X11/fonts</dir>
482 @unnumberedsubsubsec International fonts
484 On MacOS@tie{}X, all fonts are installed by default. However, finding all
485 system fonts requires a bit of configuration; see
486 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
487 this post} on the @code{lilypond-user} mailing list.
489 On Linux, international fonts are installed by different means on
490 every distribution. We cannot list the exact commands or packages
491 that are necessary, as each distribution is different, and the exact
492 package names within each distribution changes. Here are some
498 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
499 ttfonts-zh_CN fonts-ja fonts-hebrew
503 apt-get install emacs-intl-fonts xfonts-intl-.* \
504 ttf-kochi-gothic ttf-kochi-mincho \
505 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
512 - how to make a stable version and development version coexist on
515 - how to build with debug info