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