INSTALL.txt

   1
   2
   3 Table of Contents
   4 *****************
   5
   6
   7
   8
   9 INSTALL - compiling and installing GNU LilyPond
  10   Downloading
  11     Source code
  12     Precompiled binaries
  13     Upgrading
  14   Requirements
  15     Compilation
  16     Running requirements
  17     Website requirements
  18   Building  LilyPond
  19     Configuring for multiple platforms
  20   Emacs mode
  21   Compiling for distributions
  22     Red Hat Linux
  23     LinuxPPC
  24     SuSE
  25     Slackware
  26     Mandrake
  27     Debian GNU/Linux
  28   Problems
  29     FLex-2.5.4a and gcc-3.0
  30     Python-2.1[.1]
  31     Linux-2.4.0, Guile-1.4 -with-threads
  32     NetBSD
  33     Solaris:
  34     AIX
  35
  36
  37 INSTALL - compiling and installing GNU LilyPond
  38 ***********************************************
  39
  40    This document describes how to build LilyPond on Unix platforms.  It
  41 is also known to run and compile on Windows NT/95/98 as well.  More
  42 information on this topic can be found at the LilyPond on Windows page
  43 (http://www.lilypond.org/gnu-windows/).
  44
  45 Downloading
  46 ===========
  47
  48    Even numbered versions are `stable'. The webpages for the stable
  49 version (1.2) reside on the GNU servers
  50 (http://www.gnu.org/software/lilypond). Big enhancements go into the
  51 latest odd numbered version (1.3), whose webpages are on the lilypond
  52 site (http://www.lilypond.org/).
  53
  54 Source code
  55 -----------
  56
  57    If you want to compile LilyPond from source, download here:
  58    * Download development releases from
  59      `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/' by FTP and
  60      `http://ftp.cs.uu.nl/pub/GNU/LilyPond/', by HTTP.
  61
  62    * `ftp://sca.uwaterloo.ca/pub/' by FTP (Canadian mirror)
  63
  64    * at `lilypond.org' `ftp://ftp.lilypond.org/pub/LilyPond/' by FTP and
  65      `http://www.lilypond.org/ftp/' by HTTP.
  66
  67    Of course, if your platform supports LilyPond, such as Debian
  68 GNU/Linux, FreeBSD, OpenBSD or NetBSD, you're encouraged to use the
  69 native build from source drill.
  70
  71    For Red Hat Linux and SuSE Linux, `.spec' files are included in the
  72 tarball; see instructions below.
  73
  74 Precompiled binaries
  75 --------------------
  76
  77    If you want to track bleeding edge development, try:
  78
  79    * Debian GNU/Linux
  80      (ftp://ftp.debian.org/debian/pool/main/l/lilypond/) usually has
  81      the latest binaries for the most useful stable and development
  82      versions, while
  83
  84    * Mandrake Cooker
  85      (http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/) also
  86      provides fairly recent versions.
  87
  88    Binaries are made available for other popular platforms, but as we
  89 need to compile them ourselves, they are not updated for every version
  90 released.
  91
  92    * Red Hat i386
  93      (ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/)
  94
  95    * SuSE (ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE)
  96
  97    * LinuxPPC (ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/)
  98
  99    * Windows (http://www.lilypond.org/gnu-windows/)
 100
 101 Upgrading
 102 ---------
 103
 104    There are two options for upgrading sources.
 105
 106    * if you have an unpacked source tree of a previous version, you may
 107      the patches.
 108
 109      _If you upgrade by patching do remember to rerun autoconf after
 110      applying the patch_.
 111
 112    * if you have the `.tar.gz' file of a previous release, you can use
 113      xdelta (ftp://ftp.xcf.berkeley.edu/pub/xdelta/).   This is much
 114      safer than using patches, and is the recommended way.
 115
 116      The following command produces `lilypond-1.4.3.tar.gz' from
 117      `lilypond-1.4.2.tar.gz' identical (up to compression dates) to the
 118      .3 on the FTP site.
 119             xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
 120
 121 Requirements
 122 ============
 123
 124 Compilation
 125 -----------
 126
 127    You need the following packages to compile Lilypond.
 128
 129    * A reasonably new C++ compiler:  EGCS 1.1, GCC 2.95.2 or newer.
 130      Check out the gcc site (ftp://ftp.gnu.org/gnu/gcc/).
 131
 132    * Python (version 1.5 or newer; not 2.1.x) Check out the python
 133      website (http://www.python.org).
 134
 135    * GUILE 1.4 or newer,  check out the GUILE webpage
 136      (http://www.gnu.org/software/guile/guile.html).  Version 1.4 is
 137      recommended for better performance.
 138
 139    * GNU Make.  Check out the GNU make FTP directory
 140      (ftp://ftp.gnu.org/gnu/make/).
 141
 142    * Flex (version 2.5.4a or newer).  Check out the Flex webpage
 143      (http://www.gnu.org/software/flex/).
 144
 145    * Bison (version 1.25 or newer).  Check out the bison webpage
 146      (http://www.gnu.org/software/bison/)
 147
 148    * TeX.
 149
 150      TeX is used as an output backend.
 151
 152      Also, TeX's libkpathsea is used to find the fonts (`.mf', `.afm',
 153      `.tfm').  Make sure you have tetex 1.0 or newer (1.0.6 is known to
 154      work).  You may need to install a tetex-devel or tetex-dev package
 155      too.
 156
 157    * Texinfo (version 4.0 or newer).  The documentation of lily is
 158      written in texinfo.  Check out the texinfo FTP directory
 159      (ftp://ftp.gnu.org/gnu/texinfo/).
 160
 161    * The geometry package for LaTeX is needed to use ly2dvi.  It is
 162      available at the FTP directory for `geometry'
 163      (ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry).
 164      This package is normally included with the TeX distribution.
 165
 166    * kpathsea, a library for searching (TeX) files.  `kpathsea' is
 167      usually included with your installation of TeX.  You may need to
 168      install a tetex-devel or tetex-dev package too.
 169
 170      In the very unlikely case that kpathsea is not available for your
 171      platform (ie, you're not running GNU/Linux, Windows, or any recent
 172      UNIX), you can compile LilyPond without kpathsea support.  In that
 173      case, you'll probably have to indicate where TeX's tfm files live.
 174      Invoke configure something like:
 175
 176           ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
 177
 178    * pktrace, [OPTIONAL], needed for generating PostScript Type1 fonts.
 179      Get it from  `http://www.cs.uu.nl/~hanwen/pktrace/'
 180
 181    * autotrace-0.27a, [OPTIONAL], needed for generating PostScript Type1
 182      fonts. `http://autotrace.sourceforge.net'.
 183
 184    * MetaPost [OPTIONAL] needed for generating PostScript Type3 fonts.
 185      Please note that tetex-0.4pl8 (included with Red Hat 5.x) does not
 186      include `mfplain.mp', which is needed for producing the scalable
 187      font files.
 188
 189      If you don't have MetaPost and don't want to use PostScript
 190      output, then edit `mf/GNUmakefile', removing the line saying
 191      `PFA_FILES='.
 192
 193
 194 Running requirements
 195 --------------------
 196
 197    GNU LilyPond does use a lot of resources. For operation you need the
 198 following software
 199
 200    * TeX.
 201
 202    * Xdvi and Ghostscript
 203
 204    * GUILE 1.3.4, or newer.  Check out the GUILE webpage
 205      (http://www.gnu.org/software/guile.html)
 206
 207    For running LilyPond successfully you have to help TeX and MetaFont
 208 find various files.  The recommended way of doing so is adjusting the
 209 environment variables in the start-up scripts of your shell. Appropriate
 210 Csh and bourne sh scripts are left in
 211 `buildscripts/out/lilypond-profile' and
 212 `buildscripts/out/lilypond-login' after compilation.
 213
 214    LilyPond is a big and slow program.  A fast CPU and plenty of RAM is
 215 recommended for comfortable use.
 216
 217 Website requirements
 218 --------------------
 219
 220    The documentation comes in the form of a website. You can view this
 221 website on the internet, but you can also build it locally. This process
 222 requires a successful compile of lilypond. The website is built by
 223 issuing
 224
 225        make web-doc
 226
 227    Building the website requires some additional tools:
 228
 229    * xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
 230      The original is at the netpbm FTP site
 231      (ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz)
 232
 233    * pnmtopng. The original is at in the pnmtopng FTP site
 234      (ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz).
 235
 236    * texinfo (a development release) The documentation will build with
 237      texinfo-4.0, but if you want split html pages, you're best off
 238      using the lates pretest version from texinfo-4.0b
 239      (ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz) or
 240      texinfo-4.0b (ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz)
 241
 242 Building  LilyPond
 243 ==================
 244
 245    to install GNU LilyPond, type:
 246         gunzip -c lilypond-x.y.z | tar xf -
 247         cd lilypond-x.y.z
 248         ./configure             # run with --help to see appropriate options
 249         make
 250         make install
 251              sh buildscripts/clean-fonts.sh
 252
 253    If you are doing an upgrade, you should remove all `feta' `.pk' and
 254 `.tfm' files.  A script has been provided to do the work for you, see
 255 `buildscripts/clean-fonts.sh'.
 256
 257    If you are not root, you should choose a `--prefix' argument that
 258 points into your home directory, eg.
 259
 260         ./configure --prefix=$HOME/usr
 261
 262    In this case, you have to insert the contents of
 263 `buildscripts/out/lilypond-login' or
 264 `buildscripts/out/lilypond-profile' into your start up scripts by hand.
 265
 266 Configuring for multiple platforms
 267 ----------------------------------
 268
 269    If you want to build multiple versions of LilyPond with different
 270 configuration settings, you can use the `--enable-config=CONF' option
 271 of configure.  You should use `make conf=CONF' to generate the output
 272 in `out-CONF'.  Example: suppose I want to build with and without
 273 profiling.  Then I'd use the following for the normal build,
 274
 275            ./configure --prefix=~ --enable-checking
 276            make
 277            make install
 278
 279    and for the profiling version, I specify a different configuration.
 280
 281
 282            ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
 283            make conf=prof
 284            make conf=prof install
 285
 286 Emacs mode
 287 ==========
 288
 289    An Emacs mode for entering music and running LilyPond is included
 290 with the source archive as `lilypond-mode.el' and
 291 `lilypond-font-lock.el'.  You should install these files somewhere in
 292 your LOAD-PATH.  If you have installed a precompiled LilyPond package,
 293 these files can be found in `/usr/share/doc/lilypond-x.y.z/'.
 294
 295    Add this to your `~/.emacs' or `~/.emacs.el', or install this file
 296 in Emacs' `site-start.d':
 297          ;;; lilypond-init.el --- Startup code for LilyPond mode
 298
 299          (load-library "lilypond-mode.el")
 300          (setq auto-mode-alist
 301            (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
 302          (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
 303
 304    If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode
 305 is automatically loaded, you not even need to modify your `~/.emacs'
 306 file.
 307
 308 Compiling for distributions
 309 ===========================
 310
 311 Red Hat Linux
 312 -------------
 313
 314    Red Hat 7.0 i386 RPMS are available from
 315 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
 316
 317    You can also compile them yourself.  A spec file is in
 318 `make/out/lilypond.redhat.spec'. This file is distributed along with
 319 the sources.  You can make the rpm by issuing
 320
 321              tar xfz lilypond-x.y.z.tar.gz
 322         rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
 323         rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
 324
 325    For running on a Red Hat system you need these packages: guile,
 326 tetex, tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
 327
 328    For compilation on a Red Hat system you need these packages, in
 329 addition to the those needed for running: glibc-devel, gcc-c++,
 330 libstdc++-devel, guile-devel, flex, bison, texinfo, tetex-devel, groff,
 331 libgr-progs.
 332
 333 LinuxPPC
 334 --------
 335
 336    Some LinuxPPC RPMS should available from
 337 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
 338
 339    A LinuxPPC RPM can be made using the `lilypond.redhat.spec' file.
 340
 341 SuSE
 342 ----
 343
 344    Some SUSE RPMS should available from
 345 `ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE'.
 346
 347    You can also compile a RPM for SUSE yourself.  A spec file is in
 348 `make/out/lilypond.suse.spec', see the instructions for building the
 349 Red Hat RPM.
 350
 351    You must have the following packages: guile tcsh tetex te_latex
 352 te_kpath te_mpost libpng python gpp libgpp gettext autoconf netpbm
 353 libnetpb gs_serv gs_lib gs_fonts guile
 354
 355 Slackware
 356 ---------
 357
 358    No precompiled packages for Slackware are available.
 359
 360    Problems have been reported with Slackware 7.0; apparently, it ships
 361 with a faulty compiler. Do not compile LilyPond with -O2 on this
 362 platform.
 363
 364 Mandrake
 365 --------
 366
 367    Some binaries are available at rpmfind.net. Refer to
 368 `http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/'.
 369
 370    You can also compile a RPM for Mandrake yourself.  A spec file is in
 371 `make/out/lilypond.mandrake.spec', see the instructions for building
 372 the Red Hat RPM.
 373
 374 Debian GNU/Linux
 375 ----------------
 376
 377    A Debian package is also available.  You may install it easily by
 378 running `apt-get' as root:
 379
 380         apt-get install lilypond lilypond-doc
 381
 382    You can also compile the .deb for Debian yourself, do:
 383
 384         apt-get -b source lilypond
 385
 386    If you're real impatient, you may even do:
 387
 388         cd lilypond-x.y.z   # a previous version
 389              uscan               # download and build latest directly from upstream
 390
 391    Debian's TeX installation is a bit short on memory, you may want to
 392 increase it like this:
 393      --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
 394      +++ texmf.cnf      Sun Dec 16 23:46:34 2001
 395      @ -411,8 +411,8 @
 396       main_memory.context = 1500000
 397       main_memory.mpost = 1000000
 398       main_memory = 263000 % words of inimemory available; also applies to inimf&mp
 399      -extra_mem_top = 0    % extra high memory for chars, tokens, etc.
 400      -extra_mem_bot = 0    % extra low memory for boxes, glue, breakpoints, etc.
 401      +extra_mem_top = 1000000    % extra high memory for chars, tokens, etc.
 402      +extra_mem_bot = 1000000    % extra low memory for boxes, glue, breakpoints, etc.
 403
 404       obj_tab_size.context = 300000
 405
 406      @ -430,7 +430,7 @
 407       % Max number of characters in all strings, including all error messages,
 408       % help texts, font names, control sequences.  These values apply to TeX and MP.
 409       pool_size.context = 750000
 410      -pool_size = 125000
 411      +pool_size = 250000
 412       % Minimum pool space after TeX/MP's own strings; must be at least
 413       % 25000 less than pool_size, but doesn't need to be nearly that large.
 414       string_vacancies.context = 45000
 415
 416    You could also export `extra_mem_top' and `extra_mem_bot' as
 417 environment variables if you do not want to or cannot modify
 418 `/etc/texmf/texmf.cnf'.
 419
 420    Alternatively, visit
 421
 422    * http://packages.debian.org/lilypond
 423      (http://packages.debian.org/lilypond)
 424
 425    * http://people.debian.org/~foka/lilypond/
 426      (http://people.debian.org/~foka/lilypond/) for latest
 427      semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato)
 428      users.  The official stable Debian 2.2 is stuck with the old
 429      LilyPond-1.3.24.  Since LilyPond-1.4 has been released, the older
 430      lilypond1.3 Debian package is now obsolete.
 431
 432    Please contact Anthony Fok <lilypond@packages.debian.org> for more
 433 information.
 434
 435    The build scripts are in the subdirectory `debian/'; you can make
 436 the .deb by doing, for example:
 437
 438         $ su - root
 439         # dpkg --purge lilypond lilypond1.3
 440         # exit
 441         $ tar xzf lilypond-1.4.3.tar.gz
 442         $ cd lilypond-1.4.3
 443         $ dch -p -v 1.4.3-0.local.1 "Local build."
 444         $ debuild -B
 445         $ su - root
 446         # dpkg -i ../lilypond_1.4.3*.deb
 447         # exit
 448         $
 449
 450    Use command `debuild' instead of `debuild -B' if you have a very
 451 fast machine and want to build the HTML, PS and DVI documentation too.
 452
 453    For compilation on a Debian GNU/Linux system you need these packages,
 454 in addition to the those needed for running:
 455
 456    * g++, cpp, libc6-dev, libstdc++<YOUR-LIBSTDC++-VERSION-HERE>-dev
 457
 458    * libguile<YOUR-LIBGUILE-VERSION-HERE>-dev
 459
 460    * make, m4, flex, bison
 461
 462    * gettext
 463
 464    * groff, texinfo
 465
 466    * tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
 467
 468    * dpkg-dev, debhelper, fakeroot
 469
 470    * gs, netpbm
 471
 472    * pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
 473       in Debian testing/unstable.)
 474
 475    Most of these are listed on the `Build-Depends' line in the
 476 `debian/control' file.  To ensure the creation of the lilypond deb is
 477 trouble-free, we recommend that you first install the following packages
 478 by running \`apt-get' as root before building the package:
 479
 480    For Debian 2.2:
 481
 482         apt-get install task-debian-devel task-c++-dev \
 483                 python-base libguile6-dev tetex-bin tetex-dev \
 484                 tetex-extra flex bison texinfo groff gs \
 485                 netpbm pnmtopng m4 gettext
 486
 487    For Debian in development ("unstable", the future 2.3 or 3.0):
 488
 489         apt-get install binutils cpp gcc libc6-dev \
 490                 g++ libstdc++2.10-dev \
 491                 python-base libguile-dev tetex-bin libkpathsea-dev \
 492                 tetex-extra flex bison texinfo  groff gs \
 493                 netpbm m4 gettext
 494
 495    And, just so that old fonts from previous versions of LilyPond won't
 496 interfere with your build, you may want to do this before the build too:
 497
 498         dpkg --purge lilypond lilypond1.3
 499
 500 Problems
 501 ========
 502
 503    For help and questions use <lilypond-user@gnu.org>.  Please consult
 504 the FAQ before mailing your problems.  If you find bugs, please send
 505 bug reports to <bug-lilypond@gnu.org>.
 506
 507    Bugs that are not fault of LilyPond are documented here.
 508
 509 FLex-2.5.4a and gcc-3.0
 510 -----------------------
 511
 512    Flex 2.5.4a does not produce g++-3.0 compliant C++ code.  To compile
 513 LilyPond with gcc-3.0 you may do:
 514
 515              CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
 516              make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
 517              patch -p1 < lexer-gcc-3.0.patch
 518              make conf=gcc-3.0 -C lily
 519
 520    Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
 521
 522 Python-2.1[.1]
 523 --------------
 524
 525    Regular expressions are broken in Python 2.1.[.1], either upgrade or
 526 downgrade python.
 527
 528 Linux-2.4.0, Guile-1.4 -with-threads
 529 ------------------------------------
 530
 531    There's a bug in certain kernels around version 2.4.0, that is
 532 triggered when using Guile 1.4 compiled with pthreads.  You'll see
 533 random segmentation fault crashes of LilyPond.  Upgrade to a newer
 534 version of Linux.  If you can't do that, you may try to recompiling
 535 Guile without threads (YMMV):
 536
 537               guile-1.4$ ./configure --without-threads; make all install
 538
 539 NetBSD
 540 ------
 541
 542    * The flex precompiled in NetBSD-1.4.2 is broken.  Download
 543      flex-2.5.4a, build, install.
 544
 545    * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 546      release)) does not include `/usr/pkg' paths.  Configure using:
 547
 548           CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 549
 550
 551 Solaris:
 552 --------
 553
 554    * Sparc64/Solaris 2.6, GNU make-3.77
 555
 556      GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
 557      newer.
 558
 559    * Sparc64/Solaris 2.6, ld
 560
 561      Not yet resolved.
 562
 563 AIX
 564 ---
 565
 566    * AIX 4.3 ld
 567
 568      The following is from the gcc install/SPECIFIC file.
 569              Some versions of the AIX binder (linker) can fail with a
 570           relocation    overflow severe error when the -bbigtoc option
 571           is used to link    GCC-produced object files into an
 572           executable that overflows the TOC.     A fix for APAR IX75823
 573           (OVERFLOW DURING LINK WHEN USING GCC AND    -BBIGTOC) is
 574           available from IBM Customer Support and from its
 575           27service.boulder.ibm.com website as PTF U455193.
 576
 577           Binutils does not support AIX 4.3 (at least through release
 578           2.9). GNU    as and GNU ld will not work properly and one
 579           should not configure GCC    to use those GNU utilities. Use
 580           the native AIX tools which do    interoperate with GCC.
 581
 582      add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 583               LDFLAGS='-Wl,-bbigtoc' ./configure
 584
 585