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