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 LinuxPPC
 336 --------
 337
 338    Some LinuxPPC RPMS should available from
 339 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
 340
 341    A LinuxPPC RPM can be made using the `lilypond.redhat.spec' file.
 342
 343 SuSE
 344 ----
 345
 346    Some SUSE RPMS should available from
 347 `ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE'.
 348
 349    You can also compile a RPM for SUSE yourself.  A spec file is in
 350 `make/out/lilypond.suse.spec', see the instructions for building the
 351 Red Hat RPM.
 352
 353    You must have the following packages: guile tcsh tetex te_latex
 354 te_kpath te_mpost libpng python gpp libgpp gettext autoconf netpbm
 355 libnetpb gs_serv gs_lib gs_fonts guile
 356
 357 Slackware
 358 ---------
 359
 360    No precompiled packages for Slackware are available.
 361
 362    Problems have been reported with Slackware 7.0; apparently, it ships
 363 with a faulty compiler. Do not compile LilyPond with -O2 on this
 364 platform.
 365
 366 Mandrake
 367 --------
 368
 369    Some binaries are available at rpmfind.net. Refer to
 370 `http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/'.
 371
 372    You can also compile a RPM for Mandrake yourself.  A spec file is in
 373 `make/out/lilypond.mandrake.spec', see the instructions for building
 374 the Red Hat RPM.
 375
 376 Debian GNU/Linux
 377 ----------------
 378
 379    A Debian package is also available.  You may install it easily by
 380 running `apt-get' as root:
 381
 382         apt-get install lilypond lilypond-doc
 383
 384    You can also compile the .deb for Debian yourself, do:
 385
 386         apt-get -b source lilypond
 387
 388    If you're real impatient, you may even do:
 389
 390         cd lilypond-x.y.z   # a previous version
 391              uscan               # download and build latest directly from upstream
 392
 393    Debian's TeX installation is a bit short on memory, you may want to
 394 increase it like this:
 395      --- /etc/texmf/texmf.cnf.dpkg      Sun Jan 28 14:12:14 2001
 396      +++ /etc/texmf/texmf.cnf   Fri Apr 27 11:09:35 2001
 397      @ -384,8 +384,8 @
 398       main_memory.context = 1500000
 399       main_memory.mpost = 1000000
 400       main_memory = 263000 % words of inimemory available; also applies to inimf&mp
 401      -extra_mem_top = 0    % extra high memory for chars, tokens, etc.
 402      -extra_mem_bot = 0    % extra low memory for boxes, glue, breakpoints, etc.
 403      +extra_mem_top = 100000    % extra high memory for chars, tokens, etc.
 404      +extra_mem_bot = 100000    % extra low memory for boxes, glue, breakpoints, etc.
 405
 406       obj_tab_size.context = 256000
 407
 408    You could also export `extra_mem_top' and `extra_mem_bot' as
 409 environment variables if you do not want to or cannot modify
 410 `/etc/texmf/texmf.cnf'.
 411
 412    Alternatively, visit
 413
 414    * http://packages.debian.org/lilypond
 415      (http://packages.debian.org/lilypond)
 416
 417    * http://people.debian.org/~foka/lilypond/
 418      (http://people.debian.org/~foka/lilypond/) for latest
 419      semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato)
 420      users.  The official stable Debian 2.2 is stuck with the old
 421      LilyPond-1.3.24.  Since LilyPond-1.4 has been released, the older
 422      lilypond1.3 Debian package is now obsolete.
 423
 424    Please contact Anthony Fok <lilypond@packages.debian.org> for more
 425 information.
 426
 427    The build scripts are in the subdirectory `debian/'; you can make
 428 the .deb by doing, for example:
 429
 430         $ su - root
 431         # dpkg --purge lilypond lilypond1.3
 432         # exit
 433         $ tar xzf lilypond-1.4.3.tar.gz
 434         $ cd lilypond-1.4.3
 435         $ dch -p -v 1.4.3-0.local.1 "Local build."
 436         $ debuild -B
 437         $ su - root
 438         # dpkg -i ../lilypond_1.4.3*.deb
 439         # exit
 440         $
 441
 442    Use command `debuild' instead of `debuild -B' if you have a very
 443 fast machine and want to build the HTML, PS and DVI documentation too.
 444
 445    For compilation on a Debian GNU/Linux system you need these packages,
 446 in addition to the those needed for running:
 447
 448    * g++, cpp, libc6-dev, libstdc++<YOUR-LIBSTDC++-VERSION-HERE>-dev
 449
 450    * libguile<YOUR-LIBGUILE-VERSION-HERE>-dev
 451
 452    * make, m4, flex, bison
 453
 454    * gettext
 455
 456    * groff, texinfo
 457
 458    * bibtex2html (not in Debian 2.2)
 459
 460    * tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
 461
 462    * dpkg-dev, debhelper, fakeroot
 463
 464    * gs, netpbm
 465
 466    * pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
 467       in Debian testing/unstable.)
 468
 469    Most of these are listed on the `Build-Depends' line in the
 470 `debian/control' file.  To ensure the creation of the lilypond deb is
 471 trouble-free, we recommend that you first install the following packages
 472 by running \`apt-get' as root before building the package:
 473
 474    For Debian 2.2:
 475
 476         apt-get install task-debian-devel task-c++-dev \
 477                 python-base libguile6-dev tetex-bin tetex-dev \
 478                 tetex-extra flex bison texinfo groff gs \
 479                 netpbm pnmtopng m4 gettext
 480
 481    For Debian in development ("unstable", the future 2.3 or 3.0):
 482
 483         apt-get install task-debian-devel task-c++-dev \
 484                 python-base libguile9-dev tetex-bin libkpathsea-dev \
 485                 tetex-extra flex bison texinfo bibtex2html groff gs \
 486                 netpbm m4 gettext
 487
 488    And, just so that old fonts from previous versions of LilyPond won't
 489 interfere with your build, you may want to do this before the build too:
 490
 491         dpkg --purge lilypond lilypond1.3
 492
 493 Problems
 494 ========
 495
 496    For help and questions use <lilypond-user@gnu.org>.  Please consult
 497 the FAQ before mailing your problems.  If you find bugs, please send
 498 bug reports to <bug-lilypond@gnu.org>.
 499
 500    Bugs that are not fault of LilyPond are documented here.
 501
 502 FLex-2.5.4a and gcc-3.0
 503 -----------------------
 504
 505    Flex 2.5.4a does not produce g++-3.0 compliant C++ code.  To compile
 506 LilyPond with gcc-3.0 you may do:
 507
 508              CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
 509              make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
 510              patch -p1 < lexer-gcc-3.0.patch
 511              make conf=gcc-3.0 -C lily
 512
 513    Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
 514
 515 NetBSD
 516 ------
 517
 518    * The flex precompiled in NetBSD-1.4.2 is broken.  Download
 519      flex-2.5.4a, build, install.
 520
 521    * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 522      release)) does not include `/usr/pkg' paths.  Configure using:
 523
 524           CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 525
 526
 527 Solaris:
 528 --------
 529
 530    * Sparc64/Solaris 2.6, GNU make-3.77
 531
 532      GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
 533      newer.
 534
 535    * Sparc64/Solaris 2.6, ld
 536
 537      Not yet resolved.
 538
 539 AIX
 540 ---
 541
 542    * AIX 4.3 ld
 543
 544      The following is from the gcc install/SPECIFIC file.
 545              Some versions of the AIX binder (linker) can fail with a
 546           relocation    overflow severe error when the -bbigtoc option
 547           is used to link    GCC-produced object files into an
 548           executable that overflows the TOC.     A fix for APAR IX75823
 549           (OVERFLOW DURING LINK WHEN USING GCC AND    -BBIGTOC) is
 550           available from IBM Customer Support and from its
 551           27service.boulder.ibm.com website as PTF U455193.
 552
 553           Binutils does not support AIX 4.3 (at least through release
 554           2.9). GNU    as and GNU ld will not work properly and one
 555           should not configure GCC    to use those GNU utilities. Use
 556           the native AIX tools which do    interoperate with GCC.
 557
 558      add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 559               LDFLAGS='-Wl,-bbigtoc' ./configure
 560
 561