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 When installing a binary package FOO, you may need to install the
54 FOO-devel, libFOO-dev or FOO-dev package too.
58 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
60 @item @uref{http://metafont.tutorial.free.fr/,MetaFont} (mf-nowin, mf, mfw or
61 mfont binaries) and @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html,MetaPost}
62 (mpost binary), usually packaged with a @LaTeX{} distribution like
65 @item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils,t1utils}
66 (version 1.33 or newer recommended).
68 @item New Century Schoolbook fonts, as PFB files. These are shipped with
69 X11 and Ghostscript, and are named @file{c059033l.pfb}
70 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}.
72 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
73 1.8.2 or newer). If you are installing binary packages, you may need to
74 install guile-devel or guile-dev or libguile-dev too.
76 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
78 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 3.4 or
79 newer. 4.x is strongly recommended).
81 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
83 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
85 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}
86 (version 0.17 or newer).
88 @item @uref{http://www.gnu.org/software/flex/,Flex}.
90 @item @uref{http://www.perl.org/,Perl}.
92 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}.
94 @item All packages required for running, including development packages with
95 header files and libraries.
100 @unnumberedsubsubsec Running requirements
102 Running LilyPond requires proper installation of the following software
106 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
107 @item @uref{http://fontconfig.org/,FontConfig} (version 2.2 or newer).
108 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
109 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
110 (version 1.8.2 or newer), or patch 1.8.1 with
111 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
112 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
113 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
114 newer. 8.60 recommended)
115 @item Dejaview. (This is normally installed by default)
118 International fonts are required to create music with international text
122 @unnumberedsubsubsec Requirements for building documentation
124 You can view the documentation online at
125 @uref{http://lilypond.org/doc/}, but you can also build it locally.
126 This process requires a successful compile of LilyPond, and some
127 additional tools and packages:
130 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
132 @item International fonts (see input/regression/utf-8.ly for hints
133 about which font packages are necessary for your platform)
134 @item Ghostscript 8.60 or newer, or 8.50 with the patch from
135 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
137 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
138 @item @uref{http://www.nongnu.org/texi2html/,Texi2HTML} 1.80 or newer
143 @node Building LilyPond
144 @subsection Building LilyPond
146 @unnumberedsubsubsec Compiling
148 To install GNU LilyPond, type
151 gunzip -c lilypond-x.y.z | tar xf -
153 ./configure # run with --help for applicable options
159 If you are not root, you should choose a @code{--prefix} argument that
160 points into your home directory, e.g.
163 ./configure --prefix=$HOME/usr
167 @unnumberedsubsubsec Compiling for multiple platforms
169 If you want to build multiple versions of LilyPond with different
170 configuration settings, you can use the @code{--enable-config=CONF}
171 option of @command{configure}. You should use @code{make conf=CONF}
172 to generate the output in @file{out-CONF}. For example, suppose you
173 want to build with and without profiling, then use the following for
177 ./configure --prefix=$HOME/usr/ --enable-checking
182 and for the profiling version, specify a different configuration
185 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
187 make conf=prof install
191 @unnumberedsubsubsec Compiling outside the source tree
193 It is possible to compile LilyPond in a build tree different from the
194 source tree, with @code{--srcdir} option of @command{configure}:
197 mkdir lily-build && cd lily-build
198 @var{sourcedir}/configure --srcdir=@var{sourcedir}
203 @unnumberedsubsubsec Useful @command{make} variables
205 If a less verbose build output if desired, the variable
206 @code{QUIET_BUILD} may be set to @code{1} on @command{make} command
207 line, or in @file{local.make} at top of the build tree.
210 @node Building documentation
211 @subsection Building documentation
213 This requires a successful compile of LilyPond, or using an external
217 * Commands for building documentation:: Compiling and installing the documentation.
218 * Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
221 @node Commands for building documentation
222 @unnumberedsubsubsec Commands for building documentation
224 The documentation is built by issuing
230 After compilation, the HTML documentation tree is available in
231 @file{out-www/offline-root/}, and can be browsed locally.
233 The HTML and PDF files can be installed into the standard documentation
241 This also installs Info documentation with images if the installation
242 prefix is properly set; otherwise, instructions for manual installation
243 of Info documentation are printed on standard output.
245 It is also possible to build a documentation tree in
246 @file{out-www/online-root/}, with special processing, so it can be used
247 on a website with content negotiation for automatic language selection;
248 this can be achieved by issuing
251 make WEB_TARGETS=online web
255 and both @q{offline} and @q{online} targets can be generated by issuing
258 make WEB_TARGETS="offline online" web
261 Several targets are available to clean the documentation build and
262 help with maintaining documentation; an overview of these targets is
270 from every directory in the build tree. Most targets for
271 documentation maintenance are available from @file{Documentation/};
272 for more information, see @file{Documentation/user/README.txt} and
273 @file{Documentation/TRANSLATION}.
275 The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a
276 less verbose build output, just like for building the programs.
280 The most time consuming task for building the documentation is running
281 LilyPond to build images of music, and there cannot be several
282 simultaneously running @command{lilypond-book} instances, so @code{-j}
283 @command{make} option does not significantly speed up the build process.
284 To help speed it up, the makefile variable @var{CPU_COUNT} may be set
285 in @file{local.make} or on the command line to the number of
286 @code{.ly} files that LilyPond should process simultaneously, e.g. on
287 a bi-processor or dual core machine
290 make -j3 CPU_COUNT=3 web
294 The recommended value of @var{CPU_COUNT} is one plus the number of
295 cores or processors, but it is advisable to set it to a smaller value
296 if your system has not enough RAM to run that many simultaneous
299 If source files have changed since last documentation build, output
300 files that need to be rebuilt are normally rebuilt, even if you do not
301 run @code{make web-clean} first. However, building dependencies in the
302 documentation are so complex that rebuilding of some targets may not
303 be triggered as they should be; a workaround is to force rebuilding
304 by touching appropriate files, e.g.
307 touch Documentation/user/*.itely
312 @node Building documentation without compiling LilyPond
313 @unnumberedsubsubsec Building documentation without compiling LilyPond
315 The documentation can be built locally without compiling LilyPond
316 binary, if LilyPond is already installed on your system.
318 From a fresh Git checkout, do
321 ./autogen.sh # ignore any warning messages
322 cp GNUmakefile.in GNUmakefile
324 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
327 Please note that this may break sometimes -- for example, if a new
328 feature is added with a test file in input/regression, even the latest
329 development release of LilyPond will fail to build the docs.
331 You may build the manual without building all the @file{input/*}
332 stuff: change directory, for example to @file{Documentation/user},
333 issue @code{make web}, which will build documentation in a
334 subdirectory @file{out-www} from the source files in current
335 directory. In this case, if you also want to browse the documentation
336 in its post-processed form, change back to top directory and issue
339 make out=www WWW-post
344 You may also need to create a script for @command{pngtopnm} and
345 @code{pnmtopng}. On GNU/Linux, I use this:
348 export LD_LIBRARY_PATH=/usr/lib
349 exec /usr/bin/pngtopnm "$@"
352 On MacOS@tie{}X, I use this:
355 export DYLD_LIBRARY_PATH=/sw/lib
356 exec /sw/bin/pngtopnm "$@"
361 @node Testing LilyPond
362 @subsection Testing LilyPond
365 <a name="testing"></a>
368 LilyPond comes with an extensive suite that exercises the entire
369 program. This suite can be used to automatically check the impact of a
370 change. This is done as follows
374 @emph{## apply your changes, compile}
378 This will leave an HTML page @file{out/test-results/index.html}. This
379 page shows all the important differences that your change introduced,
380 whether in the layout, MIDI, performance or error reporting.
385 make test-redo @emph{## redo files differing from baseline}
386 make test-clean @emph{## remove all test results}
390 and then run @code{make check} again.
392 For tracking memory usage as part of this test, you will need GUILE
393 CVS; especially the following patch:
394 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
396 For checking the coverage of the test suite, do the following
399 ./scripts/auxiliar/build-coverage.sh
400 @emph{# uncovered files, least covered first}
401 ./scripts/auxiliar/coverage.py --summary out-cov/*.cc
402 @emph{# consecutive uncovered lines, longest first}
403 ./scripts/auxiliar/coverage.py --uncovered out-cov/*.cc
410 For help and questions use @email{lilypond-user@@gnu.org}. Send bug
411 reports to @email{bug-lilypond@@gnu.org}.
413 Bugs that are not fault of LilyPond are documented here.
415 @unnumberedsubsubsec Bison 1.875
417 There is a bug in bison-1.875: compilation fails with "parse error
418 before `goto'" in line 4922 due to a bug in bison. To fix, please
419 recompile bison 1.875 with the following fix
422 $ cd lily; make out/parser.cc
423 $ vi +4919 out/parser.cc
424 # append a semicolon to the line containing "__attribute__ ((__unused__))
430 @unnumberedsubsubsec Solaris
432 Solaris7, ./configure
434 @file{./configure} needs a POSIX compliant shell. On Solaris7,
435 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
436 is. Run configure like
439 CONFIG_SHELL=/bin/ksh ksh -c ./configure
446 CONFIG_SHELL=/bin/bash bash -c ./configure
449 @unnumberedsubsubsec FreeBSD
451 To use system fonts, dejaview must be installed. With the default
452 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
454 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
455 following line just after the @code{<fontconfig>} line. (Adjust as necessary
459 <dir>/usr/X11R6/lib/X11/fonts</dir>
463 @unnumberedsubsubsec International fonts
465 On MacOS@tie{}X, all fonts are installed by default. However, finding all
466 system fonts requires a bit of configuration; see
467 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
468 this post} on the @code{lilypond-user} mailing list.
470 On Linux, international fonts are installed by different means on
471 every distribution. We cannot list the exact commands or packages
472 that are necessary, as each distribution is different, and the exact
473 package names within each distribution changes. Here are some
479 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
480 ttfonts-zh_CN fonts-ja fonts-hebrew
484 apt-get install emacs-intl-fonts xfonts-intl-.* \
485 ttf-kochi-gothic ttf-kochi-mincho \
486 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi