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     FLex-2.5.4a and gcc-3.0
  30     NetBSD
  31     Solaris:
  32     AIX
  33
  34
  35 INSTALL - compiling and installing GNU LilyPond
  36 ***********************************************
  37
  38    This document describes how to build LilyPond on Unix platforms.  It
  39 is also known to run and compile on Windows NT/95/98 as well.  More
  40 information on this topic can be found at the LilyPond on Windows page
  41 (http://www.lilypond.org/gnu-windows/).
  42
  43 Downloading
  44 ===========
  45
  46    Even numbered versions are `stable'. The webpages for the stable
  47 version (1.2) reside on the GNU servers
  48 (http://www.gnu.org/software/lilypond). Big enhancements go into the
  49 latest odd numbered version (1.3), whose webpages are on the lilypond
  50 site (http://www.lilypond.org/).
  51
  52 source code
  53 -----------
  54
  55    If you want to compile LilyPond from source, download here:
  56    * Download development releases from
  57      `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/' by FTP and
  58      `http://ftp.cs.uu.nl/pub/GNU/LilyPond/', by HTTP.
  59
  60    * `ftp://sca.uwaterloo.ca/pub/' by FTP (Canadian mirror)
  61
  62    * at `lilypond.org' `ftp://ftp.lilypond.org/pub/LilyPond/' by FTP and
  63      `http://www.lilypond.org/ftp/' by HTTP.
  64
  65 Binaries
  66 --------
  67
  68    Binaries are available, but are not updated for every version
  69 released.
  70    * Red Hat i386
  71      (ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/)
  72
  73    * LinuxPPC (ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/)
  74
  75    * Debian GNU/Linux
  76      (ftp://ftp.debian.org/debian/pool/main/l/lilypond/)
  77
  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.3.tar.gz' from
  97      `lilypond-1.4.2.tar.gz' identical (up to compression dates) to the
  98      .3 on the FTP site.
  99             xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.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 entering music and running LilyPond is included
 274 with the source archive as `lilypond-mode.el' and
 275 `lilypond-font-lock.el'.  You should install these files somewhere in
 276 your LOAD-PATH.  If you have installed a precompiled LilyPond package,
 277 these files can be found in `/usr/share/doc/lilypond-x.y.z/'.
 278
 279    Add this to your `~/.emacs' or `~/.emacs.el', or install this file
 280 in Emacs' `site-start.d':
 281          ;;; lilypond-init.el --- Startup code for LilyPond mode
 282
 283          (load-library "lilypond-mode.el")
 284          (setq auto-mode-alist
 285            (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
 286          (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
 287
 288    If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode
 289 is automatically loaded, you not even need to modify your `~/.emacs'
 290 file.
 291
 292 Compiling for distributions
 293 ===========================
 294
 295 Red Hat Linux
 296 -------------
 297
 298    Red Hat 7.0 i386 RPMS are available from
 299 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
 300
 301    You can also compile them yourself.  A spec file is in
 302 `make/out/lilypond.redhat.spec'. This file is distributed along with
 303 the sources.  You can make the rpm by issuing
 304
 305              tar xfz lilypond-x.y.z.tar.gz
 306         rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
 307         rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
 308
 309    For running on a Red Hat system you need these packages: guile,
 310 tetex, tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
 311
 312    For compilation on a Red Hat system you need these packages, in
 313 addition to the those needed for running: glibc-devel, gcc-c++,
 314 libstdc++-devel, guile-devel, flex, bison, texinfo, tetex-devel, groff,
 315 libgr-progs.
 316
 317    Warning
 318
 319    There appears to be a problem with the Xdvi shipped with Red Hat 7.1.
 320 Symptoms: Xdvi responds very sluggishly or hangs while viewing lilypond
 321 output. The cause for this problem is unknown; you are advised to
 322 recompile Xdvi from source.
 323
 324 LinuxPPC
 325 --------
 326
 327    Some LinuxPPC RPMS should available from
 328 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
 329
 330    A LinuxPPC RPM can be made using the `lilypond.redhat.spec' file.
 331
 332 SuSE
 333 ----
 334
 335    Some SUSE RPMS should available from
 336 `ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE'.
 337
 338    You can also compile a RPM for SUSE yourself.  A spec file is in
 339 `make/out/lilypond.suse.spec', see the instructions for building the
 340 Red Hat RPM.
 341
 342    You must have the following packages: guile tcsh tetex te_latex
 343 te_kpath te_mpost libpng python gpp libgpp gettext autoconf netpbm
 344 libnetpb gs_serv gs_lib gs_fonts guile
 345
 346 Slackware
 347 ---------
 348
 349    No precompiled packages for Slackware are available.
 350
 351    Problems have been reported with Slackware 7.0; apparently, it ships
 352 with a faulty compiler. Do not compile LilyPond with -O2 on this
 353 platform.
 354
 355 Mandrake
 356 --------
 357
 358    Some binaries are available at rpmfind.net. Refer to
 359 `ftp://ftp.rpmfind.net/linux/Mandrake-devel/cooker/contrib/RPMS/'.
 360
 361 Debian GNU/Linux
 362 ----------------
 363
 364    A Debian package is also available.  You may install it easily by
 365 running `apt-get' as root:
 366
 367         apt-get install lilypond lilypond-doc
 368
 369    Debian's TeX installation is a bit short on memory, you may want to
 370 increase it like this:
 371      --- /etc/texmf/texmf.cnf.dpkg      Sun Jan 28 14:12:14 2001
 372      +++ /etc/texmf/texmf.cnf   Fri Apr 27 11:09:35 2001
 373      @ -384,8 +384,8 @
 374       main_memory.context = 1500000
 375       main_memory.mpost = 1000000
 376       main_memory = 263000 % words of inimemory available; also applies to inimf&mp
 377      -extra_mem_top = 0    % extra high memory for chars, tokens, etc.
 378      -extra_mem_bot = 0    % extra low memory for boxes, glue, breakpoints, etc.
 379      +extra_mem_top = 100000    % extra high memory for chars, tokens, etc.
 380      +extra_mem_bot = 100000    % extra low memory for boxes, glue, breakpoints, etc.
 381
 382       obj_tab_size.context = 256000
 383
 384    You could also export `extra_mem_top' and `extra_mem_bot' as
 385 environment variables if you do not want to or cannot modify
 386 `/etc/texmf/texmf.cnf'.
 387
 388    Alternatively, visit
 389
 390    * http://packages.debian.org/lilypond
 391      (http://packages.debian.org/lilypond)
 392
 393    * http://people.debian.org/~foka/lilypond/
 394      (http://people.debian.org/~foka/lilypond/) for latest
 395      semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato)
 396      users.  The official stable Debian 2.2 is stuck with the old
 397      LilyPond-1.3.24.  Since LilyPond-1.4 has been released, the older
 398      lilypond1.3 Debian package is now obsolete.
 399
 400    Please contact Anthony Fok <lilypond@packages.debian.org> for more
 401 information.
 402
 403    The build scripts are in the subdirectory `debian/'; you can make
 404 the .deb by doing, for example:
 405
 406         $ su - root
 407         # dpkg --purge lilypond lilypond1.3
 408         # exit
 409         $ tar xzf lilypond-1.4.3.tar.gz
 410         $ cd lilypond-1.4.3
 411         $ dch -p -v 1.4.3-0.local.1 "Local build."
 412         $ debuild -B
 413         $ su - root
 414         # dpkg -i ../lilypond_1.4.3*.deb
 415         # exit
 416         $
 417
 418    Use command `debuild' instead of `debuild -B' if you have a very
 419 fast machine and want to build the HTML, PS and DVI documentation too.
 420
 421    For compilation on a Debian GNU/Linux system you need these packages,
 422 in addition to the those needed for running:
 423
 424    * g++, cpp, libc6-dev, libstdc++<YOUR-LIBSTDC++-VERSION-HERE>-dev
 425
 426    * libguile<YOUR-LIBGUILE-VERSION-HERE>-dev
 427
 428    * make, m4, flex, bison
 429
 430    * gettext
 431
 432    * groff, texinfo
 433
 434    * bibtex2html (not in Debian 2.2)
 435
 436    * tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
 437
 438    * dpkg-dev, debhelper, fakeroot
 439
 440    * gs, netpbm
 441
 442    * pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
 443       in Debian testing/unstable.)
 444
 445    Most of these are listed on the `Build-Depends' line in the
 446 `debian/control' file.  To ensure the creation of the lilypond deb is
 447 trouble-free, we recommend that you first install the following packages
 448 by running \`apt-get' as root before building the package:
 449
 450    For Debian 2.2:
 451
 452         apt-get install task-debian-devel task-c++-dev \
 453                 python-base libguile6-dev tetex-bin tetex-dev \
 454                 tetex-extra flex bison texinfo groff gs \
 455                 netpbm pnmtopng m4 gettext
 456
 457    For Debian in development ("unstable", the future 2.3 or 3.0):
 458
 459         apt-get install task-debian-devel task-c++-dev \
 460                 python-base libguile9-dev tetex-bin libkpathsea-dev \
 461                 tetex-extra flex bison texinfo bibtex2html groff gs \
 462                 netpbm m4 gettext
 463
 464    And, just so that old fonts from previous versions of LilyPond won't
 465 interfere with your build, you may want to do this before the build too:
 466
 467         dpkg --purge lilypond lilypond1.3
 468
 469 Problems
 470 ========
 471
 472    For help and questions use <lilypond-user@gnu.org>.  Please consult
 473 the FAQ before mailing your problems.  If you find bugs, please send
 474 bug reports to <bug-lilypond@gnu.org>.
 475
 476    Bugs that are not fault of LilyPond are documented here.
 477
 478 FLex-2.5.4a and gcc-3.0
 479 -----------------------
 480
 481    Flex 2.5.4a does not produce g++-3.0 compliant C++ code.  To compile
 482 LilyPond with gcc-3.0 you may do:
 483
 484              CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
 485              make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
 486              patch -p1 < lexer-gcc-3.0.patch
 487              make conf=gcc-3.0 -C lily
 488
 489    Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
 490
 491 NetBSD
 492 ------
 493
 494    * The flex precompiled in NetBSD-1.4.2 is broken.  Download
 495      flex-2.5.4a, build, install.
 496
 497    * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 498      release)) does not include `/usr/pkg' paths.  Configure using:
 499
 500           CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 501
 502
 503 Solaris:
 504 --------
 505
 506    * Sparc64/Solaris 2.6, GNU make-3.77
 507
 508      GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
 509      newer.
 510
 511    * Sparc64/Solaris 2.6, ld
 512
 513      Not yet resolved.
 514
 515 AIX
 516 ---
 517
 518    * AIX 4.3 ld
 519
 520      The following is from the gcc install/SPECIFIC file.
 521              Some versions of the AIX binder (linker) can fail with a
 522           relocation    overflow severe error when the -bbigtoc option
 523           is used to link    GCC-produced object files into an
 524           executable that overflows the TOC.     A fix for APAR IX75823
 525           (OVERFLOW DURING LINK WHEN USING GCC AND    -BBIGTOC) is
 526           available from IBM Customer Support and from its
 527           27service.boulder.ibm.com website as PTF U455193.
 528
 529           Binutils does not support AIX 4.3 (at least through release
 530           2.9). GNU    as and GNU ld will not work properly and one
 531           should not configure GCC    to use those GNU utilities. Use
 532           the native AIX tools which do    interoperate with GCC.
 533
 534      add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 535               LDFLAGS='-Wl,-bbigtoc' ./configure
 536
 537