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