1 @c -*- coding: us-ascii; mode: texinfo; -*-
6 @node Compiling from source
7 @section Compiling from source
10 You can also compile LilyPond directly from the source code. This
11 requires that you can read English, so this section is not
12 translated. If you really want to compile LilyPond, see
14 @c DO NOT translate the following line at all.
15 @ref{Compiling from source,,,lilypond-program,Application Usage}.
18 @c Please translate the following line (but not the .html file name)
19 the @uref{Compiling-from-source.html,documentation in English}.
24 @c Please **do not** translate anything below this line. Users
25 @c should not be compiling LilyPond themselves; if they really
26 @c want to do so, they should be able to read the English docs,
27 @c because they'll probably need to ask questions in English
28 @c on the -devel list. -gp
29 @c Instead, please uncomment and translate the paragraph above,
30 @c and remove all stuff (menu, nodes, contents) below this line.
33 * Downloading source code::
36 * Building documentation::
41 @node Downloading source code
42 @subsection Downloading source code
48 @uref{http://lilypond.org/download/} by HTTP.
50 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
52 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
55 git clone git://git.sv.gnu.org/lilypond.git
58 The repository does not contain generated files. To create
65 For information on packaging, see @uref{http://lilypond.org/devel}.
69 @subsection Requirements
71 @unnumberedsubsubsec Compilation
73 In addition to the packages needed for running LilyPond (see below), you
74 need the following extra packages for building.
76 When installing a binary package FOO, you may need to install the
77 FOO-devel, libFOO-dev or FOO-dev package too.
81 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
83 @item @uref{http://metafont.tutorial.free.fr/,MetaFont} (mf-nowin, mf, mfw or
84 mfont binaries) and @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html,MetaPost}
85 (mpost binary), usually packaged with a @LaTeX{} distribution like
88 @item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils,t1utils}
89 (version 1.33 or newer recommended).
91 @item New Century Schoolbook fonts, as PFB files. These are shipped with
92 X11 and Ghostscript, and are named @file{c059033l.pfb}
93 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}.
95 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
96 1.8.2 or newer). If you are installing binary packages, you may need to
97 install guile-devel or guile-dev or libguile-dev too.
99 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
101 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 3.4 or
102 newer. 4.x is strongly recommended).
104 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
106 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
108 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}
109 (version 0.17 or newer).
111 @item @uref{http://www.gnu.org/software/flex/,Flex}.
113 @item @uref{http://www.perl.org/,Perl}.
115 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}.
117 @item All packages required for running, including development packages with
118 header files and libraries.
123 @unnumberedsubsubsec Running requirements
125 Running LilyPond requires proper installation of the following software
129 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
130 @item @uref{http://fontconfig.org/,FontConfig} (version 2.2 or newer).
131 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
132 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
133 (version 1.8.2 or newer), or patch 1.8.1 with
134 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
135 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
136 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
137 newer. 8.60 recommended)
138 @item Dejaview. (This is normally installed by default)
141 International fonts are required to create music with international text
145 @unnumberedsubsubsec Requirements for building documentation
147 You can view the documentation online at
148 @uref{http://lilypond.org/doc/}, but you can also build it locally.
149 This process requires a successful compile of LilyPond, and some
150 additional tools and packages:
153 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
155 @item International fonts (see input/regression/utf-8.ly for hints
156 about which font packages are necessary for your platform)
157 @item Ghostscript 8.60 or newer, or 8.50 with the patch from
158 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
160 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
161 @item @uref{http://www.nongnu.org/texi2html/,Texi2HTML} 1.80 or newer
166 @node Building LilyPond
167 @subsection Building LilyPond
169 @unnumberedsubsubsec Compiling
171 To install GNU LilyPond, type
174 gunzip -c lilypond-x.y.z | tar xf -
176 ./configure # run with --help for applicable options
182 If you are not root, you should choose a @code{--prefix} argument that
183 points into your home directory, e.g.
186 ./configure --prefix=$HOME/usr
190 @unnumberedsubsubsec Compiling for multiple platforms
192 If you want to build multiple versions of LilyPond with different
193 configuration settings, you can use the @code{--enable-config=CONF}
194 option of @command{configure}. You should use @code{make conf=CONF}
195 to generate the output in @file{out-CONF}. For example, suppose you
196 want to build with and without profiling, then use the following for
200 ./configure --prefix=$HOME/usr/ --enable-checking
205 and for the profiling version, specify a different configuration
208 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
210 make conf=prof install
214 @unnumberedsubsubsec Compiling outside the source tree
216 It is possible to compile LilyPond in a build tree different from the
217 source tree, with @code{--srcdir} option of @command{configure}:
220 mkdir lily-build && cd lily-build
221 @var{sourcedir}/configure --srcdir=@var{sourcedir}
226 @unnumberedsubsubsec Useful @command{make} variables
228 If a less verbose build output if desired, the variable
229 @code{QUIET_BUILD} may be set to @code{1} on @command{make} command
230 line, or in @file{local.make} at top of the build tree.
233 @node Building documentation
234 @subsection Building documentation
236 This requires a successful compile of LilyPond, or using an external
240 * Commands for building documentation:: Compiling and installing the documentation.
241 * Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
244 @node Commands for building documentation
245 @unnumberedsubsubsec Commands for building documentation
247 The documentation is built by issuing
253 After compilation, the HTML documentation tree is available in
254 @file{out-www/offline-root/}, and can be browsed locally.
256 The HTML and PDF files can be installed into the standard documentation
264 This also installs Info documentation with images if the installation
265 prefix is properly set; otherwise, instructions for manual installation
266 of Info documentation are printed on standard output.
268 It is also possible to build a documentation tree in
269 @file{out-www/online-root/}, with special processing, so it can be used
270 on a website with content negotiation for automatic language selection;
271 this can be achieved by issuing
274 make WEB_TARGETS=online web
278 and both @q{offline} and @q{online} targets can be generated by issuing
281 make WEB_TARGETS="offline online" web
284 Several targets are available to clean the documentation build and
285 help with maintaining documentation; an overview of these targets is
293 from every directory in the build tree. Most targets for
294 documentation maintenance are available from @file{Documentation/};
295 for more information, see @file{Documentation/user/README.txt} and
296 @file{Documentation/TRANSLATION}.
298 The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a
299 less verbose build output, just like for building the programs.
303 The most time consuming task for building the documentation is running
304 LilyPond to build images of music, and there cannot be several
305 simultaneously running @command{lilypond-book} instances, so @code{-j}
306 @command{make} option does not significantly speed up the build process.
307 To help speed it up, the makefile variable @var{CPU_COUNT} may be set
308 in @file{local.make} or on the command line to the number of
309 @code{.ly} files that LilyPond should process simultaneously, e.g. on
310 a bi-processor or dual core machine
313 make -j3 CPU_COUNT=3 web
317 The recommended value of @var{CPU_COUNT} is one plus the number of
318 cores or processors, but it is advisable to set it to a smaller value
319 if your system has not enough RAM to run that many simultaneous
322 If source files have changed since last documentation build, output
323 files that need to be rebuilt are normally rebuilt, even if you do not
324 run @code{make web-clean} first. However, building dependencies in the
325 documentation are so complex that rebuilding of some targets may not
326 be triggered as they should be; a workaround is to force rebuilding
327 by touching appropriate files, e.g.
330 touch Documentation/user/*.itely
335 @node Building documentation without compiling LilyPond
336 @unnumberedsubsubsec Building documentation without compiling LilyPond
338 The documentation can be built locally without compiling LilyPond
339 binary, if LilyPond is already installed on your system.
341 From a fresh Git checkout, do
344 ./autogen.sh # ignore any warning messages
345 cp GNUmakefile.in GNUmakefile
347 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
350 Please note that this may break sometimes -- for example, if a new
351 feature is added with a test file in input/regression, even the latest
352 development release of LilyPond will fail to build the docs.
354 You may build the manual without building all the @file{input/*}
355 stuff: change directory, for example to @file{Documentation/user},
356 issue @code{make web}, which will build documentation in a
357 subdirectory @file{out-www} from the source files in current
358 directory. In this case, if you also want to browse the documentation
359 in its post-processed form, change back to top directory and issue
362 make out=www WWW-post
367 You may also need to create a script for @command{pngtopnm} and
368 @code{pnmtopng}. On GNU/Linux, I use this:
371 export LD_LIBRARY_PATH=/usr/lib
372 exec /usr/bin/pngtopnm "$@"
375 On MacOS@tie{}X, I use this:
378 export DYLD_LIBRARY_PATH=/sw/lib
379 exec /sw/bin/pngtopnm "$@"
384 @node Testing LilyPond
385 @subsection Testing LilyPond
388 <a name="testing"></a>
391 LilyPond comes with an extensive suite that exercises the entire
392 program. This suite can be used to automatically check the impact of a
393 change. This is done as follows
397 @emph{## apply your changes, compile}
401 This will leave an HTML page @file{out/test-results/index.html}. This
402 page shows all the important differences that your change introduced,
403 whether in the layout, MIDI, performance or error reporting.
408 make test-redo @emph{## redo files differing from baseline}
409 make test-clean @emph{## remove all test results}
413 and then run @code{make check} again.
415 For tracking memory usage as part of this test, you will need GUILE
416 CVS; especially the following patch:
417 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
419 For checking the coverage of the test suite, do the following
422 ./scripts/auxiliar/build-coverage.sh
423 @emph{# uncovered files, least covered first}
424 ./scripts/auxiliar/coverage.py --summary out-cov/*.cc
425 @emph{# consecutive uncovered lines, longest first}
426 ./scripts/auxiliar/coverage.py --uncovered out-cov/*.cc
433 For help and questions use @email{lilypond-user@@gnu.org}. Send bug
434 reports to @email{bug-lilypond@@gnu.org}.
436 Bugs that are not fault of LilyPond are documented here.
438 @unnumberedsubsubsec Bison 1.875
440 There is a bug in bison-1.875: compilation fails with "parse error
441 before `goto'" in line 4922 due to a bug in bison. To fix, please
442 recompile bison 1.875 with the following fix
445 $ cd lily; make out/parser.cc
446 $ vi +4919 out/parser.cc
447 # append a semicolon to the line containing "__attribute__ ((__unused__))
453 @unnumberedsubsubsec Solaris
455 Solaris7, ./configure
457 @file{./configure} needs a POSIX compliant shell. On Solaris7,
458 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
459 is. Run configure like
462 CONFIG_SHELL=/bin/ksh ksh -c ./configure
469 CONFIG_SHELL=/bin/bash bash -c ./configure
472 @unnumberedsubsubsec FreeBSD
474 To use system fonts, dejaview must be installed. With the default
475 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
477 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
478 following line just after the @code{<fontconfig>} line. (Adjust as necessary
482 <dir>/usr/X11R6/lib/X11/fonts</dir>
486 @unnumberedsubsubsec International fonts
488 On MacOS@tie{}X, all fonts are installed by default. However, finding all
489 system fonts requires a bit of configuration; see
490 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
491 this post} on the @code{lilypond-user} mailing list.
493 On Linux, international fonts are installed by different means on
494 every distribution. We cannot list the exact commands or packages
495 that are necessary, as each distribution is different, and the exact
496 package names within each distribution changes. Here are some
502 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
503 ttfonts-zh_CN fonts-ja fonts-hebrew
507 apt-get install emacs-intl-fonts xfonts-intl-.* \
508 ttf-kochi-gothic ttf-kochi-mincho \
509 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
516 - how to make a stable version and development version coexist on
519 - how to build with debug info