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