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