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 without compiling LilyPond::
  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 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}.
 194 @end itemize
 195
 196 The documentation is built by issuing
 197
 198 @example
 199 make web
 200 @end example
 201
 202 After compilation, the HTML documentation tree is available in
 203 @file{out-www/offline-root/}, and can be browsed locally.
 204
 205 The HTML and PDF files can be installed into the standard documentation
 206 path by issuing
 207
 208 @example
 209 make out=www web-install
 210 @end example
 211
 212 It is also possible to build a documentation tree in
 213 @file{out-www/online-root/}, with special processing, so it can be used
 214 on a website with content negotiation for automatic language selection;
 215 this can be achieved by issuing
 216
 217 @example
 218 make WEB_TARGETS=online web
 219 @end example
 220
 221 @noindent
 222 and both @q{offline} and @q{online} targets can be generated by issuing
 223
 224 @example
 225 make WEB_TARGETS="offline online" web
 226 @end example
 227
 228
 229 @node Building LilyPond
 230 @subsection Building LilyPond
 231
 232 @unnumberedsubsubsec Compiling
 233
 234 To install GNU LilyPond, type
 235
 236 @example
 237 gunzip -c lilypond-x.y.z | tar xf -
 238 cd lilypond-x.y.z
 239 ./configure             # run with --help for applicable options
 240 make
 241 make install
 242 @end example
 243
 244 If you are not root, you should choose a @code{--prefix} argument that
 245 points into your home directory, e.g.
 246
 247 @example
 248 ./configure --prefix=$HOME/usr
 249 @end example
 250
 251
 252 @unnumberedsubsubsec Compiling for multiple platforms
 253
 254 If you want to build multiple versions of LilyPond with different
 255 configuration settings, you can use the @code{--enable-config=CONF}
 256 option of configure.  You should use @code{make conf=CONF} to generate
 257 the output in @file{out-CONF}.  Example: Suppose you want to build
 258 with and without profiling, then use the following for the normal
 259 build
 260
 261 @example
 262 ./configure --prefix=$HOME/usr/ --enable-checking
 263 make
 264 make install
 265 @end example
 266
 267 and for the profiling version, specify a different configuration
 268
 269 @example
 270 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
 271 make conf=prof
 272 make conf=prof install
 273 @end example
 274
 275
 276 @node Building documentation without compiling LilyPond
 277 @subsection Building documentation without compiling LilyPond
 278
 279 The documentation can be built locally without compiling LilyPond from
 280 scratch.
 281
 282 From a fresh git checkout, do
 283
 284 @example
 285 ./autogen.sh   % ignore any warning messages
 286 cp GNUmakefile.in GNUmakefile
 287 make -C python
 288 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
 289 % change the lilypond directory as appropriate
 290 @end example
 291
 292 Please note that this may break sometimes -- for example, if a new
 293 feature is added with a test file in input/regression, even the latest
 294 unstable Lily will fail to build the docs.
 295
 296 You may build the manual ( Documentation/user/ ) without building all
 297 the input/* stuff.
 298
 299 @knownissues
 300
 301 You may also need to create a script for @command{pngtopnm} and
 302 @code{pnmtopng}.  On Linux, I use this:
 303
 304 @verbatim
 305 export LD_LIBRARY_PATH=/usr/lib
 306 exec /usr/bin/pngtopnm "$@"
 307 @end verbatim
 308
 309 On MacOS@tie{}X, I use this:
 310
 311 @verbatim
 312 export DYLD_LIBRARY_PATH=/sw/lib
 313 exec /sw/bin/pngtopnm "$@"
 314 @end verbatim
 315
 316 In order to force make to build a complete manual (this does not
 317 rebuild all examples, only things which are changed), I recommend
 318 writing a script like this:
 319
 320 @verbatim
 321 ### run from Documentation/user/
 322 #  possibly required on OS X and/or old texinfo
 323 # ulimit -n 4096
 324 if [ -e out-www/lilypond.texi ]; then rm out-www/lilypond.* ; fi;
 325 if [ -e out-www/lilypond-program.texi ]; then rm
 326 out-www/lilypond-program.* ; fi;
 327 if [ -e out-www/lilypond-learning.texi ]; then rm
 328 out-www/lilypond-learning.* ; fi;
 329 nice make LILYPOND_EXTERNAL_BINARY=~/usr/bin/lilypond web
 330 @end verbatim
 331
 332 To rebuild the complete HTML docs, run the above script from the
 333 @file{Documentation/user/} directory, then run the final line (the
 334 @code{nice make}) from the top source dir.
 335
 336
 337
 338 @node Testing LilyPond
 339 @subsection Testing LilyPond
 340
 341 @html
 342 <a name="testing"></a>
 343 @end html
 344
 345 LilyPond comes with an extensive suite that exercises the entire
 346 program.  This suite can be used to automatically check the impact of a
 347 change.  This is done as follows
 348
 349 @example
 350 make test-baseline
 351 @emph{## apply your changes, compile}
 352 make check
 353 @end example
 354
 355 This will leave an HTML page @file{out/test-results/index.html}.  This
 356 page shows all the important differences that your change introduced,
 357 whether in the layout, MIDI, performance or error reporting.
 358
 359 To rerun tests, use
 360
 361 @example
 362 make test-redo           @emph{## redo files differing from baseline}
 363 make test-clean          @emph{## remove all test results}
 364 @end example
 365
 366 @noindent
 367 and then run @code{make check} again.
 368
 369 For tracking memory usage as part of this test, you will need GUILE
 370 CVS; especially the following patch:
 371 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
 372
 373 For checking the coverage of the test suite, do the following
 374
 375 @example
 376 ./buildscripts/build-coverage.sh
 377 @emph{# uncovered files, least covered first}
 378 python ./buildscripts/coverage.py  --summary out-cov/*.cc
 379 @emph{# consecutive uncovered lines, longest first}
 380 python ./buildscripts/coverage.py  --uncovered out-cov/*.cc
 381 @end example
 382
 383
 384 @node Problems
 385 @subsection Problems
 386
 387 For help and questions use @email{lilypond-user@@gnu.org}.  Send bug
 388 reports to @email{bug-lilypond@@gnu.org}.
 389
 390 Bugs that are not fault of LilyPond are documented here.
 391
 392 @unnumberedsubsubsec Bison 1.875
 393
 394 There is a bug in bison-1.875: compilation fails with "parse error
 395 before `goto'" in line 4922 due to a bug in bison.  To fix, please
 396 recompile bison 1.875 with the following fix
 397
 398 @example
 399 $ cd lily; make out/parser.cc
 400 $ vi +4919 out/parser.cc
 401 # append a semicolon to the line containing "__attribute__ ((__unused__))
 402 # save
 403 $ make
 404 @end example
 405
 406
 407 @unnumberedsubsubsec Solaris
 408
 409 Solaris7, ./configure
 410
 411 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
 412 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 413 is.  Run configure like
 414
 415 @example
 416 CONFIG_SHELL=/bin/ksh ksh -c ./configure
 417 @end example
 418
 419 @noindent
 420 or
 421
 422 @example
 423 CONFIG_SHELL=/bin/bash bash -c ./configure
 424 @end example
 425
 426 @unnumberedsubsubsec FreeBSD
 427
 428 To use system fonts, dejaview must be installed.  With the default
 429 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
 430
 431 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
 432 following line just after the @code{<fontconfig>} line.  (Adjust as necessary
 433 for your hierarchy.)
 434
 435 @example
 436 <dir>/usr/X11R6/lib/X11/fonts</dir>
 437 @end example
 438
 439
 440 @unnumberedsubsubsec International fonts
 441
 442 On MacOS@tie{}X, all fonts are installed by default.  However, finding all
 443 system fonts requires a bit of configuration; see
 444 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
 445 this post} on the @code{lilypond-user} mailing list.
 446
 447 On Linux, international fonts are installed by different means on
 448 every distribution.  We cannot list the exact commands or packages
 449 that are necessary, as each distribution is different, and the exact
 450 package names within each distribution changes.  Here are some
 451 hints, though:
 452
 453 @verbatim
 454 Red Hat Fedora
 455
 456     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
 457          ttfonts-zh_CN fonts-ja fonts-hebrew
 458
 459 Debian GNU/Linux
 460
 461    apt-get install emacs-intl-fonts xfonts-intl-.* \
 462         ttf-kochi-gothic ttf-kochi-mincho \
 463         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 464 @end verbatim
 465