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