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     Python-2.1[.1]
  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, tetex-devel, groff,
 321 libgr-progs.
 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 Problems
 491 ========
 492
 493    For help and questions use <lilypond-user@gnu.org>.  Please consult
 494 the FAQ before mailing your problems.  If you find bugs, please send
 495 bug reports to <bug-lilypond@gnu.org>.
 496
 497    Bugs that are not fault of LilyPond are documented here.
 498
 499 FLex-2.5.4a and gcc-3.0
 500 -----------------------
 501
 502    Flex 2.5.4a does not produce g++-3.0 compliant C++ code.  To compile
 503 LilyPond with gcc-3.0 you may do:
 504
 505              CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
 506              make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
 507              patch -p1 < lexer-gcc-3.0.patch
 508              make conf=gcc-3.0 -C lily
 509
 510    Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
 511
 512 Python-2.1[.1]
 513 --------------
 514
 515    Regular expressions are broken in Python 2.1.[.1], either upgrade or
 516 downgrade python.
 517
 518 Linux-2.4.0, Guile-1.4 -with-threads
 519 ------------------------------------
 520
 521    There's a bug in certain kernels around version 2.4.0, that is
 522 triggered when using Guile 1.4 compiled with pthreads.  You'll see
 523 random segmentation fault crashes of LilyPond.  Upgrade to a newer
 524 version of Linux.  If you can't do that, you may try to recompiling
 525 Guile without threads (YMMV):
 526
 527               guile-1.4$ ./configure --without-threads; make all install
 528
 529 NetBSD
 530 ------
 531
 532    * The flex precompiled in NetBSD-1.4.2 is broken.  Download
 533      flex-2.5.4a, build, install.
 534
 535    * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 536      release)) does not include `/usr/pkg' paths.  Configure using:
 537
 538           CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 539
 540
 541 Solaris:
 542 --------
 543
 544    * Sparc64/Solaris 2.6, GNU make-3.77
 545
 546      GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
 547      newer.
 548
 549    * Sparc64/Solaris 2.6, ld
 550
 551      Not yet resolved.
 552
 553 AIX
 554 ---
 555
 556    * AIX 4.3 ld
 557
 558      The following is from the gcc install/SPECIFIC file.
 559              Some versions of the AIX binder (linker) can fail with a
 560           relocation    overflow severe error when the -bbigtoc option
 561           is used to link    GCC-produced object files into an
 562           executable that overflows the TOC.     A fix for APAR IX75823
 563           (OVERFLOW DURING LINK WHEN USING GCC AND    -BBIGTOC) is
 564           available from IBM Customer Support and from its
 565           27service.boulder.ibm.com website as PTF U455193.
 566
 567           Binutils does not support AIX 4.3 (at least through release
 568           2.9). GNU    as and GNU ld will not work properly and one
 569           should not configure GCC    to use those GNU utilities. Use
 570           the native AIX tools which do    interoperate with GCC.
 571
 572      add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 573               LDFLAGS='-Wl,-bbigtoc' ./configure
 574
 575