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