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     Linux-2.4.0, Guile-1.4 -with-threads
  31     NetBSD
  32     Solaris:
  33     AIX
  34
  35
  36 INSTALL - compiling and installing GNU LilyPond
  37 ***********************************************
  38
  39    This document describes how to build LilyPond on Unix platforms.  It
  40 is also known to run and compile on Windows NT/95/98 as well.  More
  41 information on this topic can be found at the LilyPond on Windows page
  42 (http://www.lilypond.org/gnu-windows/).
  43
  44 Downloading
  45 ===========
  46
  47    Even numbered versions are `stable'. The webpages for the stable
  48 version (1.2) reside on the GNU servers
  49 (http://www.gnu.org/software/lilypond). Big enhancements go into the
  50 latest odd numbered version (1.3), whose webpages are on the lilypond
  51 site (http://www.lilypond.org/).
  52
  53 Source code
  54 -----------
  55
  56    If you want to compile LilyPond from source, download here:
  57    * Download development releases from
  58      `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/' by FTP and
  59      `http://ftp.cs.uu.nl/pub/GNU/LilyPond/', by HTTP.
  60
  61    * `ftp://sca.uwaterloo.ca/pub/' by FTP (Canadian mirror)
  62
  63    * at `lilypond.org' `ftp://ftp.lilypond.org/pub/LilyPond/' by FTP and
  64      `http://www.lilypond.org/ftp/' by HTTP.
  65
  66    Of course, if your platform supports LilyPond, such as Debian
  67 GNU/Linux, FreeBSD, OpenBSD or NetBSD, you're encouraged to use the
  68 native build from source drill.
  69
  70    For Red Hat Linux and SuSE Linux, `.spec' files are included in the
  71 tarball; see instructions below.
  72
  73 Precompiled binaries
  74 --------------------
  75
  76    If you want to track bleeding edge development, try:
  77
  78    * Debian GNU/Linux
  79      (ftp://ftp.debian.org/debian/pool/main/l/lilypond/) usually has
  80      the latest binaries for the most useful stable and development
  81      versions, while
  82
  83    * Mandrake Cooker
  84      (http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/) also
  85      provides fairly recent versions.
  86
  87    Binaries are made available for other popular platforms, but as we
  88 need to compile them ourselves, they are not updated for every version
  89 released.
  90
  91    * Red Hat i386
  92      (ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/)
  93
  94    * SuSE (ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE)
  95
  96    * LinuxPPC (ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/)
  97
  98    * Windows (http://www.lilypond.org/gnu-windows/)
  99
 100 Upgrading
 101 ---------
 102
 103    There are two options for upgrading sources.
 104
 105    * if you have an unpacked source tree of a previous version, you may
 106      the patches.
 107
 108      _If you upgrade by patching do remember to rerun autoconf after
 109      applying the patch_.
 110
 111    * if you have the `.tar.gz' file of a previous release, you can use
 112      xdelta (ftp://ftp.xcf.berkeley.edu/pub/xdelta/).   This is much
 113      safer than using patches, and is the recommended way.
 114
 115      The following command produces `lilypond-1.4.3.tar.gz' from
 116      `lilypond-1.4.2.tar.gz' identical (up to compression dates) to the
 117      .3 on the FTP site.
 118             xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
 119
 120 Requirements
 121 ============
 122
 123 Compilation
 124 -----------
 125
 126    You need the following packages to compile Lilypond.
 127
 128    * A reasonably new C++ compiler:  EGCS 1.1, GCC 2.95.2 or newer.
 129      Check out the gcc site (ftp://ftp.gnu.org/gnu/gcc/).
 130
 131    * Python 1.5, Check out the python website (http://www.python.org).
 132
 133    * GUILE 1.3.4 or newer,  check out the GUILE webpage
 134      (http://www.gnu.org/software/guile/guile.html).  Version 1.4 is
 135      recommended for better performance.
 136
 137    * GNU Make.  Check out the GNU make FTP directory
 138      (ftp://ftp.gnu.org/gnu/make/).
 139
 140    * Flex (version 2.5.4a or newer).  Check out the Flex webpage
 141      (http://www.gnu.org/software/flex/).
 142
 143    * Bison (version 1.25 or newer).  Check out the bison webpage
 144      (http://www.gnu.org/software/bison/)
 145
 146    * TeX.
 147
 148      TeX is used as an output backend.
 149
 150      Also, TeX's libkpathsea is used to find the fonts (`.mf', `.afm',
 151      `.tfm').  Make sure you have tetex 1.0 or newer (1.0.6 is known to
 152      work).  You may need to install a tetex-devel or tetex-dev package
 153      too.
 154
 155    * Texinfo (version 4.0 or newer).  The documentation of lily is
 156      written in texinfo.  Check out the texinfo FTP directory
 157      (ftp://ftp.gnu.org/gnu/texinfo/).
 158
 159    * The geometry package for LaTeX is needed to use ly2dvi.  It is
 160      available at the FTP directory for `geometry'
 161      (ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry).
 162      This package is normally included with the TeX distribution.
 163
 164    * kpathsea, a library for searching (TeX) files.  `kpathsea' is
 165      usually included with your installation of TeX.  You may need to
 166      install a tetex-devel or tetex-dev package too.
 167
 168      In the very unlikely case that kpathsea is not available for your
 169      platform (ie, you're not running GNU/Linux, Windows, or any recent
 170      UNIX), you can compile LilyPond without kpathsea support.  In that
 171      case, you'll probably have to indicate where TeX's tfm files live.
 172      Invoke configure something like:
 173
 174           ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
 175
 176    * pktrace, [OPTIONAL], needed for generating PostScript Type1 fonts.
 177      Get it from  `http://www.cs.uu.nl/~hanwen/pktrace/'
 178
 179    * autotrace-0.27a, [OPTIONAL], needed for generating PostScript Type1
 180      fonts. `http://autotrace.sourceforge.net'.
 181
 182    * MetaPost [OPTIONAL] needed for generating PostScript Type3 fonts.
 183      Please note that tetex-0.4pl8 (included with Red Hat 5.x) does not
 184      include `mfplain.mp', which is needed for producing the scalable
 185      font files.
 186
 187      If you don't have MetaPost and don't want to use PostScript
 188      output, then edit `mf/GNUmakefile', removing the line saying
 189      `PFA_FILES='.
 190
 191
 192 Running requirements
 193 --------------------
 194
 195    GNU LilyPond does use a lot of resources. For operation you need the
 196 following software
 197
 198    * TeX.
 199
 200    * Xdvi and Ghostscript
 201
 202    * GUILE 1.3.4, or newer.  Check out the GUILE webpage
 203      (http://www.gnu.org/software/guile.html)
 204
 205    For running LilyPond successfully you have to help TeX and MetaFont
 206 find various files.  The recommended way of doing so is adjusting the
 207 environment variables in the start-up scripts of your shell. Appropriate
 208 Csh and bourne sh scripts are left in
 209 `buildscripts/out/lilypond-profile' and
 210 `buildscripts/out/lilypond-login' after compilation.
 211
 212    LilyPond is a big and slow program.  A fast CPU and plenty of RAM is
 213 recommended for comfortable use.
 214
 215 Website requirements
 216 --------------------
 217
 218    The documentation comes in the form of a website. You can view this
 219 website on the internet, but you can also build it locally. This process
 220 requires a successful compile of lilypond. The website is built by
 221 issuing
 222
 223        make web-doc
 224
 225    Building the website requires some additional tools:
 226
 227    * xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
 228      The original is at the netpbm FTP site
 229      (ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz)
 230
 231    * pnmtopng. The original is at in the pnmtopng FTP site
 232      (ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz).
 233
 234    * Bibtex2html (http://www.lri.fr/~filliatr/ftp/bibtex2html/), or
 235      Bib2html (http://www.uni-koblenz.de/ag-ki/ftp/bib2html/).
 236      Bibtex2html is available in debian, while bib2html is in some rpm
 237      based distributions.  Bib2html, in turn depends on man2html for
 238      proper installation.  man2html can be had from
 239      http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05
 240      (http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05).
 241
 242      The website will build without bib converter utility, but you will
 243      not see our hypertextified bibliography.
 244
 245    * texinfo (a development release) The documentation will build with
 246      texinfo-4.0, but if you want split html pages, you're best off
 247      using the lates pretest version from texinfo-4.0b
 248      (ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz) or
 249      texinfo-4.0b (ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz)
 250
 251 Building  LilyPond
 252 ==================
 253
 254    to install GNU LilyPond, type:
 255         gunzip -c lilypond-x.y.z | tar xf -
 256         cd lilypond-x.y.z
 257         ./configure             # run with --help to see appropriate options
 258         make
 259         make install
 260              sh buildscripts/clean-fonts.sh
 261
 262    If you are doing an upgrade, you should remove all `feta' `.pk' and
 263 `.tfm' files.  A script has been provided to do the work for you, see
 264 `buildscripts/clean-fonts.sh'.
 265
 266    If you are not root, you should choose a `--prefix' argument that
 267 points into your home directory, eg.
 268
 269         ./configure --prefix=$HOME/usr
 270
 271    In this case, you have to insert the contents of
 272 `buildscripts/out/lilypond-login' or
 273 `buildscripts/out/lilypond-profile' into your start up scripts by hand.
 274
 275 Configuring for multiple platforms
 276 ----------------------------------
 277
 278    If you want to build multiple versions of LilyPond with different
 279 configuration settings, you can use the `--enable-config=CONF' option
 280 of configure.  You should use `make conf=CONF' to generate the output
 281 in `out-CONF'.  Example: suppose I want to build with and without
 282 profiling.  Then I'd use the following for the normal build,
 283
 284            ./configure --prefix=~ --enable-checking
 285            make
 286            make install
 287
 288    and for the profiling version, I specify a different configuration.
 289
 290
 291            ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
 292            make conf=prof
 293            make conf=prof install
 294
 295 Emacs mode
 296 ==========
 297
 298    An Emacs mode for entering music and running LilyPond is included
 299 with the source archive as `lilypond-mode.el' and
 300 `lilypond-font-lock.el'.  You should install these files somewhere in
 301 your LOAD-PATH.  If you have installed a precompiled LilyPond package,
 302 these files can be found in `/usr/share/doc/lilypond-x.y.z/'.
 303
 304    Add this to your `~/.emacs' or `~/.emacs.el', or install this file
 305 in Emacs' `site-start.d':
 306          ;;; lilypond-init.el --- Startup code for LilyPond mode
 307
 308          (load-library "lilypond-mode.el")
 309          (setq auto-mode-alist
 310            (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
 311          (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
 312
 313    If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode
 314 is automatically loaded, you not even need to modify your `~/.emacs'
 315 file.
 316
 317 Compiling for distributions
 318 ===========================
 319
 320 Red Hat Linux
 321 -------------
 322
 323    Red Hat 7.0 i386 RPMS are available from
 324 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
 325
 326    You can also compile them yourself.  A spec file is in
 327 `make/out/lilypond.redhat.spec'. This file is distributed along with
 328 the sources.  You can make the rpm by issuing
 329
 330              tar xfz lilypond-x.y.z.tar.gz
 331         rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
 332         rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
 333
 334    For running on a Red Hat system you need these packages: guile,
 335 tetex, tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
 336
 337    For compilation on a Red Hat system you need these packages, in
 338 addition to the those needed for running: glibc-devel, gcc-c++,
 339 libstdc++-devel, guile-devel, flex, bison, texinfo, tetex-devel, groff,
 340 libgr-progs.
 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 binutils cpp gcc libc6-dev \
 491                 g++ libstdc++2.10-dev \
 492                 python-base libguile-dev tetex-bin libkpathsea-dev \
 493                 tetex-extra flex bison texinfo bibtex2html groff gs \
 494                 netpbm m4 gettext
 495
 496    And, just so that old fonts from previous versions of LilyPond won't
 497 interfere with your build, you may want to do this before the build too:
 498
 499         dpkg --purge lilypond lilypond1.3
 500
 501 Problems
 502 ========
 503
 504    For help and questions use <lilypond-user@gnu.org>.  Please consult
 505 the FAQ before mailing your problems.  If you find bugs, please send
 506 bug reports to <bug-lilypond@gnu.org>.
 507
 508    Bugs that are not fault of LilyPond are documented here.
 509
 510 FLex-2.5.4a and gcc-3.0
 511 -----------------------
 512
 513    Flex 2.5.4a does not produce g++-3.0 compliant C++ code.  To compile
 514 LilyPond with gcc-3.0 you may do:
 515
 516              CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
 517              make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
 518              patch -p1 < lexer-gcc-3.0.patch
 519              make conf=gcc-3.0 -C lily
 520
 521    Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
 522
 523 Linux-2.4.0, Guile-1.4 -with-threads
 524 ------------------------------------
 525
 526    There's a bug in certain kernels around version 2.4.0, that is
 527 triggered when using Guile 1.4 compiled with pthreads.  You'll see
 528 random segmentation fault crashes of LilyPond.  Upgrade to a newer
 529 version of Linux.  If you can't do that, you may try to recompiling
 530 Guile without threads (YMMV):
 531
 532               guile-1.4$ ./configure --without-threads; make all install
 533
 534 NetBSD
 535 ------
 536
 537    * The flex precompiled in NetBSD-1.4.2 is broken.  Download
 538      flex-2.5.4a, build, install.
 539
 540    * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 541      release)) does not include `/usr/pkg' paths.  Configure using:
 542
 543           CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 544
 545
 546 Solaris:
 547 --------
 548
 549    * Sparc64/Solaris 2.6, GNU make-3.77
 550
 551      GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
 552      newer.
 553
 554    * Sparc64/Solaris 2.6, ld
 555
 556      Not yet resolved.
 557
 558 AIX
 559 ---
 560
 561    * AIX 4.3 ld
 562
 563      The following is from the gcc install/SPECIFIC file.
 564              Some versions of the AIX binder (linker) can fail with a
 565           relocation    overflow severe error when the -bbigtoc option
 566           is used to link    GCC-produced object files into an
 567           executable that overflows the TOC.     A fix for APAR IX75823
 568           (OVERFLOW DURING LINK WHEN USING GCC AND    -BBIGTOC) is
 569           available from IBM Customer Support and from its
 570           27service.boulder.ibm.com website as PTF U455193.
 571
 572           Binutils does not support AIX 4.3 (at least through release
 573           2.9). GNU    as and GNU ld will not work properly and one
 574           should not configure GCC    to use those GNU utilities. Use
 575           the native AIX tools which do    interoperate with GCC.
 576
 577      add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 578               LDFLAGS='-Wl,-bbigtoc' ./configure
 579
 580