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 @ifclear INSTALL
  11 @node Install
  12 @chapter Install
  13 @end ifclear
  14
  15 @c  I don't know what this comment does.  Remove?  -gp
  16 @ignore
  17 @h tml
  18 <a name="download-source">
  19 @e nd html
  20 @end ignore
  21
  22 There are two sets of releases for LilyPond: stable releases, and
  23 unstable development releases.  Stable versions have an even-numbered
  24 @q{minor} version number (i.e. 2.8, 2.10, 2.12, etc).  Development
  25 versions have an odd-numbered @q{minor} version number (i.e. 2.7, 2.9,
  26 2.11, etc).
  27
  28 Building LilyPond is a very involved process, so we @strong{highly}
  29 recommend using the precompiled binaries.
  30
  31 @menu
  32 * Precompiled binaries::
  33 * Compiling from source::
  34 @end menu
  35
  36
  37 @node Precompiled binaries
  38 @section Precompiled binaries
  39
  40 @subsection Downloading
  41
  42 Check out @uref{http://lilypond.org/web/install/} for up to date
  43 information on binary packages for your platform.  If your operating
  44 system is not covered on that general page, please see the complete list
  45 at @uref{http://download.linuxaudio.org/lilypond/binaries/}
  46
  47 We currently create binaries for
  48
  49 @example
  50 darwin-ppc  - MacOS X powerpc
  51 darwin-x86  - MacOS X intel
  52 freebsd-64  - FreeBSD 6.x, x86_64
  53 freebsd-x86 - FreeBSD 4.x, x86
  54 linux-64    - Any GNU/Linux distribution, x86_64
  55 linux-arm   - Any GNU/Linux distribution, arm
  56 linux-ppc   - Any GNU/Linux distribution, powerpc
  57 linux-x86   - Any GNU/Linux distribution, x86
  58 mingw       - Windows x86
  59 @end example
  60
  61
  62 @c TRANSLATORS:
  63 @c   Please **do not** translate anything below this line.  Users
  64 @c   should not be compiling LilyPond themselves; if they really
  65 @c   want to do so, they should be able to read the English docs,
  66 @c   because they'll probably need to ask questions in English
  67 @c   on the -devel list.   -gp
  68
  69 @node Compiling from source
  70 @section Compiling from source
  71
  72 @menu
  73 * Downloading source code::
  74 * Requirements::
  75 * Building LilyPond::
  76 * Building documentation without compiling LilyPond::
  77 * Testing LilyPond::
  78 * Problems::
  79 @end menu
  80
  81 @node Downloading source code
  82 @subsection Downloading source code
  83
  84 Download source
  85
  86 @itemize
  87 @item tarballs from
  88 @uref{http://lilypond.org/download/} by HTTP.
  89 @item tarballs from
  90 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
  91 @item
  92 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
  93
  94 @example
  95 git clone git://git.sv.gnu.org/lilypond.git
  96 @end example
  97
  98 The repository does not contain generated files.  To create
  99 @file{configure}, run
 100 @example
 101 ./autogen.sh
 102 @end example
 103 @end itemize
 104
 105 For information on packaging, see @uref{http://lilypond.org/devel}.
 106
 107
 108 @node Requirements
 109 @subsection Requirements
 110
 111 @unnumberedsubsubsec Compilation
 112
 113 In addition to the packages needed for running Lilypond (see below), you
 114 need the following extra packages for building.
 115
 116 When installing a binary package FOO, you may need to install the
 117 FOO-devel, libFOO-dev or FOO-dev package too.
 118
 119 @itemize
 120
 121 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
 122
 123 @item New Century Schoolbook fonts, as PFB files.  These are shipped with
 124 X11 and Ghostscript, and are named @file{c059033l.pfb}
 125 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}
 126
 127 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
 128 1.8.2 or newer).  If you are installing binary packages, you may need to
 129 install guile-devel or guile-dev or libguile-dev too.
 130
 131 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
 132
 133 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 4.x or
 134 newer).
 135
 136 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
 137
 138 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
 139
 140 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
 141
 142 @item @uref{http://www.gnu.org/software/flex/,Flex}
 143
 144 @item @uref{http://www.perl.org/,Perl}
 145
 146 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}
 147
 148 @item All packages required for running, including development packages with
 149 header files and libraries.
 150
 151 @end itemize
 152
 153
 154 @unnumberedsubsubsec Running requirements
 155
 156 Running LilyPond requires proper installation of the following software
 157
 158 @itemize
 159
 160 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
 161 @item @uref{http://www.freetype.org/,FontConfig} (version 2.2).
 162 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
 163 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
 164 (version 1.8.2 or newer), or patch 1.8.1 with
 165 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
 166 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
 167 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
 168 newer. 8.50 recommended)
 169 @item Dejaview.  (This is normally installed by default)
 170 @end itemize
 171
 172 International fonts are required to create music with international text
 173 or lyrics.
 174
 175
 176 @unnumberedsubsubsec Building documentation
 177
 178 You can view the documentation online at
 179 @uref{http://lilypond.org/doc/}, but you can also build it locally.
 180 This process requires a successful compile of lilypond, and some
 181 additional tools and packages
 182
 183 @itemize
 184 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
 185 @item ImageMagick
 186 @item International fonts (see input/regression/utf-8.ly for hints
 187 about which font packages are necessary for your platform)
 188 @item Ghostscript, 8.50 with the patch from
 189 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
 190 and the patch from
 191 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
 192 @end itemize
 193
 194 The documentation is built by issuing
 195
 196 @example
 197 make web
 198 @end example
 199
 200 After compilation, the HTML documentation tree is available in
 201 @file{out-www/offline-root/}, and can be browsed locally.
 202
 203 The HTML and PDF files can be installed into the standard documentation
 204 path by issuing
 205
 206 @example
 207 make out=www web-install
 208 @end example
 209
 210 It is also possible to build a documentation tree in
 211 @file{out-www/online-root/}, with special processing, so it can be used
 212 on a website with content negotiation for automatic language selection;
 213 this can be achieved by issuing
 214
 215 @example
 216 make WEB_TARGETS=online web
 217 @end example
 218
 219 @noindent
 220 and both @q{offline} and @q{online} targets can be generated by issuing
 221
 222 @example
 223 make WEB_TARGETS="offline online" web
 224 @end example
 225
 226
 227 @node Building LilyPond
 228 @subsection Building LilyPond
 229
 230 @unnumberedsubsubsec Compiling
 231
 232 To install GNU LilyPond, type
 233
 234 @example
 235 gunzip -c lilypond-x.y.z | tar xf -
 236 cd lilypond-x.y.z
 237 ./configure             # run with --help for applicable options
 238 make
 239 make install
 240 @end example
 241
 242 If you are not root, you should choose a @code{--prefix} argument that
 243 points into your home directory, e.g.
 244
 245 @example
 246 ./configure --prefix=$HOME/usr
 247 @end example
 248
 249
 250 @unnumberedsubsubsec Compiling for multiple platforms
 251
 252 If you want to build multiple versions of LilyPond with different
 253 configuration settings, you can use the @code{--enable-config=CONF}
 254 option of configure.  You should use @code{make conf=CONF} to generate
 255 the output in @file{out-CONF}.  Example: Suppose you want to build
 256 with and without profiling, then use the following for the normal
 257 build
 258
 259 @example
 260 ./configure --prefix=$HOME/usr/ --enable-checking
 261 make
 262 make install
 263 @end example
 264
 265 and for the profiling version, specify a different configuration
 266
 267 @example
 268 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
 269 make conf=prof
 270 make conf=prof install
 271 @end example
 272
 273
 274 @node Building documentation without compiling LilyPond
 275 @subsection Building documentation without compiling LilyPond
 276
 277 The documentation can be built locally without compiling lilypond from
 278 scratch.
 279
 280 From a fresh git checkout, do
 281
 282 @example
 283 ./autogen.sh   % ignore any warning messages
 284 cp GNUmakefile.in GNUmakefile
 285 make -C python
 286 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
 287 % change the lilypond directory as appropriate
 288 @end example
 289
 290 Please note that this may break sometimes -- for example, if a new
 291 feature is added with a test file in input/regression, even the latest
 292 unstable Lily will fail to build the docs.
 293
 294 You may build the manual ( Documentation/user/ ) without building all
 295 the input/* stuff.
 296
 297 @knownissues
 298
 299 You may also need to create a script for @command{pngtopnm} and
 300 @code{pnmtopng}.  On Linux, I use this:
 301
 302 @verbatim
 303 export LD_LIBRARY_PATH=/usr/lib
 304 exec /usr/bin/pngtopnm "$@"
 305 @end verbatim
 306
 307 On OSX, I use this:
 308
 309 @verbatim
 310 export DYLD_LIBRARY_PATH=/sw/lib
 311 exec /sw/bin/pngtopnm "$@"
 312 @end verbatim
 313
 314 In order to force make to build a complete manual (this does not
 315 rebuild all examples, only things which are changed), I recommend
 316 writing a script like this:
 317
 318 @verbatim
 319 ### run from Documentation/user/
 320 #  possibly required on OSX and/or old texinfo
 321 # ulimit -n 4096
 322 if [ -e out-www/lilypond.texi ]; then rm out-www/lilypond.* ; fi;
 323 if [ -e out-www/lilypond-program.texi ]; then rm
 324 out-www/lilypond-program.* ; fi;
 325 if [ -e out-www/lilypond-learning.texi ]; then rm
 326 out-www/lilypond-learning.* ; fi;
 327 nice make LILYPOND_EXTERNAL_BINARY=~/usr/bin/lilypond web
 328 @end verbatim
 329
 330 To rebuild the complete HTML docs, run the above script from the
 331 @file{Documentation/user/} directory, then run the final line (the
 332 @code{nice make}) from the top source dir.
 333
 334
 335
 336 @node Testing LilyPond
 337 @subsection Testing LilyPond
 338
 339 @html
 340 <a name="testing"></a>
 341 @end html
 342
 343 LilyPond comes with an extensive suite that exercises the entire
 344 program.  This suite can be used to automatically check the impact of a
 345 change.  This is done as follows
 346
 347 @example
 348 make test-baseline
 349 @emph{## apply your changes, compile}
 350 make check
 351 @end example
 352
 353 This will leave an HTML page @file{out/test-results/index.html}.  This
 354 page shows all the important differences that your change introduced,
 355 whether in the layout, MIDI, performance or error reporting.
 356
 357 To rerun tests, use
 358
 359 @example
 360 make test-redo           @emph{## redo files differing from baseline}
 361 make test-clean          @emph{## remove all test results}
 362 @end example
 363
 364 @noindent
 365 and then run @code{make check} again.
 366
 367 For tracking memory usage as part of this test, you will need GUILE
 368 CVS; especially the following patch:
 369 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
 370
 371 For checking the coverage of the test suite, do the following
 372
 373 @example
 374 ./buildscripts/build-coverage.sh
 375 @emph{# uncovered files, least covered first}
 376 python ./buildscripts/coverage.py  --summary out-cov/*.cc
 377 @emph{# consecutive uncovered lines, longest first}
 378 python ./buildscripts/coverage.py  --uncovered out-cov/*.cc
 379 @end example
 380
 381
 382 @node Problems
 383 @subsection Problems
 384
 385 For help and questions use @email{lilypond-user@@gnu.org}.  Send bug
 386 reports to @email{bug-lilypond@@gnu.org}.
 387
 388 Bugs that are not fault of LilyPond are documented here.
 389
 390 @unnumberedsubsubsec Bison 1.875
 391
 392 There is a bug in bison-1.875: compilation fails with "parse error
 393 before `goto'" in line 4922 due to a bug in bison.  To fix, please
 394 recompile bison 1.875 with the following fix
 395
 396 @example
 397 $ cd lily; make out/parser.cc
 398 $ vi +4919 out/parser.cc
 399 # append a semicolon to the line containing "__attribute__ ((__unused__))
 400 # save
 401 $ make
 402 @end example
 403
 404
 405 @unnumberedsubsubsec Solaris
 406
 407 Solaris7, ./configure
 408
 409 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
 410 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 411 is.  Run configure like
 412
 413 @example
 414 CONFIG_SHELL=/bin/ksh ksh -c ./configure
 415 @end example
 416
 417 @noindent
 418 or
 419
 420 @example
 421 CONFIG_SHELL=/bin/bash bash -c ./configure
 422 @end example
 423
 424 @unnumberedsubsubsec FreeBSD
 425
 426 To use system fonts, dejaview must be installed.  With the default
 427 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
 428
 429 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
 430 following line just after the @code{<fontconfig>} line.  (Adjust as necessary
 431 for your hierarchy.)
 432
 433 @example
 434 <dir>/usr/X11R6/lib/X11/fonts</dir>
 435 @end example
 436
 437
 438 @unnumberedsubsubsec International fonts
 439
 440 On MacOs X, all fonts are installed by default.  However, finding all
 441 system fonts requires a bit of configuration; see
 442 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
 443 this post} on the @code{lilypond-user} mailing list.
 444
 445 On Linux, international fonts are installed by different means on
 446 every distribution.  We cannot list the exact commands or packages
 447 that are necessary, as each distribution is different, and the exact
 448 package names within each distribution changes.  Here are some
 449 hints, though:
 450
 451 @verbatim
 452 Red Hat Fedora
 453
 454     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
 455          ttfonts-zh_CN fonts-ja fonts-hebrew
 456
 457 Debian GNU/Linux
 458
 459    apt-get install emacs-intl-fonts xfonts-intl-.* \
 460         ttf-kochi-gothic ttf-kochi-mincho \
 461         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 462 @end verbatim
 463