Documentation/user/install.itely

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