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 MacOS
  51 darwin-ppc
  52 darwin-x86
  53 freebsd-64
  54 freebsd-x86
  55 linux-64
  56 linux-arm
  57 linux-ppc
  58 linux-x86
  59 mingw
  60 @end example
  61
  62
  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 without compiling LilyPond::
  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 @bullet
  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 New Century Schoolbook fonts, as PFB files. These are shipped with
 119 X11 and Ghostscript, and are named @file{c059033l.pfb}
 120 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}
 121
 122 @item @uref{http://www.xs4all.nl/~hanwen/mftrace/,mftrace} (1.1.19 or
 123 newer); you may need to install some additional packages to get mftrace
 124 to work.
 125
 126 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
 127 1.8.2 or newer).  If you are installing binary packages, you may need to
 128 install guile-devel or guile-dev or libguile-dev too.
 129
 130 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.8 or newer).
 131
 132 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 4.x or
 133 newer).
 134
 135 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
 136
 137 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
 138
 139 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
 140
 141 @item @uref{http://www.gnu.org/software/flex/,Flex}
 142
 143 @item @uref{http://www.perl.org/,Perl}
 144
 145 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}
 146
 147 @item All packages required for running, including development packages with
 148 header files and libraries.
 149
 150 @end itemize
 151
 152
 153 @unnumberedsubsubsec Running requirements
 154
 155 Running LilyPond requires proper installation of the following software
 156
 157 @itemize @bullet
 158
 159 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
 160 @item @uref{http://www.freetype.org/,FontConfig} (version 2.2).
 161 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
 162 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
 163 (version 1.8.2 or newer), or patch 1.8.1 with
 164 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
 165 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
 166 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
 167 newer. 8.50 recommended)
 168 @item Dejaview.  (This is normally installed by default)
 169 @end itemize
 170
 171 International fonts are required to create music with international text
 172 or lyrics.
 173
 174
 175 @unnumberedsubsubsec Building documentation
 176
 177 You can view the documentation online at
 178 @uref{http://lilypond.org/doc/}, but you can also build it locally.
 179 This process requires a successful compile of lilypond.  The
 180 documentation is built by issuing
 181
 182 @example
 183 make web
 184 @end example
 185
 186 Building the website requires some additional tools and packages
 187
 188 @itemize @bullet
 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}.
 197 @end itemize
 198
 199 The HTML files can be installed into the standard documentation path
 200 by issuing
 201
 202 @example
 203 make out=www web-install
 204 @end example
 205
 206
 207 @node Building LilyPond
 208 @subsection Building LilyPond
 209
 210 @subsubsection Compiling
 211
 212 To install GNU LilyPond, type
 213
 214 @example
 215 gunzip -c lilypond-x.y.z | tar xf -
 216 cd lilypond-x.y.z
 217 ./configure             # run with --help for applicable options
 218 make
 219 make install
 220 @end example
 221
 222 If you are not root, you should choose a @code{--prefix} argument that
 223 points into your home directory, e.g.
 224
 225 @example
 226 ./configure --prefix=$HOME/usr
 227 @end example
 228
 229
 230 @subsubsection Compiling for multiple platforms
 231
 232 If you want to build multiple versions of LilyPond with different
 233 configuration settings, you can use the @code{--enable-config=CONF}
 234 option of configure.  You should use @samp{make conf=CONF} to generate
 235 the output in @file{out-CONF}.  Example: Suppose you want to build
 236 with and without profiling, then use the following for the normal
 237 build
 238
 239 @example
 240 ./configure --prefix=$HOME/usr/ --enable-checking
 241 make
 242 make install
 243 @end example
 244
 245 and for the profiling version, specify a different configuration
 246
 247 @example
 248 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
 249 make conf=prof
 250 make conf=prof install
 251 @end example
 252
 253
 254 @node Building documentation without compiling LilyPond
 255 @subsection Building documentation without compiling LilyPond
 256
 257 The documentation can be built locally without compiling lilypond from
 258 scratch.
 259
 260 From a fresh git checkout, do
 261
 262 @example
 263 ./autogen.sh   % ignore any warning messages
 264 cp GNUmakefile.in GNUmakefile
 265 make -C python
 266 nice make LILYPOND_EXTERNAL_BINARY=~/Apps/LilyPond.app/Contents/Resources/bin/lilypond web
 267 % change the lilypond directory as appropriate
 268 @end example
 269
 270 Please note that this may break sometimes -- for example, if a new
 271 feature is added with a test file in input/regression, even the latest
 272 unstable Lily will fail to build the docs.
 273
 274 You may build the manual ( Documentation/user/ ) without building all
 275 the input/* stuff.
 276
 277
 278 @node Testing LilyPond
 279 @subsection Testing LilyPond
 280
 281 @html
 282 <a name="testing"></a>
 283 @end html
 284
 285 LilyPond comes with an extensive suite that exercises the entire
 286 program. This suite can be used to automatically check the impact of a
 287 change. This is done as follows
 288
 289 @example
 290 make test-baseline
 291 @emph{## apply your changes, compile}
 292 make check
 293 @end example
 294
 295 This will leave an HTML page @file{out/test-results/index.html}.  This
 296 page shows all the important differences that your change introduced,
 297 whether in the layout, MIDI, performance or error reporting.
 298
 299 To rerun tests, use
 300
 301 @example
 302 make test-redo           @emph{## redo files differing from baseline}
 303 make test-clean          @emph{## remove all test results}
 304 @end example
 305
 306 @noindent
 307 and then run @code{make check} again.
 308
 309 For tracking memory usage as part of this test, you will need GUILE
 310 CVS; especially the following patch:
 311 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
 312
 313 For checking the coverage of the test suite, do the following
 314
 315 @example
 316 ./buildscripts/build-coverage.sh
 317 @emph{# uncovered files, least covered first}
 318 python ./buildscripts/coverage.py  --summary out-cov/*.cc
 319 @emph{# consecutive uncovered lines, longest first}
 320 python ./buildscripts/coverage.py  --uncovered out-cov/*.cc
 321 @end example
 322
 323
 324 @node Problems
 325 @subsection Problems
 326
 327 For help and questions use @email{lilypond-user@@gnu.org}.  Send bug
 328 reports to @email{bug-lilypond@@gnu.org}.
 329
 330 Bugs that are not fault of LilyPond are documented here.
 331
 332 @unnumberedsubsubsec Bison 1.875
 333
 334 There is a bug in bison-1.875: compilation fails with "parse error
 335 before `goto'" in line 4922 due to a bug in bison. To fix, please
 336 recompile bison 1.875 with the following fix
 337
 338 @example
 339 $ cd lily; make out/parser.cc
 340 $ vi +4919 out/parser.cc
 341 # append a semicolon to the line containing "__attribute__ ((__unused__))
 342 # save
 343 $ make
 344 @end example
 345
 346
 347 @unnumberedsubsubsec MacOS X
 348
 349 For Fink, use the following command to compile.
 350
 351 @verbatim
 352 export GUILE=guile-1.6
 353 export GUILE_CONFIG=guile-1.6-config
 354 export PKG_CONFIG_PATH=/sw/lib/freetype219/lib/pkgconfig/:/sw/lib/fontconfig2/lib/pkgconfig/
 355 ./configure
 356 @end verbatim
 357
 358 @unnumberedsubsubsec Solaris
 359
 360 Solaris7, ./configure
 361
 362 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
 363 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 364 is.  Run configure like
 365
 366 @example
 367 CONFIG_SHELL=/bin/ksh ksh -c ./configure
 368 @end example
 369
 370 @noindent
 371 or
 372
 373 @example
 374 CONFIG_SHELL=/bin/bash bash -c ./configure
 375 @end example
 376
 377 @unnumberedsubsubsec FreeBSD
 378
 379 To use system fonts, dejaview must be installed.  With the default
 380 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
 381
 382 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
 383 following line just after the @code{<fontconfig>} line.  (Adjust as necessary
 384 for your hierarchy.)
 385
 386 @example
 387 <dir>/usr/X11R6/lib/X11/fonts</dir>
 388 @end example
 389
 390
 391 @unnumberedsubsubsec International fonts
 392
 393 On MacOs X, all fonts are installed by default.  However, finding all
 394 system fonts requires a bit of configuration; see
 395 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
 396 this post} on the @code{lilypond-user} mailing list.
 397
 398 On Linux, international fonts are installed by different means on
 399 every distribution.  We cannot list the exact commands or packages
 400 that are necessary, as each distribution is different, and the exact
 401 package names within each distribution changes.  Here are some
 402 hints, though:
 403
 404 @verbatim
 405 Red Hat Fedora
 406
 407     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
 408          ttfonts-zh_CN fonts-ja fonts-hebrew
 409
 410 Debian GNU/Linux
 411
 412    apt-get install emacs-intl-fonts xfonts-intl-.* \
 413         ttf-kochi-gothic ttf-kochi-mincho \
 414         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 415 @end verbatim
 416