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