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