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