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