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