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     Python-2.1[.1]
  32     Linux-2.4.0, Guile-1.4 -with-threads
  33     NetBSD
  34     Solaris:
  35     AIX
  36
  37
  38 INSTALL - compiling and installing GNU LilyPond
  39 ***********************************************
  40
  41    This document describes how to build LilyPond on Unix platforms.  It
  42 is also known to run and compile on Windows NT/95/98 as well.  More
  43 information on this topic can be found at the LilyPond on Windows page
  44 (http://www.lilypond.org/gnu-windows/).
  45
  46 Downloading
  47 ===========
  48
  49    Even numbered versions are `stable'. The webpages for the stable
  50 version (1.2) reside on the GNU servers
  51 (http://www.gnu.org/software/lilypond). Big enhancements go into the
  52 latest odd numbered version (1.3), whose webpages are on the lilypond
  53 site (http://www.lilypond.org/).
  54
  55 Source code
  56 -----------
  57
  58    If you want to compile LilyPond from source, download here:
  59    * Download development releases from
  60      `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/' by FTP and
  61      `http://ftp.cs.uu.nl/pub/GNU/LilyPond/', by HTTP.
  62
  63    * `ftp://sca.uwaterloo.ca/pub/' by FTP (Canadian mirror)
  64
  65    * at `lilypond.org' `ftp://ftp.lilypond.org/pub/LilyPond/' by FTP and
  66      `http://www.lilypond.org/ftp/' by HTTP.
  67
  68    Of course, if your platform supports LilyPond, such as Debian
  69 GNU/Linux, FreeBSD, OpenBSD or NetBSD, you're encouraged to use the
  70 native build from source drill.
  71
  72    For Red Hat Linux and SuSE Linux, `.spec' files are included in the
  73 tarball; see instructions below.
  74
  75 Precompiled binaries
  76 --------------------
  77
  78    If you want to track bleeding edge development, try:
  79
  80    * Debian GNU/Linux
  81      (ftp://ftp.debian.org/debian/pool/main/l/lilypond/) usually has
  82      the latest binaries for the most useful stable and development
  83      versions, while
  84
  85    * Mandrake Cooker
  86      (http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/) also
  87      provides fairly recent versions.
  88
  89    Binaries are made available for other popular platforms, but as we
  90 need to compile them ourselves, they are not updated for every version
  91 released.
  92
  93    * Red Hat i386
  94      (ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/RedHat/RPMS/)
  95
  96    * SuSE (ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE)
  97
  98    * LinuxPPC (ftp://ftp.lilypond.org/pub/LilyPond/binaries/linuxppc/)
  99
 100    * Windows (http://www.lilypond.org/gnu-windows/)
 101
 102 Upgrading
 103 ---------
 104
 105    There are two options for upgrading sources.
 106
 107    * if you have an unpacked source tree of a previous version, you may
 108      the patches.
 109
 110      _If you upgrade by patching do remember to rerun autoconf after
 111      applying the patch_.
 112
 113    * if you have the `.tar.gz' file of a previous release, you can use
 114      xdelta (ftp://ftp.xcf.berkeley.edu/pub/xdelta/).   This is much
 115      safer than using patches, and is the recommended way.
 116
 117      The following command produces `lilypond-1.4.3.tar.gz' from
 118      `lilypond-1.4.2.tar.gz' identical (up to compression dates) to the
 119      .3 on the FTP site.
 120             xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
 121
 122 Requirements
 123 ============
 124
 125 Compilation
 126 -----------
 127
 128    You need the following packages to compile Lilypond.
 129
 130    * A reasonably new version of the GNU C++ compiler:  EGCS 1.1, GCC
 131      2.95.2 or newer. Check out the gcc site
 132      (ftp://ftp.gnu.org/gnu/gcc/).
 133
 134    * Python (version 1.5 or newer).  Check out the python website
 135      (http://www.python.org).
 136
 137    * GUILE (version 1.4 or newer).  Check out the GUILE webpage
 138      (http://www.gnu.org/software/guile/guile.html).  Version 1.4 is
 139      recommended for better performance.
 140
 141    * GNU Make.  Check out the GNU make FTP directory
 142      (ftp://ftp.gnu.org/gnu/make/).
 143
 144    * Flex (version 2.5.4a or newer).  Check out the Flex webpage
 145      (http://www.gnu.org/software/flex/).
 146
 147    * Bison (version 1.25 or newer).  Check out the bison webpage
 148      (http://www.gnu.org/software/bison/)
 149
 150    * TeX.
 151
 152      TeX is used as an output backend.
 153
 154      Also, TeX's libkpathsea is used to find the fonts (`.mf', `.afm',
 155      `.tfm').  Make sure you have tetex 1.0 or newer (1.0.6 is known to
 156      work).  You may need to install a tetex-devel or tetex-dev package
 157      too.
 158
 159    * Texinfo (version 4.0 or newer).  The documentation of lily is
 160      written in texinfo.  Check out the texinfo FTP directory
 161      (ftp://ftp.gnu.org/gnu/texinfo/).
 162
 163    * The geometry package for LaTeX is needed to use ly2dvi.  It is
 164      available at the FTP directory for `geometry'
 165      (ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry).
 166      This package is normally included with the TeX distribution.
 167
 168    * kpathsea, a library for searching (TeX) files.  `kpathsea' is
 169      usually included with your installation of TeX.  You may need to
 170      install a tetex-devel or tetex-dev package too.
 171
 172      In the very unlikely case that kpathsea is not available for your
 173      platform (ie, you're not running GNU/Linux, Windows, or any recent
 174      UNIX), you can compile LilyPond without kpathsea support.  In that
 175      case, you'll probably have to indicate where TeX's tfm files live.
 176      Invoke configure something like:
 177
 178           ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
 179
 180    * pktrace, [OPTIONAL], needed for generating PostScript Type1 fonts.
 181      Get it from  `http://www.cs.uu.nl/~hanwen/pktrace/'.  You will
 182      need to install some additional packages to get pktrace 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    Then, configure, patch, make and install LilyPond using these
 512 commands:
 513
 514              CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
 515                  ./configure --prefix=/sw
 516              make -C lily out/parser.hh out/parser.cc
 517              patch -p0 < darwin.patch
 518              make -C lily out/parser.o
 519              make all
 520              make install
 521
 522    For installing, you must be root, of course.
 523
 524 Problems
 525 ========
 526
 527    For help and questions use <lilypond-user@gnu.org>.  Please consult
 528 the FAQ before mailing your problems.  If you find bugs, please send
 529 bug reports to <bug-lilypond@gnu.org>.
 530
 531    Bugs that are not fault of LilyPond are documented here.
 532
 533 FLex-2.5.4a and gcc-3.0
 534 -----------------------
 535
 536    Flex 2.5.4a does not produce g++-3.0 compliant C++ code.  To compile
 537 LilyPond with gcc-3.0 you may do:
 538
 539              CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
 540              make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
 541              patch -p1 < lexer-gcc-3.0.patch
 542              make conf=gcc-3.0 -C lily
 543
 544    Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
 545
 546 Python-2.1[.1]
 547 --------------
 548
 549    Regular expressions are broken in Python 2.1.[.1], either upgrade or
 550 downgrade python.
 551
 552 Linux-2.4.0, Guile-1.4 -with-threads
 553 ------------------------------------
 554
 555    There's a bug in certain kernels around version 2.4.0, that is
 556 triggered when using Guile 1.4 compiled with pthreads.  You'll see
 557 random segmentation fault crashes of LilyPond.  Upgrade to a newer
 558 version of Linux.  If you can't do that, you may try to recompiling
 559 Guile without threads (YMMV):
 560
 561               guile-1.4$ ./configure --without-threads; make all install
 562
 563 NetBSD
 564 ------
 565
 566    * The flex precompiled in NetBSD-1.4.2 is broken.  Download
 567      flex-2.5.4a, build, install.
 568
 569    * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 570      release)) does not include `/usr/pkg' paths.  Configure using:
 571
 572           CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 573
 574
 575 Solaris:
 576 --------
 577
 578    * Sparc64/Solaris 2.6, GNU make-3.77
 579
 580      GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
 581      newer.
 582
 583    * Sparc64/Solaris 2.6, ld
 584
 585      Not yet resolved.
 586
 587 AIX
 588 ---
 589
 590    * AIX 4.3 ld
 591
 592      The following is from the gcc install/SPECIFIC file.
 593              Some versions of the AIX binder (linker) can fail with a
 594           relocation    overflow severe error when the -bbigtoc option
 595           is used to link    GCC-produced object files into an
 596           executable that overflows the TOC.     A fix for APAR IX75823
 597           (OVERFLOW DURING LINK WHEN USING GCC AND    -BBIGTOC) is
 598           available from IBM Customer Support and from its
 599           27service.boulder.ibm.com website as PTF U455193.
 600
 601           Binutils does not support AIX 4.3 (at least through release
 602           2.9). GNU    as and GNU ld will not work properly and one
 603           should not configure GCC    to use those GNU utilities. Use
 604           the native AIX tools which do    interoperate with GCC.
 605
 606      add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 607               LDFLAGS='-Wl,-bbigtoc' ./configure
 608
 609