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 @subsection LinuxPPC
 355
 356
 357 Some LinuxPPC RPMS should available from
 358 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/binaries/}.
 359
 360 A LinuxPPC RPM can be made using the @file{lilypond.redhat.spec} file.
 361
 362 @subsection SuSE
 363
 364 Some SUSE RPMS should available from
 365 @uref{ftp://ftp.lilypond.org/pub/LilyPond/binaries/SuSE}.
 366
 367 You can also compile a RPM for SUSE yourself.  A spec file is in
 368 @file{make/out/lilypond.suse.spec}, see the instructions for building
 369 the Red Hat RPM.
 370
 371 You must have the following packages: guile tcsh tetex te_latex te_kpath
 372 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
 373 gs_serv gs_lib gs_fonts guile
 374
 375 @subsection Slackware
 376
 377 No precompiled packages for Slackware are available.
 378
 379 Problems have been reported with Slackware 7.0; apparently, it ships
 380 with a faulty compiler. Do not compile LilyPond with -O2 on this
 381 platform.
 382
 383 @subsection Mandrake
 384
 385 Some binaries are available at rpmfind.net. Refer to
 386 @uref{http://rpmfind.net/linux/mandrake/cooker/contrib/RPMS/}.
 387
 388 You can also compile a RPM for Mandrake yourself.  A spec file is in
 389 @file{make/out/lilypond.mandrake.spec}, see the instructions for building
 390 the Red Hat RPM.
 391
 392 @subsection Debian GNU/Linux
 393
 394 A Debian package is also available.  You may install it easily by running
 395 @command{apt-get} as root:
 396 @example
 397
 398         apt-get install lilypond lilypond-doc
 399 @end example
 400
 401 You can also compile the .deb for Debian yourself, do:
 402 @example
 403
 404         apt-get -b source lilypond
 405 @end example
 406
 407 If you're real impatient, you may even do:
 408 @example
 409
 410         cd lilypond-x.y.z   # a previous version
 411         uscan               # download and build latest directly from upstream
 412 @end example
 413
 414
 415 Debian's @TeX{} installation is a bit short on memory, you may want to
 416 increase it like this:
 417 @example
 418 --- /etc/texmf/texmf.cnf.dpkg   Sun Jan 28 14:12:14 2001
 419 +++ /etc/texmf/texmf.cnf        Fri Apr 27 11:09:35 2001
 420 @@ -384,8 +384,8 @@
 421  main_memory.context = 1500000
 422  main_memory.mpost = 1000000
 423  main_memory = 263000 % words of inimemory available; also applies to inimf&mp
 424 -extra_mem_top = 0    % extra high memory for chars, tokens, etc.
 425 -extra_mem_bot = 0    % extra low memory for boxes, glue, breakpoints, etc.
 426 +extra_mem_top = 100000    % extra high memory for chars, tokens, etc.
 427 +extra_mem_bot = 100000    % extra low memory for boxes, glue, breakpoints, etc.
 428
 429  obj_tab_size.context = 256000
 430
 431 @end example
 432
 433 You could also export @env{extra_mem_top} and @env{extra_mem_bot} as
 434 environment variables if you do not want to or cannot modify
 435 @file{/etc/texmf/texmf.cnf}.
 436
 437 Alternatively, visit
 438
 439 @itemize @bullet
 440 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
 441 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
 442 for latest semi-unofficial build of LilyPond 1.4.2 for Debian 2.2 (potato) users.
 443 The official stable Debian 2.2 is stuck with the old LilyPond-1.3.24.
 444 Since LilyPond-1.4 has been released, the older lilypond1.3 Debian
 445 package is now obsolete.
 446 @end itemize
 447
 448 Please contact Anthony Fok @email{lilypond@@packages.debian.org} for more
 449 information.
 450
 451 The build scripts are in the subdirectory @file{debian/}; you can
 452 make the .deb by doing, for example:
 453
 454 @example
 455         $ su - root
 456         # dpkg --purge lilypond lilypond1.3
 457         # exit
 458         $ tar xzf lilypond-1.4.3.tar.gz
 459         $ cd lilypond-1.4.3
 460         $ dch -p -v 1.4.3-0.local.1 "Local build."
 461         $ debuild -B
 462         $ su - root
 463         # dpkg -i ../lilypond_1.4.3*.deb
 464         # exit
 465         $
 466 @end example
 467
 468 Use command @command{debuild} instead of @command{debuild -B} if you have
 469 a very fast machine and want to build the HTML, PS and DVI documentation
 470 too.
 471
 472 For compilation on a Debian GNU/Linux system you need these packages,
 473 in addition to the those needed for running:
 474
 475 @itemize @bullet
 476 @item g++, cpp, libc6-dev, libstdc++<@var{your-libstdc++-version-here}>-dev
 477 @item libguile<@var{your-libguile-version-here}>-dev
 478 @item make, m4, flex, bison
 479 @item gettext
 480 @item groff, texinfo
 481 @item bibtex2html (not in Debian 2.2)
 482 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
 483 @item dpkg-dev, debhelper, fakeroot
 484 @item gs, netpbm
 485 @item pnmtopng (only in Debian 2.2; pnmtopng has been merged with netpbm
 486   in Debian testing/unstable.)
 487 @end itemize
 488
 489 Most of these are listed on the @samp{Build-Depends} line in the
 490 @file{debian/control} file.  To ensure the creation of the lilypond deb is
 491 trouble-free, we recommend that you first install the following packages
 492 by running \@command{apt-get} as root before building the package:
 493
 494 For Debian 2.2:
 495
 496 @example
 497         apt-get install task-debian-devel task-c++-dev \
 498                 python-base libguile6-dev tetex-bin tetex-dev \
 499                 tetex-extra flex bison texinfo groff gs \
 500                 netpbm pnmtopng m4 gettext
 501 @end example
 502
 503 For Debian in development ("unstable", the future 2.3 or 3.0):
 504
 505 @example
 506         apt-get install binutils cpp gcc libc6-dev \
 507                 g++ libstdc++2.10-dev \
 508                 python-base libguile-dev tetex-bin libkpathsea-dev \
 509                 tetex-extra flex bison texinfo bibtex2html groff gs \
 510                 netpbm m4 gettext
 511 @end example
 512
 513 And, just so that old fonts from previous versions of LilyPond won't
 514 interfere with your build, you may want to do this before the build too:
 515
 516 @example
 517         dpkg --purge lilypond lilypond1.3
 518 @end example
 519
 520
 521
 522 @section Problems
 523
 524 For help and questions use @email{lilypond-user@@gnu.org}.  Please
 525 consult the FAQ before mailing your problems.  If you find bugs, please
 526 send bug reports to @email{bug-lilypond@@gnu.org}.
 527
 528 Bugs that are not fault of LilyPond are documented here.
 529
 530 @unnumberedsubsec FLex-2.5.4a and gcc-3.0
 531
 532 Flex 2.5.4a does not produce g++-3.0 compliant C++ code.  To compile
 533 LilyPond with gcc-3.0 you may do:
 534
 535 @example
 536         CC=gcc-3.0 CXX=g++-3.0 ./configure --enable-config=gcc-3.0
 537         make conf=gcc-3.0 -C lily out-gcc-3.0/lexer.cc
 538         patch -p1 < lexer-gcc-3.0.patch
 539         make conf=gcc-3.0 -C lily
 540 @end example
 541
 542 Note that this is fixed in Debian/unstable for flex >= 2.5.4a-13.
 543
 544 @unnumberedsubsec NetBSD
 545
 546 @itemize @bullet
 547 @item The flex precompiled in NetBSD-1.4.2 is broken.
 548 Download flex-2.5.4a, build, install.
 549
 550 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 551 release)) does not include @file{/usr/pkg} paths.  Configure using:
 552 @example
 553
 554 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 555
 556 @end example
 557
 558 @end itemize
 559
 560 @unnumberedsubsec  Solaris:
 561
 562 @itemize @bullet
 563 @item Sparc64/Solaris 2.6, GNU make-3.77
 564
 565 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
 566
 567 @item Sparc64/Solaris 2.6, ld
 568
 569 Not yet resolved.
 570 @end itemize
 571
 572
 573 @unnumberedsubsec   AIX
 574
 575 @itemize @bullet
 576 @item AIX 4.3 ld
 577
 578 The following is from the gcc install/SPECIFIC file.
 579 @quotation
 580    Some versions of the AIX binder (linker) can fail with a relocation
 581    overflow severe error when the -bbigtoc option is used to link
 582    GCC-produced object files into an executable that overflows the TOC.
 583    A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
 584    -BBIGTOC) is available from IBM Customer Support and from its
 585    27service.boulder.ibm.com website as PTF U455193.
 586
 587    Binutils does not support AIX 4.3 (at least through release 2.9). GNU
 588    as and GNU ld will not work properly and one should not configure GCC
 589    to use those GNU utilities. Use the native AIX tools which do
 590    interoperate with GCC.
 591 @end quotation
 592
 593 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 594 @example
 595     LDFLAGS='-Wl,-bbigtoc' ./configure
 596 @end example
 597
 598 @end itemize
 599
 600
 601 @bye
 602