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