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, [OPTIONAL], needed for generating PostScript Type1 fonts.
 180      Get it from  `http://www.cs.uu.nl/~hanwen/pktrace/'.  You will
 181      need to install some additional packages to get pktrace to work.
 182
 183
 184 Running requirements
 185 --------------------
 186
 187    GNU LilyPond does use a lot of resources. For operation you need the
 188 following software
 189
 190    * TeX.
 191
 192    * Xdvi and Ghostscript
 193
 194    * GUILE 1.3.4, or newer.  Check out the GUILE webpage
 195      (http://www.gnu.org/software/guile.html)
 196
 197    For running LilyPond successfully you have to help TeX and MetaFont
 198 find various files.  The recommended way of doing so is adjusting the
 199 environment variables in the start-up scripts of your shell. Appropriate
 200 Csh and bourne sh scripts are left in
 201 `buildscripts/out/lilypond-profile' and
 202 `buildscripts/out/lilypond-login' after compilation.
 203
 204    LilyPond is a big and slow program.  A fast CPU and plenty of RAM is
 205 recommended for comfortable use.
 206
 207 Website requirements
 208 --------------------
 209
 210    The documentation comes in the form of a website. You can view this
 211 website on the internet, but you can also build it locally. This process
 212 requires a successful compile of lilypond. The website is built by
 213 issuing
 214
 215        make web-doc
 216
 217    Building the website requires some additional tools:
 218
 219    * xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
 220      The original is at the netpbm FTP site
 221      (ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz)
 222
 223    * pnmtopng. The original is at in the pnmtopng FTP site
 224      (ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz).
 225
 226    * texinfo (a development release) The documentation will build with
 227      texinfo-4.0, but if you want split html pages, you're best off
 228      using the lates pretest version from texinfo-4.0b
 229      (ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz) or
 230      texinfo-4.0b (ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz)
 231
 232 Building  LilyPond
 233 ==================
 234
 235    to install GNU LilyPond, type:
 236         gunzip -c lilypond-x.y.z | tar xf -
 237         cd lilypond-x.y.z
 238         ./configure             # run with --help to see appropriate options
 239         make
 240         make install
 241              sh buildscripts/clean-fonts.sh
 242
 243    If you are doing an upgrade, you should remove all `feta' `.pk' and
 244 `.tfm' files.  A script has been provided to do the work for you, see
 245 `buildscripts/clean-fonts.sh'.
 246
 247    If you are not root, you should choose a `--prefix' argument that
 248 points into your home directory, eg.
 249
 250         ./configure --prefix=$HOME/usr
 251
 252    In this case, you have to insert the contents of
 253 `buildscripts/out/lilypond-login' or
 254 `buildscripts/out/lilypond-profile' into your start up scripts by hand.
 255
 256 Configuring for multiple platforms
 257 ----------------------------------
 258
 259    If you want to build multiple versions of LilyPond with different
 260 configuration settings, you can use the `--enable-config=CONF' option
 261 of configure.  You should use `make conf=CONF' to generate the output
 262 in `out-CONF'.  Example: suppose I want to build with and without
 263 profiling.  Then I'd use the following for the normal build,
 264
 265            ./configure --prefix=~ --enable-checking
 266            make
 267            make install
 268
 269    and for the profiling version, I specify a different configuration.
 270
 271
 272            ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
 273            make conf=prof
 274            make conf=prof install
 275
 276 Emacs mode
 277 ==========
 278
 279    An Emacs mode for entering music and running LilyPond is included
 280 with the source archive as `lilypond-mode.el' and
 281 `lilypond-font-lock.el'.  You should install these files somewhere in
 282 your LOAD-PATH.  If you have installed a precompiled LilyPond package,
 283 these files can be found in `/usr/share/doc/lilypond-x.y.z/'.
 284
 285    Add this to your `~/.emacs' or `~/.emacs.el', or install this file
 286 in Emacs' `site-start.d':
 287          ;;; lilypond-init.el --- Startup code for LilyPond mode
 288
 289          (load-library "lilypond-mode.el")
 290          (setq auto-mode-alist
 291            (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
 292          (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
 293
 294    If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode
 295 is automatically loaded, you not even need to modify your `~/.emacs'
 296 file.
 297
 298 Compiling for distributions
 299 ===========================
 300
 301 Red Hat Linux
 302 -------------
 303
 304    Red Hat 7.0 i386 RPMS are available from
 305 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
 306
 307    You can also compile them yourself.  A spec file is in
 308 `make/out/lilypond.redhat.spec'. This file is distributed along with
 309 the sources.  You can make the rpm by issuing
 310
 311              tar xfz lilypond-x.y.z.tar.gz
 312         rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
 313         rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
 314
 315    For running on a Red Hat system you need these packages: guile,
 316 tetex, tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
 317
 318    For compilation on a Red Hat system you need these packages, in
 319 addition to the those needed for running: glibc-devel, gcc-c++,
 320 libstdc++-devel, guile-devel, flex, bison, texinfo, groff, pktrace.
 321
 322 LinuxPPC
 323 --------
 324
 325    Some LinuxPPC RPMS should available from
 326 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
 327
 328    A LinuxPPC RPM can be made using the `lilypond.redhat.spec' file.
 329
 330 SuSE
 331 ----
 332
 333    Some SUSE RPMS should available from
 334 `ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE'.
 335
 336    You can also compile a RPM for SUSE yourself.  A spec file is in
 337 `make/out/lilypond.suse.spec', see the instructions for building the
 338 Red Hat RPM.
 339
 340    You must have the following packages: guile tcsh tetex te_latex
 341 te_kpath te_mpost libpng python gpp libgpp gettext autoconf netpbm
 342 libnetpb gs_serv gs_lib gs_fonts guile
 343
 344 Slackware
 345 ---------
 346
 347    No precompiled packages for Slackware are available.
 348
 349    Problems have been reported with Slackware 7.0; apparently, it ships
 350 with a faulty compiler. Do not compile LilyPond with -O2 on this
 351 platform.
 352
 353 Mandrake
 354 --------
 355
 356    Some binaries are available at rpmfind.net. Refer to
 357 `http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/'.
 358
 359    You can also compile a RPM for Mandrake yourself.  A spec file is in
 360 `make/out/lilypond.mandrake.spec', see the instructions for building
 361 the Red Hat RPM.
 362
 363 Debian GNU/Linux
 364 ----------------
 365
 366    A Debian package is also available.  You may install it easily by
 367 running `apt-get' as root:
 368
 369         apt-get install lilypond lilypond-doc
 370
 371    You can also compile the .deb for Debian yourself, do:
 372
 373         apt-get -b source lilypond
 374
 375    If you're real impatient, you may even do:
 376
 377         cd lilypond-x.y.z   # a previous version
 378              uscan               # download and build latest directly from upstream
 379
 380    Debian's TeX installation is a bit short on memory, you may want to
 381 increase it like this:
 382      --- texmf.cnf.orig Sun Dec 16 23:47:07 2001
 383      +++ texmf.cnf      Sun Dec 16 23:46:34 2001
 384      @ -411,8 +411,8 @
 385       main_memory.context = 1500000
 386       main_memory.mpost = 1000000
 387       main_memory = 263000 % words of inimemory available; also applies to inimf&mp
 388      -extra_mem_top = 0    % extra high memory for chars, tokens, etc.
 389      -extra_mem_bot = 0    % extra low memory for boxes, glue, breakpoints, etc.
 390      +extra_mem_top = 1000000    % extra high memory for chars, tokens, etc.
 391      +extra_mem_bot = 1000000    % extra low memory for boxes, glue, breakpoints, etc.
 392
 393       obj_tab_size.context = 300000
 394
 395      @ -430,7 +430,7 @
 396       % Max number of characters in all strings, including all error messages,
 397       % help texts, font names, control sequences.  These values apply to TeX and MP.
 398       pool_size.context = 750000
 399      -pool_size = 125000
 400      +pool_size = 250000
 401       % Minimum pool space after TeX/MP's own strings; must be at least
 402       % 25000 less than pool_size, but doesn't need to be nearly that large.
 403       string_vacancies.context = 45000
 404
 405    You could also export `extra_mem_top' and `extra_mem_bot' as
 406 environment variables if you do not want to or cannot modify
 407 `/etc/texmf/texmf.cnf'.
 408
 409    Alternatively, visit
 410
 411    * http://packages.debian.org/lilypond
 412      (http://packages.debian.org/lilypond)
 413
 414    * http://people.debian.org/~foka/lilypond/
 415      (http://people.debian.org/~foka/lilypond/) for latest
 416      semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato)
 417      users.  The official stable Debian 2.2 is stuck with the old
 418      LilyPond-1.3.24.  Since LilyPond-1.4 has been released, the older
 419      lilypond1.3 Debian package is now obsolete.
 420
 421    Please contact Anthony Fok <lilypond@packages.debian.org> for more
 422 information.
 423
 424    The build scripts are in the subdirectory `debian/'; you can make
 425 the .deb by doing, for example:
 426
 427         $ su - root
 428         # dpkg --purge lilypond lilypond1.3
 429         # exit
 430         $ tar xzf lilypond-1.4.3.tar.gz
 431         $ cd lilypond-1.4.3
 432         $ dch -p -v 1.4.3-0.local.1 "Local build."
 433         $ debuild -B
 434         $ su - root
 435         # dpkg -i ../lilypond_1.4.3*.deb
 436         # exit
 437         $
 438
 439    Use command `debuild' instead of `debuild -B' if you have a very
 440 fast machine and want to build the HTML, PS and DVI documentation too.
 441
 442    For compilation on a Debian GNU/Linux system you need these packages,
 443 in addition to the those needed for running:
 444
 445    * g++, cpp, libc6-dev, libstdc++<YOUR-LIBSTDC++-VERSION-HERE>-dev
 446
 447    * libguile<YOUR-LIBGUILE-VERSION-HERE>-dev
 448
 449    * make, m4, flex, bison
 450
 451    * gettext
 452
 453    * groff, texinfo
 454
 455    * tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
 456
 457    * dpkg-dev, debhelper, fakeroot
 458
 459    * gs, netpbm
 460
 461    * pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
 462       in Debian testing/unstable.)
 463
 464    Most of these are listed on the `Build-Depends' line in the
 465 `debian/control' file.  To ensure the creation of the lilypond deb is
 466 trouble-free, we recommend that you first install the following packages
 467 by running \`apt-get' as root before building the package:
 468
 469    For Debian 2.2:
 470
 471         apt-get install task-debian-devel task-c++-dev \
 472                 python-base libguile6-dev tetex-bin tetex-dev \
 473                 tetex-extra flex bison texinfo groff gs \
 474                 netpbm pnmtopng m4 gettext
 475
 476    For Debian in development ("unstable", the future 2.3 or 3.0):
 477
 478         apt-get install binutils cpp gcc libc6-dev \
 479                 g++ libstdc++2.10-dev \
 480                 python-base libguile-dev tetex-bin libkpathsea-dev \
 481                 tetex-extra flex bison texinfo  groff gs \
 482                 netpbm m4 gettext
 483
 484    And, just so that old fonts from previous versions of LilyPond won't
 485 interfere with your build, you may want to do this before the build too:
 486
 487         dpkg --purge lilypond lilypond1.3
 488
 489 MacOS X
 490 -------
 491
 492    LilyPond has been built on Darwin, to be precise, on:
 493          Darwin buoux.aspiratie.nl 5.3 Darwin Kernel Version 5.3: Thu Jan 24
 494          22:06:02 PST 2002; root:xnu/xnu-201.19.obj~1/RELEASE_PPC  Power Macintosh powerpc
 495
 496    using:
 497
 498          Apple Computer, Inc. version gcc-932.1, based on gcc version 2.95.2 19991024 (release)
 499
 500    To make sure you have all packages needed to build LilyPond
 501 installed, run as root:
 502
 503              apt-get install bash python guile debianutils flex bison texinfo \
 504                      ghostscript6 netpbm m4 gettext
 505
 506    and:
 507
 508              fink install tetex
 509
 510    For more information about `apt-get' and `fink', see
 511 fink.sourceforge.net (http://fink.sf.net).
 512
 513    Then, configure, patch, make and install LilyPond using these
 514 commands:
 515
 516              CC="cc -I/sw/include" CXX="c++ -I/sw/include" LDFLAGS="-L/sw/lib" \
 517                  ./configure --prefix=/sw
 518              make -C lily out/parser.hh out/parser.cc out/config.h
 519              patch -p0 < darwin.patch
 520              make -C lily out/parser.o
 521              make DEPENDENCIES_OUTPUT=/dev/null all
 522              make install
 523
 524    For installing, you must be root, of course.
 525
 526 Problems
 527 ========
 528
 529    For help and questions use <lilypond-user@gnu.org>.  Please consult
 530 the FAQ before mailing your problems.  If you find bugs, please send
 531 bug reports to <bug-lilypond@gnu.org>.
 532
 533    Bugs that are not fault of LilyPond are documented here.
 534
 535 FLex-2.5.4a and gcc-3.0
 536 -----------------------
 537
 538    Flex 2.5.4a does not produce g++-3.0 compliant C++ code.  To compile
 539 LilyPond with gcc-3.0 you may do:
 540
 541              CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
 542              make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
 543              patch -p1 < lexer-gcc-3.0.patch
 544              make conf=gcc-3.0 -C lily
 545
 546    Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
 547
 548 Linux-2.4.0, Guile-1.4 -with-threads
 549 ------------------------------------
 550
 551    There's a bug in certain kernels around version 2.4.0, that is
 552 triggered when using Guile 1.4 compiled with pthreads.  You'll see
 553 random segmentation fault crashes of LilyPond.  Upgrade to a newer
 554 version of Linux.  If you can't do that, you may try to recompiling
 555 Guile without threads (YMMV):
 556
 557               guile-1.4$ ./configure --without-threads; make all install
 558
 559 NetBSD
 560 ------
 561
 562    * The flex precompiled in NetBSD-1.4.2 is broken.  Download
 563      flex-2.5.4a, build, install.
 564
 565    * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 566      release)) does not include `/usr/pkg' paths.  Configure using:
 567
 568           CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 569
 570
 571 Solaris:
 572 --------
 573
 574    * Sparc64/Solaris 2.6, GNU make-3.77
 575
 576      GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
 577      newer.
 578
 579    * Sparc64/Solaris 2.6, ld
 580
 581      Not yet resolved.
 582
 583 AIX
 584 ---
 585
 586    * AIX 4.3 ld
 587
 588      The following is from the gcc install/SPECIFIC file.
 589              Some versions of the AIX binder (linker) can fail with a
 590           relocation    overflow severe error when the -bbigtoc option
 591           is used to link    GCC-produced object files into an
 592           executable that overflows the TOC.     A fix for APAR IX75823
 593           (OVERFLOW DURING LINK WHEN USING GCC AND    -BBIGTOC) is
 594           available from IBM Customer Support and from its
 595           27service.boulder.ibm.com website as PTF U455193.
 596
 597           Binutils does not support AIX 4.3 (at least through release
 598           2.9). GNU    as and GNU ld will not work properly and one
 599           should not configure GCC    to use those GNU utilities. Use
 600           the native AIX tools which do    interoperate with GCC.
 601
 602      add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 603               LDFLAGS='-Wl,-bbigtoc' ./configure
 604
 605