INSTALL.txt

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