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