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 If source files have changed since last documentation build, output
 329 files that need to be rebuilt are normally rebuilt, even if you do not
 330 run @code{make web-clean} first.  However, building dependencies in the
 331 documentation are so complex that rebuilding of some targets may not
 332 be triggered as they should be; a workaround is to force rebuilding
 333 by touching appropriate files, e.g.
 334
 335 @example
 336 touch Documentation/user/*.itely
 337 touch input/lsr/*.ly
 338 @end example
 339
 340
 341 @node Building documentation without compiling LilyPond
 342 @unnumberedsubsubsec Building documentation without compiling LilyPond
 343
 344 The documentation can be built locally without compiling LilyPond
 345 binary, if LilyPond is already installed on your system.
 346
 347 From a fresh Git checkout, do
 348
 349 @example
 350 ./autogen.sh   # ignore any warning messages
 351 cp GNUmakefile.in GNUmakefile
 352 make -C python
 353 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
 354 @end example
 355
 356 Please note that this may break sometimes -- for example, if a new
 357 feature is added with a test file in input/regression, even the latest
 358 development release of LilyPond will fail to build the docs.
 359
 360 You may build the manual without building all the @file{input/*}
 361 stuff: change directory, for example to @file{Documentation/user},
 362 issue @code{make web}, which will build documentation in a
 363 subdirectory @file{out-www} from the source files in current
 364 directory.  In this case, if you also want to browse the documentation
 365 in its post-processed form, change back to top directory and issue
 366
 367 @example
 368 make out=www WWW-post
 369 @end example
 370
 371 @knownissues
 372
 373 You may also need to create a script for @command{pngtopnm} and
 374 @code{pnmtopng}.  On GNU/Linux, I use this:
 375
 376 @verbatim
 377 export LD_LIBRARY_PATH=/usr/lib
 378 exec /usr/bin/pngtopnm "$@"
 379 @end verbatim
 380
 381 On MacOS@tie{}X, I use this:
 382
 383 @verbatim
 384 export DYLD_LIBRARY_PATH=/sw/lib
 385 exec /sw/bin/pngtopnm "$@"
 386 @end verbatim
 387
 388
 389
 390 @node Testing LilyPond
 391 @subsection Testing LilyPond
 392
 393 @html
 394 <a name="testing"></a>
 395 @end html
 396
 397 LilyPond comes with an extensive suite that exercises the entire
 398 program.  This suite can be used to automatically check the impact of a
 399 change.  This is done as follows
 400
 401 @example
 402 make test-baseline
 403 @emph{## apply your changes, compile}
 404 make check
 405 @end example
 406
 407 This will leave an HTML page @file{out/test-results/index.html}.  This
 408 page shows all the important differences that your change introduced,
 409 whether in the layout, MIDI, performance or error reporting.
 410
 411 To rerun tests, use
 412
 413 @example
 414 make test-redo           @emph{## redo files differing from baseline}
 415 make test-clean          @emph{## remove all test results}
 416 @end example
 417
 418 @noindent
 419 and then run @code{make check} again.
 420
 421 For tracking memory usage as part of this test, you will need GUILE
 422 CVS; especially the following patch:
 423 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
 424
 425 For checking the coverage of the test suite, do the following
 426
 427 @example
 428 ./buildscripts/build-coverage.sh
 429 @emph{# uncovered files, least covered first}
 430 python ./buildscripts/coverage.py  --summary out-cov/*.cc
 431 @emph{# consecutive uncovered lines, longest first}
 432 python ./buildscripts/coverage.py  --uncovered out-cov/*.cc
 433 @end example
 434
 435
 436 @node Problems
 437 @subsection Problems
 438
 439 For help and questions use @email{lilypond-user@@gnu.org}.  Send bug
 440 reports to @email{bug-lilypond@@gnu.org}.
 441
 442 Bugs that are not fault of LilyPond are documented here.
 443
 444 @unnumberedsubsubsec Bison 1.875
 445
 446 There is a bug in bison-1.875: compilation fails with "parse error
 447 before `goto'" in line 4922 due to a bug in bison.  To fix, please
 448 recompile bison 1.875 with the following fix
 449
 450 @example
 451 $ cd lily; make out/parser.cc
 452 $ vi +4919 out/parser.cc
 453 # append a semicolon to the line containing "__attribute__ ((__unused__))
 454 # save
 455 $ make
 456 @end example
 457
 458
 459 @unnumberedsubsubsec Solaris
 460
 461 Solaris7, ./configure
 462
 463 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
 464 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 465 is.  Run configure like
 466
 467 @example
 468 CONFIG_SHELL=/bin/ksh ksh -c ./configure
 469 @end example
 470
 471 @noindent
 472 or
 473
 474 @example
 475 CONFIG_SHELL=/bin/bash bash -c ./configure
 476 @end example
 477
 478 @unnumberedsubsubsec FreeBSD
 479
 480 To use system fonts, dejaview must be installed.  With the default
 481 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
 482
 483 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
 484 following line just after the @code{<fontconfig>} line.  (Adjust as necessary
 485 for your hierarchy.)
 486
 487 @example
 488 <dir>/usr/X11R6/lib/X11/fonts</dir>
 489 @end example
 490
 491
 492 @unnumberedsubsubsec International fonts
 493
 494 On MacOS@tie{}X, all fonts are installed by default.  However, finding all
 495 system fonts requires a bit of configuration; see
 496 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
 497 this post} on the @code{lilypond-user} mailing list.
 498
 499 On Linux, international fonts are installed by different means on
 500 every distribution.  We cannot list the exact commands or packages
 501 that are necessary, as each distribution is different, and the exact
 502 package names within each distribution changes.  Here are some
 503 hints, though:
 504
 505 @verbatim
 506 Red Hat Fedora
 507
 508     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
 509          ttfonts-zh_CN fonts-ja fonts-hebrew
 510
 511 Debian GNU/Linux
 512
 513    apt-get install emacs-intl-fonts xfonts-intl-.* \
 514         ttf-kochi-gothic ttf-kochi-mincho \
 515         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 516 @end verbatim
 517