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 New Century Schoolbook fonts, as PFB files.  These are shipped with
 126 X11 and Ghostscript, and are named @file{c059033l.pfb}
 127 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}
 128
 129 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
 130 1.8.2 or newer).  If you are installing binary packages, you may need to
 131 install guile-devel or guile-dev or libguile-dev too.
 132
 133 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
 134
 135 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 3.4 or
 136 newer.  4.x is strongly recommended).
 137
 138 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
 139
 140 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
 141
 142 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
 143
 144 @item @uref{http://www.gnu.org/software/flex/,Flex}
 145
 146 @item @uref{http://www.perl.org/,Perl}
 147
 148 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}
 149
 150 @item All packages required for running, including development packages with
 151 header files and libraries.
 152
 153 @end itemize
 154
 155
 156 @unnumberedsubsubsec Running requirements
 157
 158 Running LilyPond requires proper installation of the following software
 159
 160 @itemize
 161
 162 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
 163 @item @uref{http://www.freetype.org/,FontConfig} (version 2.2).
 164 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
 165 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
 166 (version 1.8.2 or newer), or patch 1.8.1 with
 167 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
 168 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
 169 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
 170 newer. 8.50 recommended)
 171 @item Dejaview.  (This is normally installed by default)
 172 @end itemize
 173
 174 International fonts are required to create music with international text
 175 or lyrics.
 176
 177
 178 @unnumberedsubsubsec Requirements for building documentation
 179
 180 You can view the documentation online at
 181 @uref{http://lilypond.org/doc/}, but you can also build it locally.
 182 This process requires a successful compile of LilyPond, and some
 183 additional tools and packages
 184
 185 @itemize
 186 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
 187 @item ImageMagick
 188 @item International fonts (see input/regression/utf-8.ly for hints
 189 about which font packages are necessary for your platform)
 190 @item Ghostscript, 8.50 with the patch from
 191 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
 192 and the patch from
 193 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}, or use
 194 a release of Ghostscript which includes these patches, for example
 195 8.60 or newer.
 196 @end itemize
 197
 198
 199 @node Building LilyPond
 200 @subsection Building LilyPond
 201
 202 @unnumberedsubsubsec Compiling
 203
 204 To install GNU LilyPond, type
 205
 206 @example
 207 gunzip -c lilypond-x.y.z | tar xf -
 208 cd lilypond-x.y.z
 209 ./configure             # run with --help for applicable options
 210 make
 211 su -c 'make install'
 212 @end example
 213
 214 @noindent
 215 If you are not root, you should choose a @code{--prefix} argument that
 216 points into your home directory, e.g.
 217
 218 @example
 219 ./configure --prefix=$HOME/usr
 220 @end example
 221
 222
 223 @unnumberedsubsubsec Compiling for multiple platforms
 224
 225 If you want to build multiple versions of LilyPond with different
 226 configuration settings, you can use the @code{--enable-config=CONF}
 227 option of @command{configure}.  You should use @code{make conf=CONF}
 228 to generate the output in @file{out-CONF}.  For example, suppose you
 229 want to build with and without profiling, then use the following for
 230 the normal build
 231
 232 @example
 233 ./configure --prefix=$HOME/usr/ --enable-checking
 234 make
 235 make install
 236 @end example
 237
 238 and for the profiling version, specify a different configuration
 239
 240 @example
 241 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
 242 make conf=prof
 243 make conf=prof install
 244 @end example
 245
 246
 247 @unnumberedsubsubsec Compiling outside the source tree
 248
 249 It is possible to compile LilyPond in a build tree different from the
 250 source tree, with @code{--srcdir} option of @command{configure}:
 251
 252 @example
 253 mkdir lily-build && cd lily-build
 254 @var{sourcedir}/configure --srcdir=@var{sourcedir}
 255
 256 @end example
 257
 258 @node Building documentation
 259 @subsection Building documentation
 260
 261 This requires a successful compile of LilyPond, or using an external
 262 LilyPond binary.
 263
 264 @menu
 265 * Commands for building documentation:: Compiling and installing the documentation.
 266 * Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
 267 @end menu
 268
 269 @node Commands for building documentation
 270 @unnumberedsubsubsec Commands for building documentation
 271
 272 The documentation is built by issuing
 273
 274 @example
 275 make web
 276 @end example
 277
 278 After compilation, the HTML documentation tree is available in
 279 @file{out-www/offline-root/}, and can be browsed locally.
 280
 281 The HTML and PDF files can be installed into the standard documentation
 282 path by issuing
 283
 284 @example
 285 make web-install
 286 @end example
 287
 288 @noindent
 289 This also installs Info documentation with images if the installation
 290 prefix is properly set; otherwise, instructions for manual installation
 291 of Info documentation are printed on standard output.
 292
 293 It is also possible to build a documentation tree in
 294 @file{out-www/online-root/}, with special processing, so it can be used
 295 on a website with content negotiation for automatic language selection;
 296 this can be achieved by issuing
 297
 298 @example
 299 make WEB_TARGETS=online web
 300 @end example
 301
 302 @noindent
 303 and both @q{offline} and @q{online} targets can be generated by issuing
 304
 305 @example
 306 make WEB_TARGETS="offline online" web
 307 @end example
 308
 309 Several targets are available to clean the documentation build and
 310 help with maintaining documentation; an overview of these targets is
 311 available with
 312
 313 @example
 314 make help
 315 @end example
 316
 317 @noindent
 318 from every directory in the build tree.  Most targets for
 319 documentation maintenance are available from @file{Documentation/};
 320 for more information, see @file{Documentation/user/README.txt} and
 321 @file{Documentation/TRANSLATION}.
 322
 323 @knownissues
 324
 325 If source files have changed since last documentation build, output
 326 files that need to be rebuilt are normally rebuilt, even if you do not
 327 run @code{make web-clean} first.  However, building dependencies in the
 328 documentation are so complex that rebuilding of some targets may not
 329 be triggered as they should be; a workaround is to force rebuilding
 330 by touching appropriate files, e.g.
 331
 332 @example
 333 touch Documentation/user/*.itely
 334 touch input/lsr/*.ly
 335 @end example
 336
 337
 338 @node Building documentation without compiling LilyPond
 339 @unnumberedsubsubsec Building documentation without compiling LilyPond
 340
 341 The documentation can be built locally without compiling LilyPond
 342 binary, if LilyPond is already installed on your system.
 343
 344 From a fresh Git checkout, do
 345
 346 @example
 347 ./autogen.sh   # ignore any warning messages
 348 cp GNUmakefile.in GNUmakefile
 349 make -C python
 350 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
 351 @end example
 352
 353 Please note that this may break sometimes -- for example, if a new
 354 feature is added with a test file in input/regression, even the latest
 355 development release of LilyPond will fail to build the docs.
 356
 357 You may build the manual without building all the @file{input/*}
 358 stuff: change directory, for example to @file{Documentation/user},
 359 issue @code{make web}, which will build documentation in a
 360 subdirectory @file{out-www} from the source files in current
 361 directory.  In this case, if you also want to browse the documentation
 362 in its post-processed form, change back to top directory and issue
 363
 364 @example
 365 make out=www WWW-post
 366 @end example
 367
 368 @knownissues
 369
 370 You may also need to create a script for @command{pngtopnm} and
 371 @code{pnmtopng}.  On GNU/Linux, I use this:
 372
 373 @verbatim
 374 export LD_LIBRARY_PATH=/usr/lib
 375 exec /usr/bin/pngtopnm "$@"
 376 @end verbatim
 377
 378 On MacOS@tie{}X, I use this:
 379
 380 @verbatim
 381 export DYLD_LIBRARY_PATH=/sw/lib
 382 exec /sw/bin/pngtopnm "$@"
 383 @end verbatim
 384
 385
 386
 387 @node Testing LilyPond
 388 @subsection Testing LilyPond
 389
 390 @html
 391 <a name="testing"></a>
 392 @end html
 393
 394 LilyPond comes with an extensive suite that exercises the entire
 395 program.  This suite can be used to automatically check the impact of a
 396 change.  This is done as follows
 397
 398 @example
 399 make test-baseline
 400 @emph{## apply your changes, compile}
 401 make check
 402 @end example
 403
 404 This will leave an HTML page @file{out/test-results/index.html}.  This
 405 page shows all the important differences that your change introduced,
 406 whether in the layout, MIDI, performance or error reporting.
 407
 408 To rerun tests, use
 409
 410 @example
 411 make test-redo           @emph{## redo files differing from baseline}
 412 make test-clean          @emph{## remove all test results}
 413 @end example
 414
 415 @noindent
 416 and then run @code{make check} again.
 417
 418 For tracking memory usage as part of this test, you will need GUILE
 419 CVS; especially the following patch:
 420 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
 421
 422 For checking the coverage of the test suite, do the following
 423
 424 @example
 425 ./buildscripts/build-coverage.sh
 426 @emph{# uncovered files, least covered first}
 427 python ./buildscripts/coverage.py  --summary out-cov/*.cc
 428 @emph{# consecutive uncovered lines, longest first}
 429 python ./buildscripts/coverage.py  --uncovered out-cov/*.cc
 430 @end example
 431
 432
 433 @node Problems
 434 @subsection Problems
 435
 436 For help and questions use @email{lilypond-user@@gnu.org}.  Send bug
 437 reports to @email{bug-lilypond@@gnu.org}.
 438
 439 Bugs that are not fault of LilyPond are documented here.
 440
 441 @unnumberedsubsubsec Bison 1.875
 442
 443 There is a bug in bison-1.875: compilation fails with "parse error
 444 before `goto'" in line 4922 due to a bug in bison.  To fix, please
 445 recompile bison 1.875 with the following fix
 446
 447 @example
 448 $ cd lily; make out/parser.cc
 449 $ vi +4919 out/parser.cc
 450 # append a semicolon to the line containing "__attribute__ ((__unused__))
 451 # save
 452 $ make
 453 @end example
 454
 455
 456 @unnumberedsubsubsec Solaris
 457
 458 Solaris7, ./configure
 459
 460 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
 461 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 462 is.  Run configure like
 463
 464 @example
 465 CONFIG_SHELL=/bin/ksh ksh -c ./configure
 466 @end example
 467
 468 @noindent
 469 or
 470
 471 @example
 472 CONFIG_SHELL=/bin/bash bash -c ./configure
 473 @end example
 474
 475 @unnumberedsubsubsec FreeBSD
 476
 477 To use system fonts, dejaview must be installed.  With the default
 478 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
 479
 480 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
 481 following line just after the @code{<fontconfig>} line.  (Adjust as necessary
 482 for your hierarchy.)
 483
 484 @example
 485 <dir>/usr/X11R6/lib/X11/fonts</dir>
 486 @end example
 487
 488
 489 @unnumberedsubsubsec International fonts
 490
 491 On MacOS@tie{}X, all fonts are installed by default.  However, finding all
 492 system fonts requires a bit of configuration; see
 493 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
 494 this post} on the @code{lilypond-user} mailing list.
 495
 496 On Linux, international fonts are installed by different means on
 497 every distribution.  We cannot list the exact commands or packages
 498 that are necessary, as each distribution is different, and the exact
 499 package names within each distribution changes.  Here are some
 500 hints, though:
 501
 502 @verbatim
 503 Red Hat Fedora
 504
 505     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
 506          ttfonts-zh_CN fonts-ja fonts-hebrew
 507
 508 Debian GNU/Linux
 509
 510    apt-get install emacs-intl-fonts xfonts-intl-.* \
 511         ttf-kochi-gothic ttf-kochi-mincho \
 512         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 513 @end verbatim
 514