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 @end itemize
 223
 224 @section Building  LilyPond
 225
 226 to install GNU LilyPond, type:
 227 @example
 228         gunzip -c lilypond-x.y.z | tar xf -
 229         cd lilypond-x.y.z
 230         ./configure             # run with --help to see appropriate options
 231         make
 232         make install
 233         sh buildscripts/clean-fonts.sh
 234 @end example
 235
 236 If you are doing an upgrade, you should remove all @file{feta}
 237 @code{.pk} and @file{.tfm} files.  A script has been provided to do the
 238 work for you, see @file{buildscripts/clean-fonts.sh}.
 239
 240
 241 If you are not root, you should choose a @code{--prefix} argument that
 242 points into your home directory, eg.
 243 @example
 244
 245         ./configure --prefix=$HOME/usr
 246
 247 @end example
 248
 249 In this case, you have to insert the contents of
 250 @code{buildscripts/out/lilypond-login} or
 251 @code{buildscripts/out/lilypond-profile} into your start up scripts by
 252 hand.
 253
 254
 255
 256 @subsection Configuring for multiple platforms
 257
 258 If you want to build multiple versions of LilyPond with different
 259 configuration settings, you can use the @code{--enable-config=CONF}
 260 option of configure.  You should use @samp{make conf=CONF} to generate
 261 the output in @file{out-CONF}.  Example: suppose I want to build with
 262 and without profiling.  Then I'd use the following for the normal build,
 263 @example
 264
 265       ./configure --prefix=~ --enable-checking
 266       make
 267       make install
 268 @end example
 269
 270 and for the profiling version, I specify a different configuration.
 271
 272 @example
 273
 274       ./configure --prefix=~ --enable-profiling --enable-config=prof --disable-checking
 275       make conf=prof
 276       make conf=prof install
 277
 278 @end example
 279
 280
 281
 282
 283
 284 @section Emacs mode
 285
 286 An emacs mode for LilyPond is included with the source archive as
 287 @file{lilypond-mode.el} and @file{lilypond-font-lock.el}.  If you have
 288 an RPM, it is in @file{/usr/share/doc/lilypond-X/}.  You have to install
 289 it yourself.
 290
 291 Add this to your @file{~/.emacs} or @file{~/.emacs.el}:
 292 @example
 293     (load-library "lilypond-mode.el")
 294     (setq auto-mode-alist
 295       (cons '("\\.ly$" . LilyPond-mode) auto-mode-alist))
 296     (add-hook 'LilyPond-mode-hook (lambda () (turn-on-font-lock)))
 297 @end example
 298
 299 If you have the latest LilyPond-1.3.x Debian package, LilyPond-mode is
 300 automatically loaded, so you need not modify your @code{~/.emacs} file.
 301
 302 @section Compiling for distributions
 303
 304 @subsection Red Hat Linux
 305
 306 Red Hat 7.0 i386 RPMS are available from
 307 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/RedHat/}.
 308
 309 You can also compile them yourself.  A spec file is in
 310 @file{make/out/redhat.spec}. This file is distributed along with the
 311 sources.  You can make the rpm by issuing
 312 @example
 313
 314         rpm -tb lilypond-x.y.z.tar.gz
 315         rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
 316
 317 @end example
 318
 319 For running on a Red Hat system you need these packages: guile, tetex,
 320 tetex-latex, tetex-dvips, libstdc++, python, ghostscript.
 321
 322 For compilation on a Red Hat system you need these packages, in addition
 323 to the those needed for running: glibc-devel, gcc-c++, libstdc++-devel,
 324 guile-devel, flex, bison, texinfo, tetex-devel, groff,
 325 libgr-progs.
 326
 327 @subsection SuSE
 328
 329 You can also compile them yourself.  A spec file is in
 330 @file{make/out/suse.spec}. This file is distributed along with the
 331 sources.
 332
 333 You must have the following packages: guile tcsh tetex te_latex te_kpath
 334 te_mpost libpng python gpp libgpp gettext autoconf netpbm libnetpb
 335 gs_serv gs_lib gs_fonts guile
 336
 337 @subsection Mandrake
 338
 339 [TODO]
 340
 341 @subsection Debian GNU/Linux
 342
 343 A Debian package is also available.  You may install it easily by using
 344 apt-get as root:
 345
 346 @example
 347         apt-get install lilypond1.3
 348 @end example
 349
 350
 351 Debian's tex installation is a bit short on memory, you may want to
 352 increase it like this:
 353 @example
 354 --- /etc/texmf/texmf.cnf.dpkg   Sun Jan 28 14:12:14 2001
 355 +++ /etc/texmf/texmf.cnf        Fri Apr 27 11:09:35 2001
 356 @@ -384,8 +384,8 @@
 357  main_memory.context = 1500000
 358  main_memory.mpost = 1000000
 359  main_memory = 263000 % words of inimemory available; also applies to inimf&mp
 360 -extra_mem_top = 0    % extra high memory for chars, tokens, etc.
 361 -extra_mem_bot = 0    % extra low memory for boxes, glue, breakpoints, etc.
 362 +extra_mem_top = 100000    % extra high memory for chars, tokens, etc.
 363 +extra_mem_bot = 100000    % extra low memory for boxes, glue, breakpoints, etc.
 364
 365  obj_tab_size.context = 256000
 366
 367
 368 @end example
 369
 370 Alternatively, visit
 371
 372 @itemize @bullet
 373 @item @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
 374 @item @uref{http://ftp.debian.org/debian/pool/main/l/lilypond1.3/,http://ftp.debian.org/debian/pool/main/l/lilypond1.3/}
 375 for latest package uploaded to Debian unstable;
 376 @item @uref{http://people.debian.org/~foka/lilypond/,http://people.debian.org/~foka/lilypond/}
 377 for latest semi-unofficial build of LilyPond 1.3.121 for Debian 2.2r2 (potato) users.
 378 The official stable Debian 2.2r2 is stuck with the old LilyPond-1.3.24.
 379 @end itemize
 380
 381 You may contact Anthony Fok @email{foka@@debian.org} for more information.
 382
 383 The build scripts are in the subdirectory @file{debian/}; you can
 384 make the .deb by doing, for example:
 385
 386 @example
 387         $ su - root
 388         # dpkg --purge lilypond lilypond1.3
 389         # exit
 390         $ tar xzf lilypond-1.3.122.tar.gz
 391         $ cd lilypond-1.3.122
 392         $ dch -p -v 1.3.122-0.local.1 "Local build."
 393         $ debuild
 394         $ su - root
 395         # dpkg -i ../lilypond1.3_1.3.122*.deb
 396         # exit
 397         $
 398 @end example
 399
 400 For compilation on a Debian GNU/Linux system you need these packages,
 401 in addition to the those needed for running:
 402
 403 @itemize @bullet
 404 @item g++, cpp, libc6-dev, libstdc++<your-libstdc++-version-here>-dev
 405 @item libguile<your-libguile-version-here>-dev
 406 @item make, m4, flex, bison
 407 @item gettext
 408 @item groff, texinfo, bibtex2html (not in 2.2r2)
 409 @item tetex-base, tetex-bin, tetex-extra, libkpathsea-dev or tetex-dev
 410 @item dpkg-dev, debhelper, fakeroot
 411 @item gs, netpbm, pnmtopng
 412 @end itemize
 413
 414 Most of these are listed on the Build-Depends line in the
 415 debian/control file.  To ensure the creation of the lilypond deb is
 416 trouble-free, we recommend that you first install the following packages
 417 before starting dpkg-buildpackage by running apt-get as root.
 418
 419 For Debian 2.2 (or 2.2r2, 2.2r3):
 420
 421 @example
 422         apt-get install task-debian-devel task-c++-dev \
 423                 python-base libguile6-dev tetex-bin tetex-dev \
 424                 tetex-extra flex bison texinfo groff gs \
 425                 netpbm pnmtopng m4 gettext
 426 @end example
 427
 428 For Debian in development ("unstable", the future 2.3 or 3.0):
 429
 430 @example
 431         apt-get install task-debian-devel task-c++-dev \
 432                 python-base libguile9-dev tetex-bin libkpathsea-dev \
 433                 tetex-extra flex bison texinfo bibtex2html groff gs \
 434                 netpbm pnmtopng m4 gettext
 435 @end example
 436
 437 And, just so that old fonts from previous versions of LilyPond won't
 438 interfere with your build, you may want to do this before the build too:
 439
 440 @example
 441         dpkg --purge lilypond lilypond1.3
 442 @end example
 443
 444
 445
 446 @section Problems
 447
 448 For help and questions use @email{help-gnu-music@@gnu.org} and
 449 @email{gnu-music-discuss@@gnu.org}.  Please consult the faq before
 450 mailing your problems.  If you find bugs, please send bug reports to
 451 @email{bug-gnu-music@@gnu.org}.
 452
 453 Bugs that are not fault of LilyPond are documented here.
 454
 455 @unnumberedsubsec NetBSD
 456
 457 @itemize @bullet
 458 @item The flex precompiled in NetBSD-1.4.2 is broken.
 459 Download flex-2.5.4a, build, install.
 460
 461 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 462 release)) does not include @file{/usr/pkg} paths.  Configure using:
 463 @example
 464
 465 CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 466
 467 @end example
 468
 469 @end itemize
 470
 471 @unnumberedsubsec  Solaris:
 472
 473 @itemize @bullet
 474 @item Sparc64/Solaris 2.6, GNU make-3.77
 475
 476 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
 477
 478 @item Sparc64/Solaris 2.6, ld
 479
 480 Not yet resolved.
 481 @end itemize
 482
 483
 484 @unnumberedsubsec   AIX
 485
 486 @itemize @bullet
 487 @item AIX 4.3 ld
 488
 489 The following is from the gcc install/SPECIFIC file.
 490 @quotation
 491    Some versions of the AIX binder (linker) can fail with a relocation
 492    overflow severe error when the -bbigtoc option is used to link
 493    GCC-produced object files into an executable that overflows the TOC.
 494    A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
 495    -BBIGTOC) is available from IBM Customer Support and from its
 496    27service.boulder.ibm.com website as PTF U455193.
 497
 498    Binutils does not support AIX 4.3 (at least through release 2.9). GNU
 499    as and GNU ld will not work properly and one should not configure GCC
 500    to use those GNU utilities. Use the native AIX tools which do
 501    interoperate with GCC.
 502 @end quotation
 503
 504 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 505 @example
 506     LDFLAGS='-Wl,-bbigtoc' ./configure
 507 @end example
 508
 509 @end itemize
 510
 511
 512 @bye
 513