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