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