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