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