Documentation/topdocs/INSTALL.texi

   1 \input texinfo @c -*-texinfo-*-
   2 @setfilename INSTALL.info
   3 @settitle INSTALL - compiling and installing GNU LilyPond
   4
   5 @node Top, , , (dir)
   6 @top
   7
   8 @chapter INSTALL - compiling and installing GNU LilyPond
   9
  10 @section Downloading source code
  11
  12 @html
  13 <a name="download-source">
  14 @end html
  15
  16 If you want to compile LilyPond from source, download here:
  17 @itemize @bullet
  18 @item Download stable releases at
  19 @uref{ftp://ftp.gnu.org/gnu/lilypond/,GNU}
  20 @item Download development releases from
  21 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/development/, by FTP} and
  22 @uref{http://ftp.cs.uu.nl/pub/GNU/LilyPond/development/, by HTTP}.
  23 @item @uref{ftp://sca.uwaterloo.ca/pub/, ftp (Canadian mirror)}
  24 @item at @code{lilypond.org} by
  25 @uref{ftp://ftp.lilypond.org/pub/LilyPond/, FTP} and
  26 @uref{http://www.lilypond.org/ftp/, HTTP}.
  27 @end itemize
  28
  29 Installing and compiling requires many additional packages, which are
  30 listed in the @uref{Documentation/topdocs/out-www/INSTALL.html,
  31 installation instructions}.
  32
  33
  34 @section Downloading binaries
  35
  36 @html
  37 <a name="download-binary">
  38 @end html
  39 Binaries are available, but are not updated for every version released.
  40 @itemize @bullet
  41 @item @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/RedHat/RPMS/, RedHat i386}
  42 @item @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/linuxppc, LinuxPPC}
  43 @item
  44 @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond,
  45 Debian GNU/Linux Stable}
  46 @item
  47 @uref{ftp://ftp.debian.org/debian/pool/main/l/lilypond1.3,
  48 Debian GNU/Linux Unstable}
  49 @item @uref{http://home.austin.rr.com/jbr/jeff/lilypond/, Windows Stable}
  50 @item @uref{ftp://ftp.lilypond.org/pub/lilypond/gnu-windows, Windows
  51 Testing}
  52 @end itemize
  53
  54
  55
  56 @section Upgrading
  57
  58 There are two  options for upgrading sources.
  59
  60 @itemize
  61 @item if you have an unpacked source tree of a previous version, you
  62 may the patches.
  63
  64 @emph{If you upgrade by patching do remember to rerun autoconf after
  65 applying the patch}.
  66
  67 @item if you have the @code{.tar.gz} file of a previous release, you can
  68 use
  69 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/, xdelta}.
  70  This is much safer than using patches, and is the recommended way.
  71
  72 The following command produces @file{lilypond-1.3.122.tar.gz} from
  73 @file{lilypond-1.3.121} identical (up to compression dates) to the .122
  74 on the FTP site.
  75 @example
  76   xdelta patch lilypond-1.3.121-1.3.122.xd lilypond-1.3.121.tar.gz
  77 @end example
  78 @end itemize
  79
  80 @section Build requirements
  81
  82 This document describes how to build LilyPond on Unix platforms.  It is
  83 also known to run and compile on Windows NT/95/98 as well.  More
  84 information on this topic can be found at the
  85 @uref{ftp://ftp.lilypond.org/pub/LilyPond/gnu-windows/, LilyPond on Windows
  86 page}.
  87
  88 You need the following packages to compile Lilypond.
  89
  90 @itemize
  91 @item A reasonably new C++ compiler:  EGCS 1.1, GCC 2.95.2 or
  92 newer. Check out @uref{ftp://ftp.gnu.org/gnu/gcc/, the gcc site}.
  93
  94 @item  Python 1.5,
  95 Check out @uref{http://www.python.org, the python website}.
  96
  97 @item  GUILE 1.3.4 or newer,  check out
  98 @uref{http://www.gnu.org/software/guile/guile.html,the GUILE webpage}.
  99 Version 1.4 is recommended for better performance.
 100
 101 @item GNU Make.
 102 Check out
 103 @uref{ftp://ftp.gnu.org/gnu/make/, the GNU
 104 make FTP directory}.
 105
 106 @item Flex (version 2.5.4a or newer).
 107 Check out @uref{http://www.gnu.org/software/flex/,the Flex webpage}.
 108
 109 @item Bison (version 1.25 or newer).
 110 Check out @uref{http://www.gnu.org/software/bison/,the bison  webpage}
 111
 112 @item @TeX{}.
 113
 114 @TeX{} is used as an output backend.
 115
 116 Also, @TeX{}'s libkpathsea is used to find the fonts (.mf, .afm, .tfm).
 117 Make sure you have tetex 1.0 or newer (1.0.6 is known to work).  You may
 118 need to install a tetex-devel or tetex-dev package too.
 119
 120 @item Texinfo (version 4.0 or newer).
 121 The documentation of lily is written in texinfo.  Check out
 122 @uref{ftp://ftp.gnu.org/gnu/texinfo/,the texinfo FTP directory}.
 123
 124 @item The geometry package for LaTeX is needed to use ly2dvi.
 125 It is available at
 126 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,the
 127 FTP directory for @code{geometry}}. This package is normally included
 128 with the @TeX{} distribution.
 129
 130 @item MetaPost, needed for generating PostScript fonts. Please
 131 note that tetex-0.4pl8 (included with Red Hat 5.x) does not include
 132 @file{mfplain.mp}, which is needed for producing the scalable font
 133 files.
 134
 135 If you don't have MetaPost and don't want to use PostScript output, then
 136 edit @file{mf/GNUmakefile}, removing the line saying @code{PFA_FILES=}.
 137
 138 @item kpathsea, a library for searching (TeX) files.  @code{kpathsea} is
 139 usually included with your installation of TeX.  You may need to install
 140 a tetex-devel or tetex-dev package too.
 141
 142 In the very unlikely case that kpathsea is not available for your
 143 platform (ie, you're not running GNU/Linux, Windows, or any recent
 144 UNIX), you can compile LilyPond without kpathsea support.  In that case,
 145 you'll probably have to indicate where @TeX{}'s tfm files live.  Invoke
 146 configure something like:
 147
 148 @example
 149 ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
 150 @end example
 151
 152 @end itemize
 153
 154 @section Running requirements
 155
 156 GNU LilyPond does use a lot of resources. For operation you need the
 157 following software
 158
 159 @itemize @bullet
 160 @item TeX.
 161 @item Xdvi and ghostscript
 162 @item GUILE 1.3.4, or newer.  Check out
 163 @uref{http://www.gnu.org/software/guile.html,the GUILE webpage}
 164 @end itemize
 165
 166 For running LilyPond successfully you have to help TeX and MetaFont find
 167 various files.  The recommended way of doing so is adjusting the
 168 environment variables in the start-up scripts of your shell. Appropriate
 169 Csh and bourne sh scripts are left in
 170 @file{buildscripts/out/lilypond-profile} and
 171 @file{buildscripts/out/lilypond-login} after compilation.
 172
 173 LilyPond is a big and slow program.  A fast CPU and plenty of RAM is
 174 recommended for comfortable use.
 175
 176 @section Website requirements
 177
 178 The documentation comes in the form of a website. You can view this
 179 website on the internet, but you can also build it locally. This process
 180 requires a successful compile of lilypond. The website is built
 181 by issuing
 182 @example
 183
 184   make web-doc
 185
 186 @end example
 187
 188 Building the website requires  some additional tools:
 189
 190 @itemize @bullet
 191 @item xpmtoppm (from the netpbm package: the Portable Bitmap Utilities).
 192         The original is at
 193 @uref{ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz,the
 194 netpbm FTP site}
 195
 196 @item pnmtopng. The original is
 197 at
 198 @uref{ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz,in
 199 the pnmtopng FTP site}.
 200
 201 @item @uref{http://www.lri.fr/~filliatr/ftp/bibtex2html/, Bibtex2html}, or
 202 @uref{http://www.uni-koblenz.de/ag-ki/ftp/bib2html/, Bib2html}.
 203 Bibtex2html is available in debian, while bib2html is in some rpm based
 204 distributions.
 205 Bib2html, in turn depends on man2html for proper installation.
 206 man2html can be had from @uref{http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05,http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05}.
 207
 208 The website will build without bib converter utility, but you will not
 209 see our hypertextified bibliography.
 210
 211 @end itemize
 212
 213 @section Configuring and compiling
 214
 215 to install GNU LilyPond, type:
 216 @example
 217         gunzip -c lilypond-x.y.z | tar xf -
 218         cd lilypond-x.y.z
 219         ./configure             # run with --help to see appropriate options
 220         make
 221         make install
 222         sh buildscripts/clean-fonts.sh
 223 @end example
 224
 225 If you are doing an upgrade, you should remove all @file{feta}
 226 @code{.pk} and @file{.tfm} files.  A script has been provided to do the
 227 work for you, see @file{buildscripts/clean-fonts.sh}.
 228
 229
 230 If you are not root, you should choose a @code{--prefix} argument that
 231 points into your home directory, eg.
 232 @example
 233
 234         ./configure --prefix=$HOME/usr
 235
 236 @end example
 237
 238 In this case, you have to insert the contents of
 239 @code{buildscripts/out/lilypond-login} or
 240 @code{buildscripts/out/lilypond-profile} into your start up scripts by
 241 hand.
 242
 243
 244
 245 @section Configuring for multiple platforms
 246
 247 If you want to build multiple versions of LilyPond with different
 248 configuration settings, you can use the @code{--enable-config=CONF}
 249 option of configure.  You should use @samp{make conf=CONF} to generate
 250 the output in @file{out-CONF}.  Example: suppose I want to build with
 251 and without profiling.  Then I'd use the following for the normal build,
 252 @example
 253
 254       ./configure --prefix=~ --enable-checking
 255       make
 256       make install
 257 @end example
 258
 259 and for the profiling version, I specify a different configuration.
 260
 261 @example
 262
 263       ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
 264       make conf=prof
 265       make conf=prof install
 266
 267 @end example
 268
 269
 270
 271
 272
 273
 274
 275 @section Emacs mode
 276
 277 An emacs mode for LilyPond is included with the source archive as
 278 @file{lilypond-mode.el} and @file{lilypond-font-lock.el}.  If you have
 279 an RPM, it is in @file{/usr/share/doc/lilypond-X/}.  You have to install
 280 it yourself.
 281
 282 Add this to your ~/.emacs or ~/.emacs.el:
 283 @example
 284     (load-library "lilypond-mode.el")
 285     (setq auto-mode-alist
 286       (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
 287     (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
 288 @end example
 289
 290 If you have the latest LilyPond-1.3.x Debian package, LilyPond-mode is
 291 automatically loaded, so you need not modify your @code{~/.emacs} file.
 292
 293
 294 @section Red Hat Linux
 295
 296 Red Hat 7.0 i386 RPMS are available from
 297 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/RedHat/}.
 298
 299 You can also compile them yourself.  A spec file is in
 300 @file{make/out/lilypond.spec}. This file is distributed along with the
 301 sources.  You can make the rpm by issuing
 302 @example
 303
 304         rpm -tb lilypond-x.y.z.tar.gz
 305         rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
 306
 307 @end example
 308
 309 For running on a Red Hat system you need these packages: guile, tetex,
 310 tetex-dvips, libstdc++, python, ghostscript.
 311
 312 For compilation on a Red Hat system you need these packages, in addition
 313 to the those needed for running: glibc-devel, gcc-c++, libstdc++-devel,
 314 guile-devel, flex, bison, texinfo, tetex-devel, groff, libgr-progs.
 315
 316 @section SuSE
 317
 318 [TODO: document this]
 319
 320 Install @code{tetex}, @code{te_mpost}, @code{te_kpath}.
 321
 322
 323 @section Mandrake
 324
 325 [TODO]
 326
 327 @section Debian GNU/Linux
 328
 329 A Debian package is also available.  You may install it easily by using
 330 apt-get as root:
 331
 332 @example
 333         apt-get install lilypond1.3
 334 @end example
 335
 336 Alternatively, visit
 337
 338 @itemize @bullet
 339 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
 340 @item @uref{http://ftp.debian.org/debian/pool/main/l/lilypond1.3/,http://ftp.debian.org/debian/pool/main/l/lilypond1.3/}
 341 for latest package uploaded to Debian unstable;
 342 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
 343 for latest semi-unofficial build of LilyPond 1.3.121 for Debian 2.2r2 (potato) users.
 344 The official stable Debian 2.2r2 is stuck with the old LilyPond-1.3.24.
 345 @end itemize
 346
 347 You may contact Anthony Fok @email{foka@@debian.org} for more information.
 348
 349 The build scripts are in the subdirectory @file{debian/}; you can
 350 make the .deb by doing, for example:
 351
 352 @example
 353         $ su - root
 354         # dpkg --purge lilypond lilypond1.3
 355         # exit
 356         $ tar xzf lilypond-1.3.122.tar.gz
 357         $ cd lilypond-1.3.122
 358         $ dch -p -v 1.3.122-0.local.1 "Local build."
 359         $ debuild
 360         $ su - root
 361         # dpkg -i ../lilypond1.3_1.3.122*.deb
 362         # exit
 363         $
 364 @end example
 365
 366 For compilation on a Debian GNU/Linux system you need these packages,
 367 in addition to the those needed for running:
 368
 369 @itemize @bullet
 370 @item g++, cpp, libc6-dev, libstdc++<your-libstdc++-version-here>-dev
 371 @item libguile<your-libguile-version-here>-dev
 372 @item make, m4, flex, bison
 373 @item gettext
 374 @item groff, texinfo, bibtex2html (not in 2.2r2)
 375 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
 376 @item dpkg-dev, debhelper, fakeroot
 377 @item gs, netpbm, pnmtopng
 378 @end itemize
 379
 380 Most of these are listed on the Build-Depends line in the
 381 debian/control file.  To ensure the creation of the lilypond deb is
 382 trouble-free, we recommend that you first install the following packages
 383 before starting dpkg-buildpackage by running apt-get as root.
 384
 385 For Debian 2.2 (or 2.2r2, 2.2r3):
 386
 387 @example
 388         apt-get install task-debian-devel task-c++-dev \
 389                 python-base libguile6-dev tetex-bin tetex-dev \
 390                 tetex-extra flex bison texinfo groff gs \
 391                 netpbm pnmtopng m4 gettext
 392 @end example
 393
 394 For Debian in development ("unstable", the future 2.3 or 3.0):
 395
 396 @example
 397         apt-get install task-debian-devel task-c++-dev \
 398                 python-base libguile9-dev tetex-bin libkpathsea-dev \
 399                 tetex-extra flex bison texinfo bibtex2html groff gs \
 400                 netpbm pnmtopng m4 gettext
 401 @end example
 402
 403 And, just so that old fonts from previous versions of LilyPond won't
 404 interfere with your build, you may want to do this before the build too:
 405
 406 @example
 407         dpkg --purge lilypond lilypond1.3
 408 @end example
 409
 410
 411
 412 @section Problems
 413
 414 For help and questions use @email{help-gnu-music@@gnu.org} and
 415 @email{gnu-music-discuss@@gnu.org}.  Please consult the faq before
 416 mailing your problems.  If you find bugs, please send bug reports to
 417 @email{bug-gnu-music@@gnu.org}.
 418
 419 Bugs that are not fault of LilyPond are documented here.
 420
 421 @unnumbered NetBSD
 422
 423 @itemize @bullet
 424 @item The flex precompiled in NetBSD-1.4.2 is broken.
 425 Download flex-2.5.4a, build, install.
 426
 427 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 428 release)) does not include @file{/usr/pkg} paths.  Configure using:
 429 @example
 430
 431 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 432
 433 @end example
 434
 435 @end itemize
 436
 437 @unnumbered Solaris:
 438
 439 @itemize @bullet
 440 @item Sparc64/Solaris 2.6, GNU make-3.77
 441
 442 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
 443
 444
 445 @item Sparc64/Solaris 2.6, ld
 446
 447 Not yet resolved.
 448 @end itemize
 449
 450
 451 @unnumbered AIX
 452
 453 @itemize @bullet
 454 @item AIX 4.3 ld
 455
 456 The following is from the gcc install/SPECIFIC file.
 457 @quotation
 458    Some versions of the AIX binder (linker) can fail with a relocation
 459    overflow severe error when the -bbigtoc option is used to link
 460    GCC-produced object files into an executable that overflows the TOC.
 461    A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
 462    -BBIGTOC) is available from IBM Customer Support and from its
 463    27service.boulder.ibm.com website as PTF U455193.
 464
 465    Binutils does not support AIX 4.3 (at least through release 2.9). GNU
 466    as and GNU ld will not work properly and one should not configure GCC
 467    to use those GNU utilities. Use the native AIX tools which do
 468    interoperate with GCC.
 469 @end quotation
 470
 471 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 472 @example
 473     LDFLAGS='-Wl,-bbigtoc' ./configure
 474 @end example
 475
 476 @end itemize
 477
 478
 479 @bye
 480