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