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