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