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