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-latex, 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,
 323 libgr-progs.
 324
 325 @subsection SuSE
 326
 327 You can also compile them yourself.  A spec file is in
 328 @file{make/out/suse.spec}. This file is distributed along with the
 329 sources.
 330
 331 You must have the following packages: guile tcsh tetex te_latex te_kpath
 332 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
 333 gs_serv gs_lib gs_fonts guile
 334
 335 @subsection Mandrake
 336
 337 [TODO]
 338
 339 @subsection Debian GNU/Linux
 340
 341 A Debian package is also available.  You may install it easily by using
 342 apt-get as root:
 343
 344 @example
 345         apt-get install lilypond1.3
 346 @end example
 347
 348 Alternatively, visit
 349
 350 @itemize @bullet
 351 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
 352 @item @uref{http://ftp.debian.org/debian/pool/main/l/lilypond1.3/,http://ftp.debian.org/debian/pool/main/l/lilypond1.3/}
 353 for latest package uploaded to Debian unstable;
 354 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
 355 for latest semi-unofficial build of LilyPond 1.3.121 for Debian 2.2r2 (potato) users.
 356 The official stable Debian 2.2r2 is stuck with the old LilyPond-1.3.24.
 357 @end itemize
 358
 359 You may contact Anthony Fok @email{foka@@debian.org} for more information.
 360
 361 The build scripts are in the subdirectory @file{debian/}; you can
 362 make the .deb by doing, for example:
 363
 364 @example
 365         $ su - root
 366         # dpkg --purge lilypond lilypond1.3
 367         # exit
 368         $ tar xzf lilypond-1.3.122.tar.gz
 369         $ cd lilypond-1.3.122
 370         $ dch -p -v 1.3.122-0.local.1 "Local build."
 371         $ debuild
 372         $ su - root
 373         # dpkg -i ../lilypond1.3_1.3.122*.deb
 374         # exit
 375         $
 376 @end example
 377
 378 For compilation on a Debian GNU/Linux system you need these packages,
 379 in addition to the those needed for running:
 380
 381 @itemize @bullet
 382 @item g++, cpp, libc6-dev, libstdc++<your-libstdc++-version-here>-dev
 383 @item libguile<your-libguile-version-here>-dev
 384 @item make, m4, flex, bison
 385 @item gettext
 386 @item groff, texinfo, bibtex2html (not in 2.2r2)
 387 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
 388 @item dpkg-dev, debhelper, fakeroot
 389 @item gs, netpbm, pnmtopng
 390 @end itemize
 391
 392 Most of these are listed on the Build-Depends line in the
 393 debian/control file.  To ensure the creation of the lilypond deb is
 394 trouble-free, we recommend that you first install the following packages
 395 before starting dpkg-buildpackage by running apt-get as root.
 396
 397 For Debian 2.2 (or 2.2r2, 2.2r3):
 398
 399 @example
 400         apt-get install task-debian-devel task-c++-dev \
 401                 python-base libguile6-dev tetex-bin tetex-dev \
 402                 tetex-extra flex bison texinfo groff gs \
 403                 netpbm pnmtopng m4 gettext
 404 @end example
 405
 406 For Debian in development ("unstable", the future 2.3 or 3.0):
 407
 408 @example
 409         apt-get install task-debian-devel task-c++-dev \
 410                 python-base libguile9-dev tetex-bin libkpathsea-dev \
 411                 tetex-extra flex bison texinfo bibtex2html groff gs \
 412                 netpbm pnmtopng m4 gettext
 413 @end example
 414
 415 And, just so that old fonts from previous versions of LilyPond won't
 416 interfere with your build, you may want to do this before the build too:
 417
 418 @example
 419         dpkg --purge lilypond lilypond1.3
 420 @end example
 421
 422
 423
 424 @section Problems
 425
 426 For help and questions use @email{help-gnu-music@@gnu.org} and
 427 @email{gnu-music-discuss@@gnu.org}.  Please consult the faq before
 428 mailing your problems.  If you find bugs, please send bug reports to
 429 @email{bug-gnu-music@@gnu.org}.
 430
 431 Bugs that are not fault of LilyPond are documented here.
 432
 433 @unnumberedsubsec NetBSD
 434
 435 @itemize @bullet
 436 @item The flex precompiled in NetBSD-1.4.2 is broken.
 437 Download flex-2.5.4a, build, install.
 438
 439 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 440 release)) does not include @file{/usr/pkg} paths.  Configure using:
 441 @example
 442
 443 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 444
 445 @end example
 446
 447 @end itemize
 448
 449 @unnumberedsubsec  Solaris:
 450
 451 @itemize @bullet
 452 @item Sparc64/Solaris 2.6, GNU make-3.77
 453
 454 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
 455
 456 @item Sparc64/Solaris 2.6, ld
 457
 458 Not yet resolved.
 459 @end itemize
 460
 461
 462 @unnumberedsubsec   AIX
 463
 464 @itemize @bullet
 465 @item AIX 4.3 ld
 466
 467 The following is from the gcc install/SPECIFIC file.
 468 @quotation
 469    Some versions of the AIX binder (linker) can fail with a relocation
 470    overflow severe error when the -bbigtoc option is used to link
 471    GCC-produced object files into an executable that overflows the TOC.
 472    A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
 473    -BBIGTOC) is available from IBM Customer Support and from its
 474    27service.boulder.ibm.com website as PTF U455193.
 475
 476    Binutils does not support AIX 4.3 (at least through release 2.9). GNU
 477    as and GNU ld will not work properly and one should not configure GCC
 478    to use those GNU utilities. Use the native AIX tools which do
 479    interoperate with GCC.
 480 @end quotation
 481
 482 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 483 @example
 484     LDFLAGS='-Wl,-bbigtoc' ./configure
 485 @end example
 486
 487 @end itemize
 488
 489
 490 @bye
 491