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