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