1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of install.itely and ../devel/compiling.itexi
4 @c DO NOT TRANSLATE THIS FILE
6 @node Compiling from source
7 @section Compiling from source
10 * Downloading source code::
13 * Building documentation::
18 @node Downloading source code
19 @subsection Downloading source code
25 @uref{http://lilypond.org/download/} by HTTP.
27 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
29 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
32 git clone git://git.sv.gnu.org/lilypond.git
35 The repository does not contain generated files. To create
42 For information on packaging, see @uref{http://lilypond.org/devel}.
46 @subsection Requirements
48 @unnumberedsubsubsec Compilation
50 In addition to the packages needed for running LilyPond (see below), you
51 need the following extra packages for building.
53 Below is a full list of packages needed to build LilyPond. However, for
54 most common distributions there is an easy way of installing most all
55 build dependencies in one go
57 @multitable @columnfractions .5 .5
58 @headitem Distribution
62 @tab @code{sudo apt-get build-dep lilypond}
65 @tab @code{sudo yum-builddep lilypond}
68 @c sorry for the idiosyncratic command, I really asked and argued
69 @c for "zypper build-dep" :-(
70 @tab @code{sudo zypper --build-deps-only source-install lilypond}
74 When installing a binary package FOO, you may need to install the
75 FOO-devel, libFOO-dev or FOO-dev package too.
79 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
81 @item @uref{http://metafont.tutorial.free.fr/,MetaFont} (mf-nowin, mf, mfw or
82 mfont binaries) and @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html,MetaPost}
83 (mpost binary), usually packaged with a @LaTeX{} distribution like
86 @item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils,t1utils}
87 (version 1.33 or newer recommended).
89 @item New Century Schoolbook fonts, as PFB files. These are shipped with
90 X11 and Ghostscript, and are named @file{c059033l.pfb}
91 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}.
93 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
94 1.8.2 or newer). If you are installing binary packages, you may need to
95 install guile-devel or guile-dev or libguile-dev too.
97 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
99 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 3.4 or
100 newer. 4.x is strongly recommended).
102 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
104 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
106 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}
107 (version 0.17 or newer).
109 @item @uref{http://www.gnu.org/software/flex/,Flex}.
111 @item @uref{http://www.perl.org/,Perl}.
113 @item @uref{http://www.gnu.org/software/bison/,GNU Bison}.
115 @item All packages required for running, including development packages with
116 header files and libraries.
121 @unnumberedsubsubsec Running requirements
123 Running LilyPond requires proper installation of the following software
127 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
128 @item @uref{http://fontconfig.org/,FontConfig} (version 2.2 or newer).
129 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
130 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
131 (version 1.8.2 or newer), or patch 1.8.1 with
132 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
133 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
134 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
135 newer. 8.60 recommended)
136 @item Dejaview. (This is normally installed by default)
139 International fonts are required to create music with international text
143 @unnumberedsubsubsec Requirements for building documentation
145 You can view the documentation online at
146 @uref{http://lilypond.org/doc/}, but you can also build it locally.
147 This process requires a successful compile of LilyPond, and some
148 additional tools and packages:
151 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
153 @item International fonts (see input/regression/utf-8.ly for hints
154 about which font packages are necessary for your platform)
155 @item Ghostscript 8.60 or newer, or 8.50 with the patch from
156 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
158 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
159 @item @uref{http://www.nongnu.org/texi2html/,Texi2HTML} 1.80 or newer
164 @node Building LilyPond
165 @subsection Building LilyPond
167 @unnumberedsubsubsec Compiling
169 To install GNU LilyPond, type
172 gunzip -c lilypond-x.y.z | tar xf -
174 ./configure # run with --help for applicable options
180 If you are not root, you should choose a @code{--prefix} argument that
181 points into your home directory, e.g.
184 ./configure --prefix=$HOME/usr
188 @unnumberedsubsubsec Compiling for multiple platforms
190 If you want to build multiple versions of LilyPond with different
191 configuration settings, you can use the @code{--enable-config=CONF}
192 option of @command{configure}. You should use @code{make conf=CONF}
193 to generate the output in @file{out-CONF}. For example, suppose you
194 want to build with and without profiling, then use the following for
198 ./configure --prefix=$HOME/usr/ --enable-checking
203 and for the profiling version, specify a different configuration
206 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
208 make conf=prof install
212 @unnumberedsubsubsec Compiling outside the source tree
214 It is possible to compile LilyPond in a build tree different from the
215 source tree, with @code{--srcdir} option of @command{configure}:
218 mkdir lily-build && cd lily-build
219 @var{sourcedir}/configure --srcdir=@var{sourcedir}
224 @unnumberedsubsubsec Useful @command{make} variables
226 If a less verbose build output if desired, the variable
227 @code{QUIET_BUILD} may be set to @code{1} on @command{make} command
228 line, or in @file{local.make} at top of the build tree.
231 @node Building documentation
232 @subsection Building documentation
234 This requires a successful compile of LilyPond, or using an external
238 * Commands for building documentation:: Compiling and installing the documentation.
239 * Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
242 @node Commands for building documentation
243 @unnumberedsubsubsec Commands for building documentation
245 The documentation is built by issuing
251 After compilation, the HTML documentation tree is available in
252 @file{out-www/offline-root/}, and can be browsed locally.
254 The HTML, PDF and if available Info files can be installed into the
255 standard documentation path by issuing
262 This also installs Info documentation with images if the installation
263 prefix is properly set; otherwise, instructions to complete proper
264 installation of Info documentation are printed on standard output.
266 Compilation of documentation in Info format with images can be done
267 separately by issuing
274 Separate installation of this documentation is done by issuing
281 Note that to get the images in Info documentation, @code{install-doc}
282 target creates symbolic links to HTML and PDF installed documentation
283 tree in @file{@var{prefix}/share/info}, in order to save disk space,
284 whereas @code{install-info} copies images in
285 @file{@var{prefix}/share/info} subdirectories.
287 It is possible to build a documentation tree in
288 @file{out-www/online-root/}, with special processing, so it can be
289 used on a website with content negotiation for automatic language
290 selection; this can be achieved by issuing
293 make WEB_TARGETS=online doc
297 and both @q{offline} and @q{online} targets can be generated by issuing
300 make WEB_TARGETS="offline online" doc
303 Several targets are available to clean the documentation build and
304 help with maintaining documentation; an overview of these targets is
312 from every directory in the build tree. Most targets for
313 documentation maintenance are available from @file{Documentation/};
315 for more information, see the Contributors' Guide, section
316 @emph{Documentation work}.
318 The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a
319 less verbose build output, just like for building the programs.
324 The most time consuming task for building the documentation is running
325 LilyPond to build images of music, and there cannot be several
326 simultaneously running @command{lilypond-book} instances, so @code{-j}
327 @command{make} option does not significantly speed up the build process.
328 To help speed it up, the makefile variable @var{CPU_COUNT} may be set
329 in @file{local.make} or on the command line to the number of
330 @code{.ly} files that LilyPond should process simultaneously, e.g. on
331 a bi-processor or dual core machine
334 make -j3 CPU_COUNT=3 doc
338 The recommended value of @var{CPU_COUNT} is one plus the number of
339 cores or processors, but it is advisable to set it to a smaller value
340 if your system has not enough RAM to run that many simultaneous
343 If source files have changed since last documentation build, output
344 files that need to be rebuilt are normally rebuilt, even if you do not
345 run @code{make doc-clean} first. However, building dependencies in the
346 documentation are so complex that rebuilding of some targets may not
347 be triggered as they should be; a workaround is to force rebuilding
348 by touching appropriate files, e.g.
351 touch Documentation/user/*.itely
356 @node Building documentation without compiling LilyPond
357 @unnumberedsubsubsec Building documentation without compiling LilyPond
359 The documentation can be built locally without compiling LilyPond
360 binary, if LilyPond is already installed on your system.
362 From a fresh Git checkout, do
365 ./autogen.sh # ignore any warning messages
366 cp GNUmakefile.in GNUmakefile
368 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
371 Please note that this may break sometimes -- for example, if a new
372 feature is added with a test file in input/regression, even the latest
373 development release of LilyPond will fail to build the docs.
375 You may build the manual without building all the @file{input/*}
376 stuff: change directory, for example to @file{Documentation/user},
377 issue @code{make doc}, which will build documentation in a
378 subdirectory @file{out-www} from the source files in current
379 directory. In this case, if you also want to browse the documentation
380 in its post-processed form, change back to top directory and issue
383 make out=www WWW-post
388 You may also need to create a script for @command{pngtopnm} and
389 @code{pnmtopng}. On GNU/Linux, I use this:
392 export LD_LIBRARY_PATH=/usr/lib
393 exec /usr/bin/pngtopnm "$@"
396 On MacOS@tie{}X, I use this:
399 export DYLD_LIBRARY_PATH=/sw/lib
400 exec /sw/bin/pngtopnm "$@"
405 @node Testing LilyPond
406 @subsection Testing LilyPond
409 <a name="testing"></a>
412 LilyPond comes with an extensive suite that exercises the entire
413 program. This suite can be used to automatically check the impact of a
414 change. This is done as follows
418 @emph{## apply your changes, compile}
422 This will leave an HTML page @file{out/test-results/index.html}. This
423 page shows all the important differences that your change introduced,
424 whether in the layout, MIDI, performance or error reporting.
429 make test-redo @emph{## redo files differing from baseline}
430 make test-clean @emph{## remove all test results}
434 and then run @code{make check} again.
436 For tracking memory usage as part of this test, you will need GUILE
437 CVS; especially the following patch:
438 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
440 For checking the coverage of the test suite, do the following
443 ./scripts/auxiliar/build-coverage.sh
444 @emph{# uncovered files, least covered first}
445 ./scripts/auxiliar/coverage.py --summary out-cov/*.cc
446 @emph{# consecutive uncovered lines, longest first}
447 ./scripts/auxiliar/coverage.py --uncovered out-cov/*.cc
454 For help and questions use @email{lilypond-user@@gnu.org}. Send bug
455 reports to @email{bug-lilypond@@gnu.org}.
457 Bugs that are not fault of LilyPond are documented here.
459 @unnumberedsubsubsec Bison 1.875
461 There is a bug in bison-1.875: compilation fails with "parse error
462 before `goto'" in line 4922 due to a bug in bison. To fix, please
463 recompile bison 1.875 with the following fix
466 $ cd lily; make out/parser.cc
467 $ vi +4919 out/parser.cc
468 # append a semicolon to the line containing "__attribute__ ((__unused__))
474 @unnumberedsubsubsec Solaris
476 Solaris7, ./configure
478 @file{./configure} needs a POSIX compliant shell. On Solaris7,
479 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
480 is. Run configure like
483 CONFIG_SHELL=/bin/ksh ksh -c ./configure
490 CONFIG_SHELL=/bin/bash bash -c ./configure
493 @unnumberedsubsubsec FreeBSD
495 To use system fonts, dejaview must be installed. With the default
496 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
498 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
499 following line just after the @code{<fontconfig>} line. (Adjust as necessary
503 <dir>/usr/X11R6/lib/X11/fonts</dir>
507 @unnumberedsubsubsec International fonts
509 On MacOS@tie{}X, all fonts are installed by default. However, finding all
510 system fonts requires a bit of configuration; see
511 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
512 this post} on the @code{lilypond-user} mailing list.
514 On Linux, international fonts are installed by different means on
515 every distribution. We cannot list the exact commands or packages
516 that are necessary, as each distribution is different, and the exact
517 package names within each distribution changes. Here are some
523 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
524 ttfonts-zh_CN fonts-ja fonts-hebrew
528 apt-get install emacs-intl-fonts xfonts-intl-.* \
529 ttf-kochi-gothic ttf-kochi-mincho \
530 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi