Documentation/topdocs/INSTALL.texi

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