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