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)
133 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
134 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.60 or
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
156 @item @uref{http://www.nongnu.org/texi2html/,Texi2HTML} 1.82
161 @node Building LilyPond
162 @subsection Building LilyPond
164 @unnumberedsubsubsec Compiling
166 To install GNU LilyPond, type
169 gunzip -c lilypond-x.y.z | tar xf -
171 ./configure # run with --help for applicable options
177 If you are not root, you should choose a @code{--prefix} argument that
178 points into your home directory, e.g.
181 ./configure --prefix=$HOME/usr
184 If you encounter any problems, please see @ref{Problems}.
187 @unnumberedsubsubsec Compiling for multiple platforms
189 If you want to build multiple versions of LilyPond with different
190 configuration settings, you can use the @code{--enable-config=CONF}
191 option of @command{configure}. You should use @code{make conf=CONF}
192 to generate the output in @file{out-CONF}. For example, suppose you
193 want to build with and without profiling, then use the following for
197 ./configure --prefix=$HOME/usr/ --enable-checking
202 and for the profiling version, specify a different configuration
205 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
207 make conf=prof install
211 @unnumberedsubsubsec Compiling outside the source tree
213 It is possible to compile LilyPond in a build tree different from the
214 source tree, with @code{--srcdir} option of @command{configure}:
217 mkdir lily-build && cd lily-build
218 @var{sourcedir}/configure --srcdir=@var{sourcedir}
223 @unnumberedsubsubsec Useful @command{make} variables
225 If a less verbose build output if desired, the variable
226 @code{QUIET_BUILD} may be set to @code{1} on @command{make} command
227 line, or in @file{local.make} at top of the build tree.
230 @node Building documentation
231 @subsection Building documentation
233 This requires a successful compile of LilyPond, or using an external
237 * Commands for building documentation:: Compiling and installing the documentation.
238 * Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
241 @node Commands for building documentation
242 @unnumberedsubsubsec Commands for building documentation
244 The documentation is built by issuing
250 After compilation, the HTML documentation tree is available in
251 @file{out-www/offline-root/}, and can be browsed locally. Various
252 portions of the documentation can be found by looking in
253 @file{out/} and @file{out-www} subdirectories in other places in
254 the source tree, but these are only @emph{portions} of the docs.
255 Please do not complain about anything which is broken in those
256 places; the only complete set of documentation is in
257 @file{out-www/offline-root/} from the top of the source tree.
259 The HTML, PDF and if available Info files can be installed into the
260 standard documentation path by issuing
267 This also installs Info documentation with images if the installation
268 prefix is properly set; otherwise, instructions to complete proper
269 installation of Info documentation are printed on standard output.
271 Compilation of documentation in Info format with images can be done
272 separately by issuing
279 Separate installation of this documentation is done by issuing
286 Note that to get the images in Info documentation, @code{install-doc}
287 target creates symbolic links to HTML and PDF installed documentation
288 tree in @file{@var{prefix}/share/info}, in order to save disk space,
289 whereas @code{install-info} copies images in
290 @file{@var{prefix}/share/info} subdirectories.
292 It is possible to build a documentation tree in
293 @file{out-www/online-root/}, with special processing, so it can be
294 used on a website with content negotiation for automatic language
295 selection; this can be achieved by issuing
298 make WEB_TARGETS=online doc
302 and both @q{offline} and @q{online} targets can be generated by issuing
305 make WEB_TARGETS="offline online" doc
308 Several targets are available to clean the documentation build and
309 help with maintaining documentation; an overview of these targets is
317 from every directory in the build tree. Most targets for
318 documentation maintenance are available from
319 @file{Documentation/}. For more information, see
320 @rcontrib{Documentation work}.
322 The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a
323 less verbose build output, just like for building the programs.
328 The most time consuming task for building the documentation is running
329 LilyPond to build images of music, and there cannot be several
330 simultaneously running @command{lilypond-book} instances, so @code{-j}
331 @command{make} option does not significantly speed up the build process.
332 To help speed it up, the makefile variable @var{CPU_COUNT} may be set
333 in @file{local.make} or on the command line to the number of
334 @code{.ly} files that LilyPond should process simultaneously, e.g. on
335 a bi-processor or dual core machine
338 make -j3 CPU_COUNT=3 doc
342 The recommended value of @var{CPU_COUNT} is one plus the number of
343 cores or processors, but it is advisable to set it to a smaller value
344 if your system has not enough RAM to run that many simultaneous
347 If source files have changed since last documentation build, output
348 files that need to be rebuilt are normally rebuilt, even if you do not
349 run @code{make doc-clean} first. However, building dependencies in the
350 documentation are so complex that rebuilding of some targets may not
351 be triggered as they should be; a workaround is to force rebuilding
352 by touching appropriate files, e.g.
355 touch Documentation/extend.texi
356 touch Documentation/*te??
357 touch Documentation/snippets/*.te??
361 @node Building documentation without compiling LilyPond
362 @unnumberedsubsubsec Building documentation without compiling LilyPond
364 The documentation can be built locally without compiling LilyPond
365 binary, if LilyPond is already installed on your system.
367 From a fresh Git checkout, do
370 ./autogen.sh # ignore any warning messages
371 cp GNUmakefile.in GNUmakefile
372 make -C scripts && make -C python
373 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
376 Please note that this may break sometimes -- for example, if a new
377 feature is added with a test file in input/regression, even the latest
378 development release of LilyPond will fail to build the docs.
380 You may build the manual without building all the @file{input/*} stuff
381 (i.e. mostly regression tests): change directory, for example to
382 @file{Documentation/}, issue @code{make doc}, which will build
383 documentation in a subdirectory @file{out-www} from the source files in
384 current directory. In this case, if you also want to browse the
385 documentation in its post-processed form, change back to top directory
389 make out=www WWW-post
394 You may also need to create a script for @command{pngtopnm} and
395 @code{pnmtopng}. On GNU/Linux, I use this:
398 export LD_LIBRARY_PATH=/usr/lib
399 exec /usr/bin/pngtopnm "$@"
402 On MacOS X with fink, I use this:
405 export DYLD_LIBRARY_PATH=/sw/lib
406 exec /sw/bin/pngtopnm "$@"
409 On MacOS X with macports, you should use this:
412 export DYLD_LIBRARY_PATH=/opt/local/lib
413 exec /opt/local/bin/pngtopnm "$@"
418 @node Testing LilyPond
419 @subsection Testing LilyPond
422 <a name="testing"></a>
425 LilyPond comes with an extensive suite that exercises the entire
426 program. This suite can be used to automatically check the impact of a
427 change. This is done as follows
431 @emph{## apply your changes, compile}
435 This will leave an HTML page @file{out/test-results/index.html}. This
436 page shows all the important differences that your change introduced,
437 whether in the layout, MIDI, performance or error reporting.
442 make test-redo @emph{## redo files differing from baseline}
443 make test-clean @emph{## remove all test results}
447 and then run @code{make check} again.
449 For tracking memory usage as part of this test, you will need GUILE
450 CVS; especially the following patch:
451 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
453 For checking the coverage of the test suite, do the following
456 ./scripts/auxiliar/build-coverage.sh
457 @emph{# uncovered files, least covered first}
458 ./scripts/auxiliar/coverage.py --summary out-cov/*.cc
459 @emph{# consecutive uncovered lines, longest first}
460 ./scripts/auxiliar/coverage.py --uncovered out-cov/*.cc
467 For help and questions use @email{lilypond-user@@gnu.org}. Send
468 bug reports to @email{bug-lilypond@@gnu.org}.
470 Bugs that are not fault of LilyPond are documented here.
472 @unnumberedsubsubsec Bison 1.875
474 There is a bug in bison-1.875: compilation fails with "parse error
475 before `goto'" in line 4922 due to a bug in bison. To fix, please
476 recompile bison 1.875 with the following fix
479 $ cd lily; make out/parser.cc
480 $ vi +4919 out/parser.cc
481 # append a semicolon to the line containing "__attribute__ ((__unused__))
487 @unnumberedsubsubsec Compiling on MacOS@tie{}X
489 Here are special instructions for compiling under MacOS@tie{}X.
490 These instructions assume that dependencies are installed using
491 @uref{http://www.macports.org/, MacPorts.} The instructions have
492 been tested using OS X 10.5 (Leopard).
494 First, install the relevant dependencies using MacPorts.
496 Next, add the following to your relevant shell initialization
497 files. This is @code{~/.profile} by default. You should create
498 this file if it does not exist.
501 export PATH=/opt/local/bin:/opt/local/sbin:$PATH
502 export DYLD_LIBRARY_PATH=/System/Library/Frameworks/ApplicationServices.framework/Versions/A/Frameworks/ImageIO.framework/Versions/A/Resources:\
503 /opt/local/lib:$DYLD_LIBRARY_PATH
506 Now you must edit the generated @code{config.make} file. Change
509 FLEXLEXER_FILE = /usr/include/FlexLexer.h
516 FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
519 At this point, you should verify that you have the appropriate
520 fonts installed with your ghostscript installation. Check @code{ls
521 /opt/local/share/ghostscript/fonts} for: 'c0590*' files (.pfb,
522 .pfb and .afm). If you don't have them, run the following
523 commands to grab them from the ghostscript SVN server and install
524 them in the appropriate location:
527 svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
528 sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
529 rm -rf urw-fonts-1.07pre44
532 Now run the @code{./configure} script. To avoid complications with
533 automatic font detection, add
536 --with-ncsb-dir=/opt/local/share/ghostscript/fonts
540 @unnumberedsubsubsec Solaris
542 Solaris7, ./configure
544 @file{./configure} needs a POSIX compliant shell. On Solaris7,
545 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
546 is. Run configure like
549 CONFIG_SHELL=/bin/ksh ksh -c ./configure
556 CONFIG_SHELL=/bin/bash bash -c ./configure
559 @unnumberedsubsubsec FreeBSD
561 To use system fonts, dejaview must be installed. With the default
562 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
564 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
565 following line just after the @code{<fontconfig>} line. (Adjust as necessary
569 <dir>/usr/X11R6/lib/X11/fonts</dir>
573 @unnumberedsubsubsec International fonts
575 On Mac OS X, all fonts are installed by default. However, finding all
576 system fonts requires a bit of configuration; see
577 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
578 this post} on the @code{lilypond-user} mailing list.
580 On Linux, international fonts are installed by different means on
581 every distribution. We cannot list the exact commands or packages
582 that are necessary, as each distribution is different, and the exact
583 package names within each distribution changes. Here are some
589 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
590 ttfonts-zh_CN fonts-ja fonts-hebrew
594 apt-get install emacs-intl-fonts xfonts-intl-.* \
595 ttf-kochi-gothic ttf-kochi-mincho \
596 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
600 @unnumberedsubsubsec Using lilypond python libraries
602 If you want to use lilypond's python libraries (either running
603 certain build scripts manually, or using them in other programs),
604 set @code{PYTHONPATH} to @file{python/out} in your build
605 directory, or @file{.../usr/lib/lilypond/current/python} in the
606 installation directory structure.