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