INSTALL.txt

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