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