INSTALL.txt

   1 INSTALL - compiling and installing GNU LilyPond
   2 ***********************************************
   3
   4 Table of Contents
   5 *****************
   6
   7 INSTALL - compiling and installing GNU LilyPond
   8   Precompiled binaries
   9     Downloading
  10   Compiling from source
  11     Downloading source code
  12     Requirements
  13       Compilation
  14       Running requirements
  15       Requirements for building documentation
  16     Building LilyPond
  17       Compiling
  18       Compiling for multiple platforms
  19       Compiling outside the source tree
  20       Useful `make' variables
  21     Building documentation
  22       Commands for building documentation
  23       Building documentation without compiling LilyPond
  24     Testing LilyPond
  25     Problems
  26       Bison 1.875
  27       Solaris
  28       FreeBSD
  29       International fonts
  30
  31
  32 There are two sets of releases for LilyPond: stable releases, and
  33 unstable development releases.  Stable versions have an even-numbered
  34 `minor' version number (i.e. 2.8, 2.10, 2.12, etc).  Development
  35 versions have an odd-numbered `minor' version number (i.e. 2.7, 2.9,
  36 2.11, etc).
  37
  38    Building LilyPond is a very involved process, so we *highly*
  39 recommend using the precompiled binaries.
  40
  41 Precompiled binaries
  42 ====================
  43
  44 Downloading
  45 -----------
  46
  47 Check out `http://lilypond.org/web/install/' for up to date information
  48 on binary packages for your platform.  If your operating system is not
  49 covered on that general page, please see the complete list at
  50 `http://download.linuxaudio.org/lilypond/binaries/'
  51
  52    We currently create binaries for
  53
  54      darwin-ppc  - MacOS X powerpc
  55      darwin-x86  - MacOS X intel
  56      freebsd-64  - FreeBSD 6.x, x86_64
  57      freebsd-x86 - FreeBSD 4.x, x86
  58      linux-64    - Any GNU/Linux distribution, x86_64
  59      linux-ppc   - Any GNU/Linux distribution, powerpc
  60      linux-x86   - Any GNU/Linux distribution, x86
  61      mingw       - Windows x86
  62
  63
  64 Known issues and warnings
  65 .........................
  66
  67 If you have MacOS 10.3 or 10.4 and you would like to use Python scripts
  68 such as `convert-ly' and `lilypond-book', see *note Setup for MacOS X:
  69 (lilypond-program)Setup for MacOS X.
  70
  71 Compiling from source
  72 =====================
  73
  74 Downloading source code
  75 -----------------------
  76
  77 Download source
  78
  79    * tarballs from `http://lilypond.org/download/' by HTTP.
  80
  81    * tarballs from `http://download.linuxaudio.org/lilypond/' by HTTP.
  82
  83    * GIT from git.sv.gnu.org
  84      (http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary)
  85
  86           git clone git://git.sv.gnu.org/lilypond.git
  87
  88      The repository does not contain generated files.  To create
  89      `configure', run
  90           ./autogen.sh
  91
  92    For information on packaging, see `http://lilypond.org/devel'.
  93
  94 Requirements
  95 ------------
  96
  97 Compilation
  98 ...........
  99
 100 In addition to the packages needed for running LilyPond (see below), you
 101 need the following extra packages for building.
 102
 103    When installing a binary package FOO, you may need to install the
 104 FOO-devel, libFOO-dev or FOO-dev package too.
 105
 106    * FontForge (http://fontforge.sf.net/) 20060125 or newer.
 107
 108    * MetaFont (http://metafont.tutorial.free.fr/) (mf-nowin, mf, mfw or
 109      mfont binaries) and MetaPost
 110      (http://cm.bell-labs.com/who/hobby/MetaPost.html) (mpost binary),
 111      usually packaged with a LaTeX distribution like tetex or texlive.
 112
 113    * t1utils (http://www.lcdf.org/~eddietwo/type/#t1utils) (version
 114      1.33 or newer recommended).
 115
 116    * New Century Schoolbook fonts, as PFB files.  These are shipped with
 117      X11 and Ghostscript, and are named `c059033l.pfb' `c059036l.pfb',
 118      `c059013l.pfb' and `c059016l.pfb'.
 119
 120    * GUILE (http://www.gnu.org/software/guile/guile.html) (version
 121      1.8.2 or newer).  If you are installing binary packages, you may
 122      need to install guile-devel or guile-dev or libguile-dev too.
 123
 124    * Texinfo (ftp://ftp.gnu.org/gnu/texinfo/) (version 4.11 or newer).
 125
 126    * The GNU c++ compiler (http://gcc.gnu.org/) (version 3.4 or newer.
 127      4.x is strongly recommended).
 128
 129    * Python (http://www.python.org) (version 2.4 or newer)
 130
 131    * GNU Make (ftp://ftp.gnu.org/gnu/make/) (version 3.78 or newer).
 132
 133    * gettext (http://www.gnu.org/software/gettext/gettext.html)
 134      (version 0.17 or newer).
 135
 136    * Flex (http://www.gnu.org/software/flex/).
 137
 138    * Perl (http://www.perl.org/).
 139
 140    * GNU Bison (http://www.gnu.org/software/bison/).
 141
 142    * All packages required for running, including development packages
 143      with header files and libraries.
 144
 145
 146 Running requirements
 147 ....................
 148
 149 Running LilyPond requires proper installation of the following software
 150
 151    * Freetype (http://www.freetype.org/) (version 2.1.10 or newer).
 152
 153    * FontConfig (http://fontconfig.org/) (version 2.2 or newer).
 154
 155    * Pango (http://www.pango.org/) (version 1.12 or newer).
 156
 157    * GUILE (http://www.gnu.org/software/guile/guile.html) (version
 158      1.8.2 or newer), or patch 1.8.1 with
 159      `http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch'.
 160
 161    * Python (http://www.python.org) (version 2.4 or newer).
 162
 163    * Ghostscript (http://www.ghostscript.com) (version 8.15 or newer.
 164      8.60 recommended)
 165
 166    * Dejaview.  (This is normally installed by default)
 167
 168    International fonts are required to create music with international
 169 text or lyrics.
 170
 171 Requirements for building documentation
 172 .......................................
 173
 174 You can view the documentation online at `http://lilypond.org/doc/',
 175 but you can also build it locally.  This process requires a successful
 176 compile of LilyPond, and some additional tools and packages:
 177
 178    * The netpbm utilities (http://netpbm.sourceforge.net/)
 179
 180    * ImageMagick
 181
 182    * International fonts (see input/regression/utf-8.ly for hints about
 183      which font packages are necessary for your platform)
 184
 185    * Ghostscript 8.60 or newer, or 8.50 with the patch from
 186      `http://bugs.ghostscript.com/show_bug.cgi?id=688154' and the patch
 187      from `http://bugs.ghostscript.com/show_bug.cgi?id=688017'.
 188
 189    * Texi2HTML (http://www.nongnu.org/texi2html/) 1.80 or newer
 190
 191    * rsync
 192
 193 Building LilyPond
 194 -----------------
 195
 196 Compiling
 197 .........
 198
 199 To install GNU LilyPond, type
 200
 201      gunzip -c lilypond-x.y.z | tar xf -
 202      cd lilypond-x.y.z
 203      ./configure                # run with --help for applicable options
 204      make
 205      su -c 'make install'
 206
 207 If you are not root, you should choose a `--prefix' argument that
 208 points into your home directory, e.g.
 209
 210      ./configure --prefix=$HOME/usr
 211
 212 Compiling for multiple platforms
 213 ................................
 214
 215 If you want to build multiple versions of LilyPond with different
 216 configuration settings, you can use the `--enable-config=CONF' option
 217 of `configure'.  You should use `make conf=CONF' to generate the output
 218 in `out-CONF'.  For example, suppose you want to build with and without
 219 profiling, then use the following for the normal build
 220
 221      ./configure --prefix=$HOME/usr/ --enable-checking
 222      make
 223      make install
 224
 225    and for the profiling version, specify a different configuration
 226
 227      ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
 228      make conf=prof
 229      make conf=prof install
 230
 231 Compiling outside the source tree
 232 .................................
 233
 234 It is possible to compile LilyPond in a build tree different from the
 235 source tree, with `--srcdir' option of `configure':
 236
 237      mkdir lily-build && cd lily-build
 238      SOURCEDIR/configure --srcdir=SOURCEDIR
 239
 240 Useful `make' variables
 241 .......................
 242
 243 If a less verbose build output if desired, the variable `QUIET_BUILD'
 244 may be set to `1' on `make' command line, or in `local.make' at top of
 245 the build tree.
 246
 247 Building documentation
 248 ----------------------
 249
 250 This requires a successful compile of LilyPond, or using an external
 251 LilyPond binary.
 252
 253 Commands for building documentation
 254 ...................................
 255
 256 The documentation is built by issuing
 257
 258      make doc
 259
 260    After compilation, the HTML documentation tree is available in
 261 `out-www/offline-root/', and can be browsed locally.
 262
 263    The HTML, PDF and if available Info files can be installed into the
 264 standard documentation path by issuing
 265
 266      make install-doc
 267
 268 This also installs Info documentation with images if the installation
 269 prefix is properly set; otherwise, instructions to complete proper
 270 installation of Info documentation are printed on standard output.
 271
 272    Compilation of documentation in Info format with images can be done
 273 separately by issuing
 274
 275      make info
 276
 277 Separate installation of this documentation is done by issuing
 278
 279      make install-info
 280
 281 Note that to get the images in Info documentation, `install-doc' target
 282 creates symbolic links to HTML and PDF installed documentation tree in
 283 `PREFIX/share/info', in order to save disk space, whereas
 284 `install-info' copies images in `PREFIX/share/info' subdirectories.
 285
 286    It is possible to build a documentation tree in
 287 `out-www/online-root/', with special processing, so it can be used on a
 288 website with content negotiation for automatic language selection; this
 289 can be achieved by issuing
 290
 291      make WEB_TARGETS=online doc
 292
 293 and both `offline' and `online' targets can be generated by issuing
 294
 295      make WEB_TARGETS="offline online" doc
 296
 297    Several targets are available to clean the documentation build and
 298 help with maintaining documentation; an overview of these targets is
 299 available with
 300
 301      make help
 302
 303 from every directory in the build tree.  Most targets for documentation
 304 maintenance are available from `Documentation/'; for more information,
 305 see the Contributors' Guide, section _Documentation work_.
 306
 307    The makefile variable `QUIET_BUILD' may be set to `1' for a less
 308 verbose build output, just like for building the programs.
 309
 310
 311
 312 Known issues and warnings
 313 .........................
 314
 315 The most time consuming task for building the documentation is running
 316 LilyPond to build images of music, and there cannot be several
 317 simultaneously running `lilypond-book' instances, so `-j' `make' option
 318 does not significantly speed up the build process.  To help speed it
 319 up, the makefile variable CPU_COUNT may be set in `local.make' or on
 320 the command line to the number of `.ly' files that LilyPond should
 321 process simultaneously, e.g. on a bi-processor or dual core machine
 322
 323      make -j3 CPU_COUNT=3 doc
 324
 325 The recommended value of CPU_COUNT is one plus the number of cores or
 326 processors, but it is advisable to set it to a smaller value if your
 327 system has not enough RAM to run that many simultaneous LilyPond
 328 instances.
 329
 330    If source files have changed since last documentation build, output
 331 files that need to be rebuilt are normally rebuilt, even if you do not
 332 run `make doc-clean' first.  However, building dependencies in the
 333 documentation are so complex that rebuilding of some targets may not be
 334 triggered as they should be; a workaround is to force rebuilding by
 335 touching appropriate files, e.g.
 336
 337      touch Documentation/user/*.itely
 338      touch input/lsr/*.ly
 339
 340 Building documentation without compiling LilyPond
 341 .................................................
 342
 343 The documentation can be built locally without compiling LilyPond
 344 binary, if LilyPond is already installed on your system.
 345
 346    From a fresh Git checkout, do
 347
 348      ./autogen.sh   # ignore any warning messages
 349      cp GNUmakefile.in GNUmakefile
 350      make -C python
 351      nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
 352
 353    Please note that this may break sometimes - for example, if a new
 354 feature is added with a test file in input/regression, even the latest
 355 development release of LilyPond will fail to build the docs.
 356
 357    You may build the manual without building all the `input/*' stuff:
 358 change directory, for example to `Documentation/user', issue `make
 359 doc', which will build documentation in a subdirectory `out-www' from
 360 the source files in current directory.  In this case, if you also want
 361 to browse the documentation in its post-processed form, change back to
 362 top directory and issue
 363
 364      make out=www WWW-post
 365
 366
 367 Known issues and warnings
 368 .........................
 369
 370 You may also need to create a script for `pngtopnm' and `pnmtopng'.  On
 371 GNU/Linux, I use this:
 372
 373 export LD_LIBRARY_PATH=/usr/lib
 374 exec /usr/bin/pngtopnm "$@"
 375
 376    On MacOS X, I use this:
 377
 378 export DYLD_LIBRARY_PATH=/sw/lib
 379 exec /sw/bin/pngtopnm "$@"
 380
 381 Testing LilyPond
 382 ----------------
 383
 384 LilyPond comes with an extensive suite that exercises the entire
 385 program.  This suite can be used to automatically check the impact of a
 386 change.  This is done as follows
 387
 388      make test-baseline
 389      _## apply your changes, compile_
 390      make check
 391
 392    This will leave an HTML page `out/test-results/index.html'.  This
 393 page shows all the important differences that your change introduced,
 394 whether in the layout, MIDI, performance or error reporting.
 395
 396    To rerun tests, use
 397
 398      make test-redo           _## redo files differing from baseline_
 399      make test-clean          _## remove all test results_
 400
 401 and then run `make check' again.
 402
 403    For tracking memory usage as part of this test, you will need GUILE
 404 CVS; especially the following patch:
 405 `http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch'.
 406
 407    For checking the coverage of the test suite, do the following
 408
 409      ./scripts/auxiliar/build-coverage.sh
 410      _# uncovered files, least covered first_
 411      ./scripts/auxiliar/coverage.py  --summary out-cov/*.cc
 412      _# consecutive uncovered lines, longest first_
 413      ./scripts/auxiliar/coverage.py  --uncovered out-cov/*.cc
 414
 415 Problems
 416 --------
 417
 418 For help and questions use <lilypond-user@gnu.org>.  Send bug reports
 419 to <bug-lilypond@gnu.org>.
 420
 421    Bugs that are not fault of LilyPond are documented here.
 422
 423 Bison 1.875
 424 ...........
 425
 426 There is a bug in bison-1.875: compilation fails with "parse error
 427 before `goto'" in line 4922 due to a bug in bison.  To fix, please
 428 recompile bison 1.875 with the following fix
 429
 430      $ cd lily; make out/parser.cc
 431      $ vi +4919 out/parser.cc
 432      # append a semicolon to the line containing "__attribute__ ((__unused__))
 433      # save
 434      $ make
 435
 436 Solaris
 437 .......
 438
 439 Solaris7, ./configure
 440
 441    `./configure' needs a POSIX compliant shell.  On Solaris7, `/bin/sh'
 442 is not yet POSIX compliant, but `/bin/ksh' or bash is.  Run configure
 443 like
 444
 445      CONFIG_SHELL=/bin/ksh ksh -c ./configure
 446
 447 or
 448
 449      CONFIG_SHELL=/bin/bash bash -c ./configure
 450
 451 FreeBSD
 452 .......
 453
 454 To use system fonts, dejaview must be installed.  With the default
 455 port, the fonts are installed in `usr/X11R6/lib/X11/fonts/dejavu'.
 456
 457    Open the file `$LILYPONDBASE/usr/etc/fonts/local.conf' and add the
 458 following line just after the `<fontconfig>' line.  (Adjust as necessary
 459 for your hierarchy.)
 460
 461      <dir>/usr/X11R6/lib/X11/fonts</dir>
 462
 463 International fonts
 464 ...................
 465
 466 On MacOS X, all fonts are installed by default.  However, finding all
 467 system fonts requires a bit of configuration; see this post
 468 (http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html)
 469 on the `lilypond-user' mailing list.
 470
 471    On Linux, international fonts are installed by different means on
 472 every distribution.  We cannot list the exact commands or packages that
 473 are necessary, as each distribution is different, and the exact package
 474 names within each distribution changes.  Here are some hints, though:
 475
 476 Red Hat Fedora
 477
 478     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
 479          ttfonts-zh_CN fonts-ja fonts-hebrew
 480
 481 Debian GNU/Linux
 482
 483    apt-get install emacs-intl-fonts xfonts-intl-.* \
 484         ttf-kochi-gothic ttf-kochi-mincho \
 485         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 486