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