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     MacOS X
  29   Problems
  30     FLex-2.5.4a and gcc-3.0
  31     Linux-2.4.0, Guile-1.4 -with-threads
  32     NetBSD
  33     Solaris:
  34     AIX
  35
  36
  37 INSTALL - compiling and installing GNU LilyPond
  38 ***********************************************
  39
  40    This document describes how to build LilyPond on Unix platforms.  It
  41 is also known to run and compile on Windows NT/95/98 as well.  More
  42 information on this topic can be found at the LilyPond on Windows page
  43 (http://www.lilypond.org/gnu-windows/).
  44
  45 Downloading
  46 ===========
  47
  48    Even numbered versions are `stable'. The webpages for the stable
  49 version (1.2) reside on the GNU servers
  50 (http://www.gnu.org/software/lilypond). Big enhancements go into the
  51 latest odd numbered version (1.3), whose webpages are on the lilypond
  52 site (http://www.lilypond.org/).
  53
  54 Source code
  55 -----------
  56
  57    If you want to compile LilyPond from source, download here:
  58    * Download development releases from
  59      `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/' by FTP and
  60      `http://ftp.cs.uu.nl/pub/GNU/LilyPond/', by HTTP.
  61
  62    * `ftp://sca.uwaterloo.ca/pub/' by FTP (Canadian mirror)
  63
  64    * at `lilypond.org' `ftp://ftp.lilypond.org/pub/LilyPond/' by FTP and
  65      `http://www.lilypond.org/ftp/' by HTTP.
  66
  67    Of course, if your platform supports LilyPond, such as Debian
  68 GNU/Linux, FreeBSD, OpenBSD or NetBSD, you're encouraged to use the
  69 native build from source drill.
  70
  71    For Red Hat Linux and SuSE Linux, `.spec' files are included in the
  72 tarball; see instructions below.
  73
  74 Precompiled binaries
  75 --------------------
  76
  77    If you want to track bleeding edge development, try:
  78
  79    * Debian GNU/Linux
  80      (ftp://ftp.debian.org/debian/pool/main/l/lilypond/) usually has
  81      the latest binaries for the most useful stable and development
  82      versions, while
  83
  84    * Mandrake Cooker
  85      (http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/) also
  86      provides fairly recent versions.
  87
  88    Binaries are made available for other popular platforms, but as we
  89 need to compile them ourselves, they are not updated for every version
  90 released.
  91
  92    * Red Hat i386
  93      (ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/)
  94
  95    * SuSE (ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE)
  96
  97    * LinuxPPC (ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/)
  98
  99    * Windows (http://www.lilypond.org/gnu-windows/)
 100
 101 Upgrading
 102 ---------
 103
 104    There are two options for upgrading sources.
 105
 106    * if you have an unpacked source tree of a previous version, you may
 107      the patches.
 108
 109      _If you upgrade by patching do remember to rerun autoconf after
 110      applying the patch_.
 111
 112    * if you have the `.tar.gz' file of a previous release, you can use
 113      xdelta (ftp://ftp.xcf.berkeley.edu/pub/xdelta/).   This is much
 114      safer than using patches, and is the recommended way.
 115
 116      The following command produces `lilypond-1.4.3.tar.gz' from
 117      `lilypond-1.4.2.tar.gz' identical (up to compression dates) to the
 118      .3 on the FTP site.
 119             xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
 120
 121 Requirements
 122 ============
 123
 124 Compilation
 125 -----------
 126
 127    You need the following packages to compile Lilypond.
 128
 129    * A reasonably new version of the GNU C++ compiler:  EGCS 1.1, GCC
 130      2.95.2 or newer. Check out the gcc site
 131      (ftp://ftp.gnu.org/gnu/gcc/).
 132
 133    * Python (version 1.5 or newer).  Check out the python website
 134      (http://www.python.org).
 135
 136    * GUILE (version 1.4 or newer).  Check out the GUILE webpage
 137      (http://www.gnu.org/software/guile/guile.html).  Version 1.4 is
 138      recommended for better performance.
 139
 140    * GNU Make.  Check out the GNU make FTP directory
 141      (ftp://ftp.gnu.org/gnu/make/).
 142
 143    * Flex (version 2.5.4a or newer).  Check out the Flex webpage
 144      (http://www.gnu.org/software/flex/).
 145
 146    * Bison (version 1.25 or newer).  Check out the bison webpage
 147      (http://www.gnu.org/software/bison/)
 148
 149    * TeX.
 150
 151      TeX is used as an output backend.
 152
 153      Also, TeX's libkpathsea is used to find the fonts (`.mf', `.afm',
 154      `.tfm').  Make sure you have tetex 1.0 or newer (1.0.6 is known to
 155      work).  You may need to install a tetex-devel or tetex-dev package
 156      too.
 157
 158    * Texinfo (version 4.0 or newer).  The documentation of lily is
 159      written in texinfo.  Check out the texinfo FTP directory
 160      (ftp://ftp.gnu.org/gnu/texinfo/).
 161
 162    * The geometry package for LaTeX is needed to use ly2dvi.  It is
 163      available at the FTP directory for `geometry'
 164      (ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry).
 165      This package is normally included with the TeX distribution.
 166
 167    * kpathsea, a library for searching (TeX) files.  `kpathsea' is
 168      usually included with your installation of TeX.  You may need to
 169      install a tetex-devel or tetex-dev package too.
 170
 171      In the very unlikely case that kpathsea is not available for your
 172      platform (ie, you're not running GNU/Linux, Windows, or any recent
 173      UNIX), you can compile LilyPond without kpathsea support.  In that
 174      case, you'll probably have to indicate where TeX's tfm files live.
 175      Invoke configure something like:
 176
 177           ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
 178
 179    * pktrace 1.0 or newer, [OPTIONAL], needed for generating PostScript
 180      Type1 fonts. Get it from  `http://www.cs.uu.nl/~hanwen/pktrace/'.
 181      You will need to install some additional packages to get pktrace
 182      to work.
 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    * texinfo (a development release) The documentation will build with
 228      texinfo-4.0, but if you want split html pages, you're best off
 229      using the lates pretest version from texinfo-4.0b
 230      (ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz) or
 231      texinfo-4.0b (ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz)
 232
 233 Building  LilyPond
 234 ==================
 235
 236    to install GNU LilyPond, type:
 237         gunzip -c lilypond-x.y.z | tar xf -
 238         cd lilypond-x.y.z
 239         ./configure             # run with --help to see appropriate options
 240         make
 241         make install
 242              sh buildscripts/clean-fonts.sh
 243
 244    If you are doing an upgrade, you should remove all `feta' `.pk' and
 245 `.tfm' files.  A script has been provided to do the work for you, see
 246 `buildscripts/clean-fonts.sh'.
 247
 248    If you are not root, you should choose a `--prefix' argument that
 249 points into your home directory, eg.
 250
 251         ./configure --prefix=$HOME/usr
 252
 253    In this case, you have to insert the contents of
 254 `buildscripts/out/lilypond-login' or
 255 `buildscripts/out/lilypond-profile' into your start up scripts by hand.
 256
 257 Configuring for multiple platforms
 258 ----------------------------------
 259
 260    If you want to build multiple versions of LilyPond with different
 261 configuration settings, you can use the `--enable-config=CONF' option
 262 of configure.  You should use `make conf=CONF' to generate the output
 263 in `out-CONF'.  Example: suppose I want to build with and without
 264 profiling.  Then I'd use the following for the normal build,
 265
 266            ./configure --prefix=~ --enable-checking
 267            make
 268            make install
 269
 270    and for the profiling version, I specify a different configuration.
 271
 272
 273            ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
 274            make conf=prof
 275            make conf=prof install
 276
 277 Emacs mode
 278 ==========
 279
 280    An Emacs mode for entering music and running LilyPond is included
 281 with the source archive as `lilypond-mode.el' and
 282 `lilypond-font-lock.el'.  You should install these files somewhere in
 283 your LOAD-PATH.  If you have installed a precompiled LilyPond package,
 284 these files can be found in `/usr/share/doc/lilypond-x.y.z/'.
 285
 286    Add this to your `~/.emacs' or `~/.emacs.el', or install this file
 287 in Emacs' `site-start.d':
 288          ;;; lilypond-init.el --- Startup code for LilyPond mode
 289
 290          (load-library "lilypond-mode.el")
 291          (setq auto-mode-alist
 292            (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
 293          (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
 294
 295    If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode
 296 is automatically loaded, you not even need to modify your `~/.emacs'
 297 file.
 298
 299 Compiling for distributions
 300 ===========================
 301
 302 Red Hat Linux
 303 -------------
 304
 305    Red Hat 7.0 i386 RPMS are available from
 306 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
 307
 308    You can also compile them yourself.  A spec file is in
 309 `make/out/lilypond.redhat.spec'. This file is distributed along with
 310 the sources.  You can make the rpm by issuing
 311
 312              tar xfz lilypond-x.y.z.tar.gz
 313         rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
 314         rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
 315
 316    For running on a Red Hat system you need these packages: guile,
 317 tetex, tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
 318
 319    For compilation on a Red Hat system you need these packages, in
 320 addition to the those needed for running: glibc-devel, gcc-c++,
 321 libstdc++-devel, guile-devel, flex, bison, texinfo, groff, pktrace.
 322
 323 LinuxPPC
 324 --------
 325
 326    Some LinuxPPC RPMS should available from
 327 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
 328
 329    A LinuxPPC RPM can be made using the `lilypond.redhat.spec' file.
 330
 331 SuSE
 332 ----
 333
 334    Some SUSE RPMS should available from
 335 `ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE'.
 336
 337    You can also compile a RPM for SUSE yourself.  A spec file is in
 338 `make/out/lilypond.suse.spec', see the instructions for building the
 339 Red Hat RPM.
 340
 341    You must have the following packages: guile tcsh tetex te_latex
 342 te_kpath te_mpost libpng python gpp libgpp gettext autoconf netpbm
 343 libnetpb gs_serv gs_lib gs_fonts guile
 344
 345 Slackware
 346 ---------
 347
 348    No precompiled packages for Slackware are available.
 349
 350    Problems have been reported with Slackware 7.0; apparently, it ships
 351 with a faulty compiler. Do not compile LilyPond with -O2 on this
 352 platform.
 353
 354 Mandrake
 355 --------
 356
 357    Some binaries are available at rpmfind.net. Refer to
 358 `http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/'.
 359
 360    You can also compile a RPM for Mandrake yourself.  A spec file is in
 361 `make/out/lilypond.mandrake.spec', see the instructions for building
 362 the Red Hat RPM.
 363
 364 Debian GNU/Linux
 365 ----------------
 366
 367    A Debian package is also available.  You may install it easily by
 368 running `apt-get' as root:
 369
 370         apt-get install lilypond lilypond-doc
 371
 372    You can also compile the .deb for Debian yourself, do:
 373
 374         apt-get -b source lilypond
 375
 376    If you're real impatient, you may even do:
 377
 378         cd lilypond-x.y.z   # a previous version
 379              uscan               # download and build latest directly from upstream
 380
 381    Debian's TeX installation is a bit short on memory, you may want to
 382 increase it like this:
 383      --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
 384      +++ texmf.cnf      Sun Dec 16 23:46:34 2001
 385      @ -411,8 +411,8 @
 386       main_memory.context = 1500000
 387       main_memory.mpost = 1000000
 388       main_memory = 263000 % words of inimemory available; also applies to inimf&mp
 389      -extra_mem_top = 0    % extra high memory for chars, tokens, etc.
 390      -extra_mem_bot = 0    % extra low memory for boxes, glue, breakpoints, etc.
 391      +extra_mem_top = 1000000    % extra high memory for chars, tokens, etc.
 392      +extra_mem_bot = 1000000    % extra low memory for boxes, glue, breakpoints, etc.
 393
 394       obj_tab_size.context = 300000
 395
 396      @ -430,7 +430,7 @
 397       % Max number of characters in all strings, including all error messages,
 398       % help texts, font names, control sequences.  These values apply to TeX and MP.
 399       pool_size.context = 750000
 400      -pool_size = 125000
 401      +pool_size = 250000
 402       % Minimum pool space after TeX/MP's own strings; must be at least
 403       % 25000 less than pool_size, but doesn't need to be nearly that large.
 404       string_vacancies.context = 45000
 405
 406    You could also export `extra_mem_top' and `extra_mem_bot' as
 407 environment variables if you do not want to or cannot modify
 408 `/etc/texmf/texmf.cnf'.
 409
 410    Alternatively, visit
 411
 412    * http://packages.debian.org/lilypond
 413      (http://packages.debian.org/lilypond)
 414
 415    * http://people.debian.org/~foka/lilypond/
 416      (http://people.debian.org/~foka/lilypond/) for latest
 417      semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato)
 418      users.  The official stable Debian 2.2 is stuck with the old
 419      LilyPond-1.3.24.  Since LilyPond-1.4 has been released, the older
 420      lilypond1.3 Debian package is now obsolete.
 421
 422    Please contact Anthony Fok <lilypond@packages.debian.org> for more
 423 information.
 424
 425    The build scripts are in the subdirectory `debian/'; you can make
 426 the .deb by doing, for example:
 427
 428         $ su - root
 429         # dpkg --purge lilypond lilypond1.3
 430         # exit
 431         $ tar xzf lilypond-1.4.3.tar.gz
 432         $ cd lilypond-1.4.3
 433         $ dch -p -v 1.4.3-0.local.1 "Local build."
 434         $ debuild -B
 435         $ su - root
 436         # dpkg -i ../lilypond_1.4.3*.deb
 437         # exit
 438         $
 439
 440    Use command `debuild' instead of `debuild -B' if you have a very
 441 fast machine and want to build the HTML, PS and DVI documentation too.
 442
 443    For compilation on a Debian GNU/Linux system you need these packages,
 444 in addition to the those needed for running:
 445
 446    * g++, cpp, libc6-dev, libstdc++<YOUR-LIBSTDC++-VERSION-HERE>-dev
 447
 448    * libguile<YOUR-LIBGUILE-VERSION-HERE>-dev
 449
 450    * make, m4, flex, bison
 451
 452    * gettext
 453
 454    * groff, texinfo
 455
 456    * tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
 457
 458    * dpkg-dev, debhelper, fakeroot
 459
 460    * gs, netpbm
 461
 462    * pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
 463       in Debian testing/unstable.)
 464
 465    Most of these are listed on the `Build-Depends' line in the
 466 `debian/control' file.  To ensure the creation of the lilypond deb is
 467 trouble-free, we recommend that you first install the following packages
 468 by running \`apt-get' as root before building the package:
 469
 470    For Debian 2.2:
 471
 472         apt-get install task-debian-devel task-c++-dev \
 473                 python-base libguile6-dev tetex-bin tetex-dev \
 474                 tetex-extra flex bison texinfo groff gs \
 475                 netpbm pnmtopng m4 gettext
 476
 477    For Debian in development ("unstable", the future 2.3 or 3.0):
 478
 479         apt-get install binutils cpp gcc libc6-dev \
 480                 g++ libstdc++2.10-dev \
 481                 python-base libguile-dev tetex-bin libkpathsea-dev \
 482                 tetex-extra flex bison texinfo  groff gs \
 483                 netpbm m4 gettext
 484
 485    And, just so that old fonts from previous versions of LilyPond won't
 486 interfere with your build, you may want to do this before the build too:
 487
 488         dpkg --purge lilypond lilypond1.3
 489
 490 MacOS X
 491 -------
 492
 493    LilyPond has been built on Darwin, to be precise, on:
 494          Darwin buoux.aspiratie.nl 5.3 Darwin Kernel Version 5.3: Thu Jan 24
 495          22:06:02 PST 2002; root:xnu/xnu-201.19.obj~1/RELEASE_PPC  Power Macintosh powerpc
 496
 497    using:
 498
 499          Apple Computer, Inc. version gcc-932.1, based on gcc version 2.95.2 19991024 (release)
 500
 501    To make sure you have all packages needed to build LilyPond
 502 installed, run as root:
 503
 504              apt-get install bash python guile debianutils flex bison texinfo \
 505                      ghostscript6 netpbm m4 gettext
 506
 507    and:
 508
 509              fink install tetex
 510
 511    For more information about `apt-get' and `fink', see
 512 fink.sourceforge.net (http://fink.sf.net).
 513
 514    Then, configure, patch, make and install LilyPond using these
 515 commands:
 516
 517              CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
 518                  ./configure --prefix=/sw
 519              make -C lily out/parser.hh out/parser.cc out/config.h
 520              patch -p0 < darwin.patch
 521              make -C lily out/parser.o
 522              make DEPENDENCIES_OUTPUT=/dev/null all
 523              make install
 524
 525    For installing, you must be root, of course.
 526
 527 Problems
 528 ========
 529
 530    For help and questions use <lilypond-user@gnu.org>.  Please consult
 531 the FAQ before mailing your problems.  If you find bugs, please send
 532 bug reports to <bug-lilypond@gnu.org>.
 533
 534    Bugs that are not fault of LilyPond are documented here.
 535
 536 FLex-2.5.4a and gcc-3.0
 537 -----------------------
 538
 539    Flex 2.5.4a does not produce g++-3.0 compliant C++ code.  To compile
 540 LilyPond with gcc-3.0 you may do:
 541
 542              CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
 543              make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
 544              patch -p1 < lexer-gcc-3.0.patch
 545              make conf=gcc-3.0 -C lily
 546
 547    Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
 548
 549 Linux-2.4.0, Guile-1.4 -with-threads
 550 ------------------------------------
 551
 552    There's a bug in certain kernels around version 2.4.0, that is
 553 triggered when using Guile 1.4 compiled with pthreads.  You'll see
 554 random segmentation fault crashes of LilyPond.  Upgrade to a newer
 555 version of Linux.  If you can't do that, you may try to recompiling
 556 Guile without threads (YMMV):
 557
 558               guile-1.4$ ./configure --without-threads; make all install
 559
 560 NetBSD
 561 ------
 562
 563    * The flex precompiled in NetBSD-1.4.2 is broken.  Download
 564      flex-2.5.4a, build, install.
 565
 566    * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 567      release)) does not include `/usr/pkg' paths.  Configure using:
 568
 569           CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 570
 571
 572 Solaris:
 573 --------
 574
 575    * Sparc64/Solaris 2.6, GNU make-3.77
 576
 577      GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
 578      newer.
 579
 580    * Sparc64/Solaris 2.6, ld
 581
 582      Not yet resolved.
 583
 584 AIX
 585 ---
 586
 587    * AIX 4.3 ld
 588
 589      The following is from the gcc install/SPECIFIC file.
 590              Some versions of the AIX binder (linker) can fail with a
 591           relocation    overflow severe error when the -bbigtoc option
 592           is used to link    GCC-produced object files into an
 593           executable that overflows the TOC.     A fix for APAR IX75823
 594           (OVERFLOW DURING LINK WHEN USING GCC AND    -BBIGTOC) is
 595           available from IBM Customer Support and from its
 596           27service.boulder.ibm.com website as PTF U455193.
 597
 598           Binutils does not support AIX 4.3 (at least through release
 599           2.9). GNU    as and GNU ld will not work properly and one
 600           should not configure GCC    to use those GNU utilities. Use
 601           the native AIX tools which do    interoperate with GCC.
 602
 603      add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 604               LDFLAGS='-Wl,-bbigtoc' ./configure
 605
 606