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    * texinfo (a development release) The documentation will build with
 235      texinfo-4.0, but if you want split html pages, you're best off
 236      using the lates pretest version from texinfo-4.0b
 237      (ftp://texinfo.org/texinfo/pretests/texinfo-4.0b.tar.gz) or
 238      texinfo-4.0b (ftp://alpha.gnu.org/gnu/texinfo-4.0b.tar.gz)
 239
 240 Building  LilyPond
 241 ==================
 242
 243    to install GNU LilyPond, type:
 244         gunzip -c lilypond-x.y.z | tar xf -
 245         cd lilypond-x.y.z
 246         ./configure             # run with --help to see appropriate options
 247         make
 248         make install
 249              sh buildscripts/clean-fonts.sh
 250
 251    If you are doing an upgrade, you should remove all `feta' `.pk' and
 252 `.tfm' files.  A script has been provided to do the work for you, see
 253 `buildscripts/clean-fonts.sh'.
 254
 255    If you are not root, you should choose a `--prefix' argument that
 256 points into your home directory, eg.
 257
 258         ./configure --prefix=$HOME/usr
 259
 260    In this case, you have to insert the contents of
 261 `buildscripts/out/lilypond-login' or
 262 `buildscripts/out/lilypond-profile' into your start up scripts by hand.
 263
 264 Configuring for multiple platforms
 265 ----------------------------------
 266
 267    If you want to build multiple versions of LilyPond with different
 268 configuration settings, you can use the `--enable-config=CONF' option
 269 of configure.  You should use `make conf=CONF' to generate the output
 270 in `out-CONF'.  Example: suppose I want to build with and without
 271 profiling.  Then I'd use the following for the normal build,
 272
 273            ./configure --prefix=~ --enable-checking
 274            make
 275            make install
 276
 277    and for the profiling version, I specify a different configuration.
 278
 279
 280            ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
 281            make conf=prof
 282            make conf=prof install
 283
 284 Emacs mode
 285 ==========
 286
 287    An Emacs mode for entering music and running LilyPond is included
 288 with the source archive as `lilypond-mode.el' and
 289 `lilypond-font-lock.el'.  You should install these files somewhere in
 290 your LOAD-PATH.  If you have installed a precompiled LilyPond package,
 291 these files can be found in `/usr/share/doc/lilypond-x.y.z/'.
 292
 293    Add this to your `~/.emacs' or `~/.emacs.el', or install this file
 294 in Emacs' `site-start.d':
 295          ;;; lilypond-init.el --- Startup code for LilyPond mode
 296
 297          (load-library "lilypond-mode.el")
 298          (setq auto-mode-alist
 299            (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
 300          (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
 301
 302    If you have the latest LilyPond-1.4.x Debian package, LilyPond-mode
 303 is automatically loaded, you not even need to modify your `~/.emacs'
 304 file.
 305
 306 Compiling for distributions
 307 ===========================
 308
 309 Red Hat Linux
 310 -------------
 311
 312    Red Hat 7.0 i386 RPMS are available from
 313 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
 314
 315    You can also compile them yourself.  A spec file is in
 316 `make/out/lilypond.redhat.spec'. This file is distributed along with
 317 the sources.  You can make the rpm by issuing
 318
 319              tar xfz lilypond-x.y.z.tar.gz
 320         rpm -bb lilypond-x.y.z/make/out/lilypond.redhat.spec
 321         rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
 322
 323    For running on a Red Hat system you need these packages: guile,
 324 tetex, tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
 325
 326    For compilation on a Red Hat system you need these packages, in
 327 addition to the those needed for running: glibc-devel, gcc-c++,
 328 libstdc++-devel, guile-devel, flex, bison, texinfo, tetex-devel, groff,
 329 libgr-progs.
 330
 331 LinuxPPC
 332 --------
 333
 334    Some LinuxPPC RPMS should available from
 335 `ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/'.
 336
 337    A LinuxPPC RPM can be made using the `lilypond.redhat.spec' file.
 338
 339 SuSE
 340 ----
 341
 342    Some SUSE RPMS should available from
 343 `ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE'.
 344
 345    You can also compile a RPM for SUSE yourself.  A spec file is in
 346 `make/out/lilypond.suse.spec', see the instructions for building the
 347 Red Hat RPM.
 348
 349    You must have the following packages: guile tcsh tetex te_latex
 350 te_kpath te_mpost libpng python gpp libgpp gettext autoconf netpbm
 351 libnetpb gs_serv gs_lib gs_fonts guile
 352
 353 Slackware
 354 ---------
 355
 356    No precompiled packages for Slackware are available.
 357
 358    Problems have been reported with Slackware 7.0; apparently, it ships
 359 with a faulty compiler. Do not compile LilyPond with -O2 on this
 360 platform.
 361
 362 Mandrake
 363 --------
 364
 365    Some binaries are available at rpmfind.net. Refer to
 366 `http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/'.
 367
 368    You can also compile a RPM for Mandrake yourself.  A spec file is in
 369 `make/out/lilypond.mandrake.spec', see the instructions for building
 370 the Red Hat RPM.
 371
 372 Debian GNU/Linux
 373 ----------------
 374
 375    A Debian package is also available.  You may install it easily by
 376 running `apt-get' as root:
 377
 378         apt-get install lilypond lilypond-doc
 379
 380    You can also compile the .deb for Debian yourself, do:
 381
 382         apt-get -b source lilypond
 383
 384    If you're real impatient, you may even do:
 385
 386         cd lilypond-x.y.z   # a previous version
 387              uscan               # download and build latest directly from upstream
 388
 389    Debian's TeX installation is a bit short on memory, you may want to
 390 increase it like this:
 391      --- /etc/texmf/texmf.cnf.dpkg      Sun Jan 28 14:12:14 2001
 392      +++ /etc/texmf/texmf.cnf   Fri Apr 27 11:09:35 2001
 393      @ -384,8 +384,8 @
 394       main_memory.context = 1500000
 395       main_memory.mpost = 1000000
 396       main_memory = 263000 % words of inimemory available; also applies to inimf&mp
 397      -extra_mem_top = 0    % extra high memory for chars, tokens, etc.
 398      -extra_mem_bot = 0    % extra low memory for boxes, glue, breakpoints, etc.
 399      +extra_mem_top = 100000    % extra high memory for chars, tokens, etc.
 400      +extra_mem_bot = 100000    % extra low memory for boxes, glue, breakpoints, etc.
 401
 402       obj_tab_size.context = 256000
 403
 404    You could also export `extra_mem_top' and `extra_mem_bot' as
 405 environment variables if you do not want to or cannot modify
 406 `/etc/texmf/texmf.cnf'.
 407
 408    Alternatively, visit
 409
 410    * http://packages.debian.org/lilypond
 411      (http://packages.debian.org/lilypond)
 412
 413    * http://people.debian.org/~foka/lilypond/
 414      (http://people.debian.org/~foka/lilypond/) for latest
 415      semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato)
 416      users.  The official stable Debian 2.2 is stuck with the old
 417      LilyPond-1.3.24.  Since LilyPond-1.4 has been released, the older
 418      lilypond1.3 Debian package is now obsolete.
 419
 420    Please contact Anthony Fok <lilypond@packages.debian.org> for more
 421 information.
 422
 423    The build scripts are in the subdirectory `debian/'; you can make
 424 the .deb by doing, for example:
 425
 426         $ su - root
 427         # dpkg --purge lilypond lilypond1.3
 428         # exit
 429         $ tar xzf lilypond-1.4.3.tar.gz
 430         $ cd lilypond-1.4.3
 431         $ dch -p -v 1.4.3-0.local.1 "Local build."
 432         $ debuild -B
 433         $ su - root
 434         # dpkg -i ../lilypond_1.4.3*.deb
 435         # exit
 436         $
 437
 438    Use command `debuild' instead of `debuild -B' if you have a very
 439 fast machine and want to build the HTML, PS and DVI documentation too.
 440
 441    For compilation on a Debian GNU/Linux system you need these packages,
 442 in addition to the those needed for running:
 443
 444    * g++, cpp, libc6-dev, libstdc++<YOUR-LIBSTDC++-VERSION-HERE>-dev
 445
 446    * libguile<YOUR-LIBGUILE-VERSION-HERE>-dev
 447
 448    * make, m4, flex, bison
 449
 450    * gettext
 451
 452    * groff, texinfo
 453
 454    * tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
 455
 456    * dpkg-dev, debhelper, fakeroot
 457
 458    * gs, netpbm
 459
 460    * pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
 461       in Debian testing/unstable.)
 462
 463    Most of these are listed on the `Build-Depends' line in the
 464 `debian/control' file.  To ensure the creation of the lilypond deb is
 465 trouble-free, we recommend that you first install the following packages
 466 by running \`apt-get' as root before building the package:
 467
 468    For Debian 2.2:
 469
 470         apt-get install task-debian-devel task-c++-dev \
 471                 python-base libguile6-dev tetex-bin tetex-dev \
 472                 tetex-extra flex bison texinfo groff gs \
 473                 netpbm pnmtopng m4 gettext
 474
 475    For Debian in development ("unstable", the future 2.3 or 3.0):
 476
 477         apt-get install binutils cpp gcc libc6-dev \
 478                 g++ libstdc++2.10-dev \
 479                 python-base libguile-dev tetex-bin libkpathsea-dev \
 480                 tetex-extra flex bison texinfo  groff gs \
 481                 netpbm m4 gettext
 482
 483    And, just so that old fonts from previous versions of LilyPond won't
 484 interfere with your build, you may want to do this before the build too:
 485
 486         dpkg --purge lilypond lilypond1.3
 487
 488 Problems
 489 ========
 490
 491    For help and questions use <lilypond-user@gnu.org>.  Please consult
 492 the FAQ before mailing your problems.  If you find bugs, please send
 493 bug reports to <bug-lilypond@gnu.org>.
 494
 495    Bugs that are not fault of LilyPond are documented here.
 496
 497 FLex-2.5.4a and gcc-3.0
 498 -----------------------
 499
 500    Flex 2.5.4a does not produce g++-3.0 compliant C++ code.  To compile
 501 LilyPond with gcc-3.0 you may do:
 502
 503              CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
 504              make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
 505              patch -p1 < lexer-gcc-3.0.patch
 506              make conf=gcc-3.0 -C lily
 507
 508    Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
 509
 510 Linux-2.4.0, Guile-1.4 -with-threads
 511 ------------------------------------
 512
 513    There's a bug in certain kernels around version 2.4.0, that is
 514 triggered when using Guile 1.4 compiled with pthreads.  You'll see
 515 random segmentation fault crashes of LilyPond.  Upgrade to a newer
 516 version of Linux.  If you can't do that, you may try to recompiling
 517 Guile without threads (YMMV):
 518
 519               guile-1.4$ ./configure --without-threads; make all install
 520
 521 NetBSD
 522 ------
 523
 524    * The flex precompiled in NetBSD-1.4.2 is broken.  Download
 525      flex-2.5.4a, build, install.
 526
 527    * The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 528      release)) does not include `/usr/pkg' paths.  Configure using:
 529
 530           CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 531
 532
 533 Solaris:
 534 --------
 535
 536    * Sparc64/Solaris 2.6, GNU make-3.77
 537
 538      GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or
 539      newer.
 540
 541    * Sparc64/Solaris 2.6, ld
 542
 543      Not yet resolved.
 544
 545 AIX
 546 ---
 547
 548    * AIX 4.3 ld
 549
 550      The following is from the gcc install/SPECIFIC file.
 551              Some versions of the AIX binder (linker) can fail with a
 552           relocation    overflow severe error when the -bbigtoc option
 553           is used to link    GCC-produced object files into an
 554           executable that overflows the TOC.     A fix for APAR IX75823
 555           (OVERFLOW DURING LINK WHEN USING GCC AND    -BBIGTOC) is
 556           available from IBM Customer Support and from its
 557           27service.boulder.ibm.com website as PTF U455193.
 558
 559           Binutils does not support AIX 4.3 (at least through release
 560           2.9). GNU    as and GNU ld will not work properly and one
 561           should not configure GCC    to use those GNU utilities. Use
 562           the native AIX tools which do    interoperate with GCC.
 563
 564      add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 565               LDFLAGS='-Wl,-bbigtoc' ./configure
 566
 567