1 @c -*- coding: utf-8; mode: texinfo; -*-
4 @c DO NOT TRANSLATE THIS FILE
6 @c include any node/sections from the higher-level *texi file.
7 @c @n ode Compiling from source
8 @c @s ection Compiling from source
11 * Downloading source code::
14 * Building documentation::
19 @node Downloading source code
20 @subsection Downloading source code
26 @uref{http://lilypond.org/download/} by HTTP.
28 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
30 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
33 git clone git://git.sv.gnu.org/lilypond.git
36 The repository does not contain generated files. To create
43 For information on packaging, see @uref{http://lilypond.org/devel}.
47 @subsection Requirements
49 @unnumberedsubsubsec Compilation
51 In addition to the packages needed for running LilyPond (see below), you
52 need the following extra packages for building.
54 Below is a full list of packages needed to build LilyPond. However, for
55 most common distributions there is an easy way of installing most all
56 build dependencies in one go
58 @multitable @columnfractions .5 .5
59 @headitem Distribution
63 @tab @code{sudo apt-get build-dep lilypond}
66 @tab @code{sudo yum-builddep lilypond}
69 @c sorry for the idiosyncratic command, I really asked and argued
70 @c for "zypper build-dep" :-(
71 @tab @code{sudo zypper --build-deps-only source-install lilypond}
75 When installing a binary package FOO, you may need to install the
76 FOO-devel, libFOO-dev or FOO-dev package too.
80 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
82 @item @uref{http://metafont.tutorial.free.fr/,MetaFont} (mf-nowin, mf, mfw or
83 mfont binaries) and @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html,MetaPost}
84 (mpost binary), usually packaged with a @LaTeX{} distribution like
87 @item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils,t1utils}
88 (version 1.33 or newer recommended).
90 @item New Century Schoolbook fonts, as PFB files. These are shipped with
91 X11 and Ghostscript, and are named @file{c059033l.pfb}
92 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}.
94 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
95 1.8.2 or newer). If you are installing binary packages, you may need to
96 install guile-devel or guile-dev or libguile-dev too.
98 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
100 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 3.4 or
101 newer. 4.x is strongly recommended).
103 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
105 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
107 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}
108 (version 0.17 or newer).
110 @item @uref{http://www.gnu.org/software/flex/,Flex}.
112 @item @uref{http://www.perl.org/,Perl}.
114 @item @uref{http://www.gnu.org/software/bison/,GNU Bison}.
116 @item All packages required for running, including development packages with
117 header files and libraries.
122 @unnumberedsubsubsec Running requirements
124 Running LilyPond requires proper installation of the following software
128 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
129 @item @uref{http://fontconfig.org/,FontConfig} (version 2.2 or newer).
130 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
131 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
132 (version 1.8.2 or newer), or patch 1.8.1 with
133 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
134 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
135 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
136 newer. 8.60 recommended)
137 @item Dejaview. (This is normally installed by default)
140 International fonts are required to create music with international text
144 @unnumberedsubsubsec Requirements for building documentation
146 You can view the documentation online at
147 @uref{http://lilypond.org/doc/}, but you can also build it locally.
148 This process requires a successful compile of LilyPond, and some
149 additional tools and packages:
152 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
154 @item International fonts (see input/regression/utf-8.ly for hints
155 about which font packages are necessary for your platform)
156 @item Ghostscript 8.60 or newer, or 8.50 with the patch from
157 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
159 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
160 @item @uref{http://www.nongnu.org/texi2html/,Texi2HTML} 1.82 or newer
165 @node Building LilyPond
166 @subsection Building LilyPond
168 @unnumberedsubsubsec Compiling
170 To install GNU LilyPond, type
173 gunzip -c lilypond-x.y.z | tar xf -
175 ./configure # run with --help for applicable options
181 If you are not root, you should choose a @code{--prefix} argument that
182 points into your home directory, e.g.
185 ./configure --prefix=$HOME/usr
188 If you encounter any problems, please see @ref{Problems}.
191 @unnumberedsubsubsec Compiling for multiple platforms
193 If you want to build multiple versions of LilyPond with different
194 configuration settings, you can use the @code{--enable-config=CONF}
195 option of @command{configure}. You should use @code{make conf=CONF}
196 to generate the output in @file{out-CONF}. For example, suppose you
197 want to build with and without profiling, then use the following for
201 ./configure --prefix=$HOME/usr/ --enable-checking
206 and for the profiling version, specify a different configuration
209 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
211 make conf=prof install
215 @unnumberedsubsubsec Compiling outside the source tree
217 It is possible to compile LilyPond in a build tree different from the
218 source tree, with @code{--srcdir} option of @command{configure}:
221 mkdir lily-build && cd lily-build
222 @var{sourcedir}/configure --srcdir=@var{sourcedir}
227 @unnumberedsubsubsec Useful @command{make} variables
229 If a less verbose build output if desired, the variable
230 @code{QUIET_BUILD} may be set to @code{1} on @command{make} command
231 line, or in @file{local.make} at top of the build tree.
234 @node Building documentation
235 @subsection Building documentation
237 This requires a successful compile of LilyPond, or using an external
241 * Commands for building documentation:: Compiling and installing the documentation.
242 * Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
245 @node Commands for building documentation
246 @unnumberedsubsubsec Commands for building documentation
248 The documentation is built by issuing
254 After compilation, the HTML documentation tree is available in
255 @file{out-www/offline-root/}, and can be browsed locally.
257 The HTML, PDF and if available Info files can be installed into the
258 standard documentation path by issuing
265 This also installs Info documentation with images if the installation
266 prefix is properly set; otherwise, instructions to complete proper
267 installation of Info documentation are printed on standard output.
269 Compilation of documentation in Info format with images can be done
270 separately by issuing
277 Separate installation of this documentation is done by issuing
284 Note that to get the images in Info documentation, @code{install-doc}
285 target creates symbolic links to HTML and PDF installed documentation
286 tree in @file{@var{prefix}/share/info}, in order to save disk space,
287 whereas @code{install-info} copies images in
288 @file{@var{prefix}/share/info} subdirectories.
290 It is possible to build a documentation tree in
291 @file{out-www/online-root/}, with special processing, so it can be
292 used on a website with content negotiation for automatic language
293 selection; this can be achieved by issuing
296 make WEB_TARGETS=online doc
300 and both @q{offline} and @q{online} targets can be generated by issuing
303 make WEB_TARGETS="offline online" doc
306 Several targets are available to clean the documentation build and
307 help with maintaining documentation; an overview of these targets is
315 from every directory in the build tree. Most targets for
316 documentation maintenance are available from @file{Documentation/};
318 for more information, see the Contributors' Guide, section
319 @emph{Documentation work}.
321 The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a
322 less verbose build output, just like for building the programs.
327 The most time consuming task for building the documentation is running
328 LilyPond to build images of music, and there cannot be several
329 simultaneously running @command{lilypond-book} instances, so @code{-j}
330 @command{make} option does not significantly speed up the build process.
331 To help speed it up, the makefile variable @var{CPU_COUNT} may be set
332 in @file{local.make} or on the command line to the number of
333 @code{.ly} files that LilyPond should process simultaneously, e.g. on
334 a bi-processor or dual core machine
337 make -j3 CPU_COUNT=3 doc
341 The recommended value of @var{CPU_COUNT} is one plus the number of
342 cores or processors, but it is advisable to set it to a smaller value
343 if your system has not enough RAM to run that many simultaneous
346 If source files have changed since last documentation build, output
347 files that need to be rebuilt are normally rebuilt, even if you do not
348 run @code{make doc-clean} first. However, building dependencies in the
349 documentation are so complex that rebuilding of some targets may not
350 be triggered as they should be; a workaround is to force rebuilding
351 by touching appropriate files, e.g.
354 touch Documentation/notation/*.itely
355 touch Documentation/snippets/*.ly
359 @node Building documentation without compiling LilyPond
360 @unnumberedsubsubsec Building documentation without compiling LilyPond
362 The documentation can be built locally without compiling LilyPond
363 binary, if LilyPond is already installed on your system.
365 From a fresh Git checkout, do
368 ./autogen.sh # ignore any warning messages
369 cp GNUmakefile.in GNUmakefile
371 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
374 Please note that this may break sometimes -- for example, if a new
375 feature is added with a test file in input/regression, even the latest
376 development release of LilyPond will fail to build the docs.
378 You may build the manual without building all the @file{input/*} stuff
379 (i.e. mostly regression tests): change directory, for example to
380 @file{Documentation/}, issue @code{make doc}, which will build
381 documentation in a subdirectory @file{out-www} from the source files in
382 current directory. In this case, if you also want to browse the
383 documentation in its post-processed form, change back to top directory
387 make out=www WWW-post
392 You may also need to create a script for @command{pngtopnm} and
393 @code{pnmtopng}. On GNU/Linux, I use this:
396 export LD_LIBRARY_PATH=/usr/lib
397 exec /usr/bin/pngtopnm "$@"
400 On MacOS X with fink, I use this:
403 export DYLD_LIBRARY_PATH=/sw/lib
404 exec /sw/bin/pngtopnm "$@"
407 On MacOS X with macports, you should use this:
410 export DYLD_LIBRARY_PATH=/opt/local/lib
411 exec /opt/local/bin/pngtopnm "$@"
416 @node Testing LilyPond
417 @subsection Testing LilyPond
420 <a name="testing"></a>
423 LilyPond comes with an extensive suite that exercises the entire
424 program. This suite can be used to automatically check the impact of a
425 change. This is done as follows
429 @emph{## apply your changes, compile}
433 This will leave an HTML page @file{out/test-results/index.html}. This
434 page shows all the important differences that your change introduced,
435 whether in the layout, MIDI, performance or error reporting.
440 make test-redo @emph{## redo files differing from baseline}
441 make test-clean @emph{## remove all test results}
445 and then run @code{make check} again.
447 For tracking memory usage as part of this test, you will need GUILE
448 CVS; especially the following patch:
449 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
451 For checking the coverage of the test suite, do the following
454 ./scripts/auxiliar/build-coverage.sh
455 @emph{# uncovered files, least covered first}
456 ./scripts/auxiliar/coverage.py --summary out-cov/*.cc
457 @emph{# consecutive uncovered lines, longest first}
458 ./scripts/auxiliar/coverage.py --uncovered out-cov/*.cc
465 For help and questions use @email{lilypond-user@@gnu.org}. Send
466 bug reports to @email{bug-lilypond@@gnu.org}.
468 Bugs that are not fault of LilyPond are documented here.
470 @unnumberedsubsubsec Bison 1.875
472 There is a bug in bison-1.875: compilation fails with "parse error
473 before `goto'" in line 4922 due to a bug in bison. To fix, please
474 recompile bison 1.875 with the following fix
477 $ cd lily; make out/parser.cc
478 $ vi +4919 out/parser.cc
479 # append a semicolon to the line containing "__attribute__ ((__unused__))
485 @unnumberedsubsubsec Compiling on MacOS@tie{}X
487 Here are special instructions for compiling under MacOS@tie{}X.
488 These instructions assume that dependencies are installed using
489 @uref{http://www.macports.org/, MacPorts.} The instructions have
490 been tested using OS X 10.5 (Leopard).
492 First, install the relevant dependencies using MacPorts.
494 Next, add the following to your relevant shell initialization
495 files. This is @code{~/.profile} by default. You should create
496 this file if it does not exist.
499 export PATH=/opt/local/bin:/opt/local/sbin:$PATH
500 export DYLD_LIBRARY_PATH=/System/Library/Frameworks/ApplicationServices.framework/Versions/A/Frameworks/ImageIO.framework/Versions/A/Resources:\
501 /opt/local/lib:$DYLD_LIBRARY_PATH
504 Now you must edit the generated @code{config.make} file. Change
507 FLEXLEXER_FILE = /usr/include/FlexLexer.h
514 FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
517 At this point, you should verify that you have the appropriate
518 fonts installed with your ghostscript installation. Check @code{ls
519 /opt/local/share/ghostscript/fonts} for: 'c0590*' files (.pfb,
520 .pfb and .afm). If you don't have them, run the following
521 commands to grab them from the ghostscript SVN server and install
522 them in the appropriate location:
525 svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
526 sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
527 rm -rf urw-fonts-1.07pre44
530 Now run the @code{./configure} script. To avoid complications with
531 automatic font detection, add
534 --with-ncsb-dir=/opt/local/share/ghostscript/fonts
538 @unnumberedsubsubsec Solaris
540 Solaris7, ./configure
542 @file{./configure} needs a POSIX compliant shell. On Solaris7,
543 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
544 is. Run configure like
547 CONFIG_SHELL=/bin/ksh ksh -c ./configure
554 CONFIG_SHELL=/bin/bash bash -c ./configure
557 @unnumberedsubsubsec FreeBSD
559 To use system fonts, dejaview must be installed. With the default
560 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
562 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
563 following line just after the @code{<fontconfig>} line. (Adjust as necessary
567 <dir>/usr/X11R6/lib/X11/fonts</dir>
571 @unnumberedsubsubsec International fonts
573 On Mac OS X, all fonts are installed by default. However, finding all
574 system fonts requires a bit of configuration; see
575 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
576 this post} on the @code{lilypond-user} mailing list.
578 On Linux, international fonts are installed by different means on
579 every distribution. We cannot list the exact commands or packages
580 that are necessary, as each distribution is different, and the exact
581 package names within each distribution changes. Here are some
587 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
588 ttfonts-zh_CN fonts-ja fonts-hebrew
592 apt-get install emacs-intl-fonts xfonts-intl-.* \
593 ttf-kochi-gothic ttf-kochi-mincho \
594 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi