Documentation/devel/compiling.itexi

   1 @c -*- coding: us-ascii; mode: texinfo; -*-
   2 @node Compiling from source
   3 @chapter Compiling from source
   4
   5 @ignore
   6 You can also compile LilyPond directly from the source code. This
   7 requires that you can read English, so this section is not
   8 translated.  If you really want to compile LilyPond, see
   9 @iftex
  10 @c DO NOT translate the following line at all.
  11 @ref{Compiling from source,,,lilypond-program,Application Usage}.
  12 @end iftex
  13 @ifhtml
  14 @c Please translate the following line (but not the .html file name)
  15 the @uref{Compiling-from-source.html,documentation in English}.
  16 @end ifhtml
  17 @end ignore
  18
  19 @c TRANSLATORS:
  20 @c   Please **do not** translate anything below this line.  Users
  21 @c   should not be compiling LilyPond themselves; if they really
  22 @c   want to do so, they should be able to read the English docs,
  23 @c   because they'll probably need to ask questions in English
  24 @c   on the -devel list.   -gp
  25 @c Instead, please uncomment and translate the paragraph above,
  26 @c and remove all stuff (menu, nodes, contents) below this line.
  27
  28 @menu
  29 * Downloading source code::
  30 * Requirements::
  31 * Building LilyPond::
  32 * Building documentation::
  33 * Testing LilyPond::
  34 * Problems::
  35 @end menu
  36
  37 @node Downloading source code
  38 @section Downloading source code
  39
  40 Download source
  41
  42 @itemize
  43 @item tarballs from
  44 @uref{http://lilypond.org/download/} by HTTP.
  45 @item tarballs from
  46 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
  47 @item
  48 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
  49
  50 @example
  51 git clone git://git.sv.gnu.org/lilypond.git
  52 @end example
  53
  54 The repository does not contain generated files.  To create
  55 @file{configure}, run
  56 @example
  57 ./autogen.sh
  58 @end example
  59 @end itemize
  60
  61 For information on packaging, see @uref{http://lilypond.org/devel}.
  62
  63
  64 @node Requirements
  65 @section Requirements
  66
  67 @unnumberedsubsubsec Compilation
  68
  69 In addition to the packages needed for running LilyPond (see below), you
  70 need the following extra packages for building.
  71
  72 When installing a binary package FOO, you may need to install the
  73 FOO-devel, libFOO-dev or FOO-dev package too.
  74
  75 @itemize
  76
  77 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
  78
  79 @item @uref{http://metafont.tutorial.free.fr/,MetaFont} (mf-nowin, mf, mfw or
  80 mfont binaries) and @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html,MetaPost}
  81 (mpost binary), usually packaged with a @LaTeX{} distribution like
  82 tetex or texlive.
  83
  84 @item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils,t1utils}
  85 (version 1.33 or newer recommended).
  86
  87 @item New Century Schoolbook fonts, as PFB files.  These are shipped with
  88 X11 and Ghostscript, and are named @file{c059033l.pfb}
  89 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}.
  90
  91 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
  92 1.8.2 or newer).  If you are installing binary packages, you may need to
  93 install guile-devel or guile-dev or libguile-dev too.
  94
  95 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
  96
  97 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 3.4 or
  98 newer.  4.x is strongly recommended).
  99
 100 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
 101
 102 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
 103
 104 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}
 105 (version 0.17 or newer).
 106
 107 @item @uref{http://www.gnu.org/software/flex/,Flex}.
 108
 109 @item @uref{http://www.perl.org/,Perl}.
 110
 111 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}.
 112
 113 @item All packages required for running, including development packages with
 114 header files and libraries.
 115
 116 @end itemize
 117
 118
 119 @unnumberedsubsubsec Running requirements
 120
 121 Running LilyPond requires proper installation of the following software
 122
 123 @itemize
 124
 125 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
 126 @item @uref{http://fontconfig.org/,FontConfig} (version 2.2 or newer).
 127 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
 128 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
 129 (version 1.8.2 or newer), or patch 1.8.1 with
 130 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
 131 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
 132 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
 133 newer. 8.60 recommended)
 134 @item Dejaview.  (This is normally installed by default)
 135 @end itemize
 136
 137 International fonts are required to create music with international text
 138 or lyrics.
 139
 140
 141 @unnumberedsubsubsec Requirements for building documentation
 142
 143 You can view the documentation online at
 144 @uref{http://lilypond.org/doc/}, but you can also build it locally.
 145 This process requires a successful compile of LilyPond, and some
 146 additional tools and packages:
 147
 148 @itemize
 149 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
 150 @item ImageMagick
 151 @item International fonts (see input/regression/utf-8.ly for hints
 152 about which font packages are necessary for your platform)
 153 @item Ghostscript 8.60 or newer, or 8.50 with the patch from
 154 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
 155 and the patch from
 156 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
 157 @item @uref{http://www.nongnu.org/texi2html/,Texi2HTML} 1.80 or newer
 158 @item rsync
 159 @end itemize
 160
 161
 162 @node Building LilyPond
 163 @section Building LilyPond
 164
 165 @unnumberedsubsubsec Compiling
 166
 167 To install GNU LilyPond, type
 168
 169 @example
 170 gunzip -c lilypond-x.y.z | tar xf -
 171 cd lilypond-x.y.z
 172 ./configure             # run with --help for applicable options
 173 make
 174 su -c 'make install'
 175 @end example
 176
 177 @noindent
 178 If you are not root, you should choose a @code{--prefix} argument that
 179 points into your home directory, e.g.
 180
 181 @example
 182 ./configure --prefix=$HOME/usr
 183 @end example
 184
 185
 186 @unnumberedsubsubsec Compiling for multiple platforms
 187
 188 If you want to build multiple versions of LilyPond with different
 189 configuration settings, you can use the @code{--enable-config=CONF}
 190 option of @command{configure}.  You should use @code{make conf=CONF}
 191 to generate the output in @file{out-CONF}.  For example, suppose you
 192 want to build with and without profiling, then use the following for
 193 the normal build
 194
 195 @example
 196 ./configure --prefix=$HOME/usr/ --enable-checking
 197 make
 198 make install
 199 @end example
 200
 201 and for the profiling version, specify a different configuration
 202
 203 @example
 204 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
 205 make conf=prof
 206 make conf=prof install
 207 @end example
 208
 209
 210 @unnumberedsubsubsec Compiling outside the source tree
 211
 212 It is possible to compile LilyPond in a build tree different from the
 213 source tree, with @code{--srcdir} option of @command{configure}:
 214
 215 @example
 216 mkdir lily-build && cd lily-build
 217 @var{sourcedir}/configure --srcdir=@var{sourcedir}
 218
 219 @end example
 220
 221
 222 @unnumberedsubsubsec Useful @command{make} variables
 223
 224 If a less verbose build output if desired, the variable
 225 @code{QUIET_BUILD} may be set to @code{1} on @command{make} command
 226 line, or in @file{local.make} at top of the build tree.
 227
 228
 229 @node Building documentation
 230 @section Building documentation
 231
 232 This requires a successful compile of LilyPond, or using an external
 233 LilyPond binary.
 234
 235 @menu
 236 * Commands for building documentation:: Compiling and installing the documentation.
 237 * Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
 238 @end menu
 239
 240 @node Commands for building documentation
 241 @unnumberedsubsec Commands for building documentation
 242
 243 The documentation is built by issuing
 244
 245 @example
 246 make web
 247 @end example
 248
 249 After compilation, the HTML documentation tree is available in
 250 @file{out-www/offline-root/}, and can be browsed locally.
 251
 252 The HTML and PDF files can be installed into the standard documentation
 253 path by issuing
 254
 255 @example
 256 make web-install
 257 @end example
 258
 259 @noindent
 260 This also installs Info documentation with images if the installation
 261 prefix is properly set; otherwise, instructions for manual installation
 262 of Info documentation are printed on standard output.
 263
 264 It is also possible to build a documentation tree in
 265 @file{out-www/online-root/}, with special processing, so it can be used
 266 on a website with content negotiation for automatic language selection;
 267 this can be achieved by issuing
 268
 269 @example
 270 make WEB_TARGETS=online web
 271 @end example
 272
 273 @noindent
 274 and both @q{offline} and @q{online} targets can be generated by issuing
 275
 276 @example
 277 make WEB_TARGETS="offline online" web
 278 @end example
 279
 280 Several targets are available to clean the documentation build and
 281 help with maintaining documentation; an overview of these targets is
 282 available with
 283
 284 @example
 285 make help
 286 @end example
 287
 288 @noindent
 289 from every directory in the build tree.  Most targets for
 290 documentation maintenance are available from @file{Documentation/};
 291 for more information, see @file{Documentation/user/README.txt} and
 292 @file{Documentation/TRANSLATION}.
 293
 294 The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a
 295 less verbose build output, just like for building the programs.
 296
 297 @knownissues
 298
 299 The most time consuming task for building the documentation is running
 300 LilyPond to build images of music, and there cannot be several
 301 simultaneously running @command{lilypond-book} instances, so @code{-j}
 302 @command{make} option does not significantly speed up the build process.
 303 To help speed it up, the makefile variable @var{CPU_COUNT} may be set
 304 in @file{local.make} or on the command line to the number of
 305 @code{.ly} files that LilyPond should process simultaneously, e.g. on
 306 a bi-processor or dual core machine
 307
 308 @example
 309 make -j3 CPU_COUNT=3 web
 310 @end example
 311
 312 @noindent
 313 The recommended value of @var{CPU_COUNT} is one plus the number of
 314 cores or processors, but it is advisable to set it to a smaller value
 315 if your system has not enough RAM to run that many simultaneous
 316 LilyPond instances.
 317
 318 If source files have changed since last documentation build, output
 319 files that need to be rebuilt are normally rebuilt, even if you do not
 320 run @code{make web-clean} first.  However, building dependencies in the
 321 documentation are so complex that rebuilding of some targets may not
 322 be triggered as they should be; a workaround is to force rebuilding
 323 by touching appropriate files, e.g.
 324
 325 @example
 326 touch Documentation/user/*.itely
 327 touch input/lsr/*.ly
 328 @end example
 329
 330
 331 @node Building documentation without compiling LilyPond
 332 @unnumberedsubsec Building documentation without compiling LilyPond
 333
 334 The documentation can be built locally without compiling LilyPond
 335 binary, if LilyPond is already installed on your system.
 336
 337 From a fresh Git checkout, do
 338
 339 @example
 340 ./autogen.sh   # ignore any warning messages
 341 cp GNUmakefile.in GNUmakefile
 342 make -C python
 343 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
 344 @end example
 345
 346 Please note that this may break sometimes -- for example, if a new
 347 feature is added with a test file in input/regression, even the latest
 348 development release of LilyPond will fail to build the docs.
 349
 350 You may build the manual without building all the @file{input/*}
 351 stuff: change directory, for example to @file{Documentation/user},
 352 issue @code{make web}, which will build documentation in a
 353 subdirectory @file{out-www} from the source files in current
 354 directory.  In this case, if you also want to browse the documentation
 355 in its post-processed form, change back to top directory and issue
 356
 357 @example
 358 make out=www WWW-post
 359 @end example
 360
 361 @knownissues
 362
 363 You may also need to create a script for @command{pngtopnm} and
 364 @code{pnmtopng}.  On GNU/Linux, I use this:
 365
 366 @verbatim
 367 export LD_LIBRARY_PATH=/usr/lib
 368 exec /usr/bin/pngtopnm "$@"
 369 @end verbatim
 370
 371 On MacOS@tie{}X, I use this:
 372
 373 @verbatim
 374 export DYLD_LIBRARY_PATH=/sw/lib
 375 exec /sw/bin/pngtopnm "$@"
 376 @end verbatim
 377
 378
 379
 380 @node Testing LilyPond
 381 @section Testing LilyPond
 382
 383 @html
 384 <a name="testing"></a>
 385 @end html
 386
 387 LilyPond comes with an extensive suite that exercises the entire
 388 program.  This suite can be used to automatically check the impact of a
 389 change.  This is done as follows
 390
 391 @example
 392 make test-baseline
 393 @emph{## apply your changes, compile}
 394 make check
 395 @end example
 396
 397 This will leave an HTML page @file{out/test-results/index.html}.  This
 398 page shows all the important differences that your change introduced,
 399 whether in the layout, MIDI, performance or error reporting.
 400
 401 To rerun tests, use
 402
 403 @example
 404 make test-redo           @emph{## redo files differing from baseline}
 405 make test-clean          @emph{## remove all test results}
 406 @end example
 407
 408 @noindent
 409 and then run @code{make check} again.
 410
 411 For tracking memory usage as part of this test, you will need GUILE
 412 CVS; especially the following patch:
 413 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
 414
 415 For checking the coverage of the test suite, do the following
 416
 417 @example
 418 ./scripts/auxiliar/build-coverage.sh
 419 @emph{# uncovered files, least covered first}
 420 ./scripts/auxiliar/coverage.py  --summary out-cov/*.cc
 421 @emph{# consecutive uncovered lines, longest first}
 422 ./scripts/auxiliar/coverage.py  --uncovered out-cov/*.cc
 423 @end example
 424
 425
 426 @node Problems
 427 @section Problems
 428
 429 For help and questions use @email{lilypond-user@@gnu.org}.  Send bug
 430 reports to @email{bug-lilypond@@gnu.org}.
 431
 432 Bugs that are not fault of LilyPond are documented here.
 433
 434 @unnumberedsubsubsec Bison 1.875
 435
 436 There is a bug in bison-1.875: compilation fails with "parse error
 437 before `goto'" in line 4922 due to a bug in bison.  To fix, please
 438 recompile bison 1.875 with the following fix
 439
 440 @example
 441 $ cd lily; make out/parser.cc
 442 $ vi +4919 out/parser.cc
 443 # append a semicolon to the line containing "__attribute__ ((__unused__))
 444 # save
 445 $ make
 446 @end example
 447
 448
 449 @unnumberedsubsubsec Solaris
 450
 451 Solaris7, ./configure
 452
 453 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
 454 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 455 is.  Run configure like
 456
 457 @example
 458 CONFIG_SHELL=/bin/ksh ksh -c ./configure
 459 @end example
 460
 461 @noindent
 462 or
 463
 464 @example
 465 CONFIG_SHELL=/bin/bash bash -c ./configure
 466 @end example
 467
 468 @unnumberedsubsubsec FreeBSD
 469
 470 To use system fonts, dejaview must be installed.  With the default
 471 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
 472
 473 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
 474 following line just after the @code{<fontconfig>} line.  (Adjust as necessary
 475 for your hierarchy.)
 476
 477 @example
 478 <dir>/usr/X11R6/lib/X11/fonts</dir>
 479 @end example
 480
 481
 482 @unnumberedsubsubsec International fonts
 483
 484 On MacOS@tie{}X, all fonts are installed by default.  However, finding all
 485 system fonts requires a bit of configuration; see
 486 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
 487 this post} on the @code{lilypond-user} mailing list.
 488
 489 On Linux, international fonts are installed by different means on
 490 every distribution.  We cannot list the exact commands or packages
 491 that are necessary, as each distribution is different, and the exact
 492 package names within each distribution changes.  Here are some
 493 hints, though:
 494
 495 @verbatim
 496 Red Hat Fedora
 497
 498     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
 499          ttfonts-zh_CN fonts-ja fonts-hebrew
 500
 501 Debian GNU/Linux
 502
 503    apt-get install emacs-intl-fonts xfonts-intl-.* \
 504         ttf-kochi-gothic ttf-kochi-mincho \
 505         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 506 @end verbatim
 507
 508
 509
 510 ALSO ADD:
 511
 512 - how to make a stable version and development version coexist on
 513   your system
 514
 515 - how to build with debug info
 516
 517
 518