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