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 @chapter INSTALL - compiling and installing GNU LilyPond
   9
  10
  11 @section Abstract
  12
  13 This document explains what you need to install LilyPond, and what you
  14 should do.  If you are going to compile and install LilyPond often,
  15 e.g. when doing development, you might want to check out the
  16 @file{buildscripts/set-lily.sh} script.  It sets some environment
  17 variables and symlinks, which comes in handy when you have to compile
  18 LilyPond more often.
  19
  20 @section Obtaining
  21
  22 You can get the latest version of LilyPond at
  23 @uref{ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/,
  24 ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/}.
  25
  26
  27 @emph{If you upgrade by patching do remember to rerun autoconf after
  28 applying the patch}.
  29
  30 If you do not want to download the entire archive for each version, the
  31 safest method for upgrading is to use @file{xdelta}, see
  32 @uref{ftp://ftp.xcf.berkeley.edu/pub/xdelta/}.
  33
  34 The following command produces @file{lilypond-1.1.55.tar.gz} from
  35 @file{lilypond-1.1.54} identical (up to compression dates) to the .55 on
  36 the FTP site.
  37 @example
  38   xdelta patch lilypond-1.1.54-1.1.55.xd lilypond-1.1.54.tar.gz
  39 @end example
  40
  41 @section Prerequisites
  42
  43 For compilation you need:
  44
  45 @itemize @bullet
  46 @item A GNU system: GNU LilyPond is known to run on these GNU systems: Linux
  47     (PPC, intel), FreeBSD, AIX, NeXTStep, IRIX, Digital Unix and
  48 Solaris.
  49
  50 @item Lots of disk space: LilyPond takes between 30 and 100 mb to
  51 compile if you use debugging information.  If you are short on
  52 disk-space run configure with @code{--disable-debugging}.
  53
  54 @item
  55 Although we recommend to use Unix, LilyPond is known to run on Windows
  56 NT/95/98 as well.  See Section Windows NT/95,es.
  57
  58 @item  EGCS 1.1 or newer. Check out @uref{ftp://ftp.gnu.org/gnu/gcc/}.
  59
  60 @item  Python 1.5,
  61 Check out
  62 @uref{ftp://ftp.python.org} or @uref{ftp://ftp.cwi.nl/pub/python}.
  63
  64 @item  GUILE 1.3.4 or newer,  check out
  65 @uref{http://www.gnu.org/software/guile/guile.html,http://www.gnu.org/software/guile/guile.html}.
  66 Version 1.4 is recommended for better performance.
  67
  68 @item GNU Make.
  69 Check out
  70 @uref{ftp://ftp.gnu.org/gnu/make/,ftp://ftp.gnu.org/gnu/make/}.
  71
  72 @item Flex (version 2.5.4 or newer).
  73 Check out @uref{ftp://ftp.gnu.org/gnu/flex/,ftp://ftp.gnu.org/gnu/flex/}.
  74
  75 @item Bison (version 1.25 or newer).
  76 Check out @uref{ftp://ftp.gnu.org/gnu/bison/,ftp://ftp.gnu.org/gnu/bison/}.
  77
  78 @item Texinfo (version 4.0 or newer).
  79 Check out @uref{ftp://ftp.gnu.org/gnu/texinfo/,ftp://ftp.gnu.org/gnu/texinfo/}.
  80 Most documentation is in texinfo.
  81
  82 @item The geometry package for LaTeX is needed to use ly2dvi.
  83 Available at
  84 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry}
  85 or at mirror site @uref{ftp://ftp.dante.de,ftp://ftp.dante.de}
  86
  87 @item MetaPost, needed for generating PostScript fonts. Please
  88 note that tetex-0.4pl8 (included with Redhat 5.x) does not include
  89 @file{mfplain.mp}, which is needed for producing the scalable font
  90 files.
  91
  92 If you do not want to use PostScript output, edit @file{mf/GNUmakefile}.
  93
  94 @item kpathsea, a library for searching (TeX) files.  @code{kpathsea} is
  95 usually included with your installation of TeX.
  96
  97
  98 @end itemize
  99
 100 @section Running
 101
 102 GNU LilyPond does use a lot of resources. For operation you need the
 103 following software
 104
 105 @itemize @bullet
 106 @item TeX
 107 @item A PostScript printer and/or viewer (such as Ghostscript) is strongly
 108     recommended.  Xdvi will show all embedded PostScript too if you have
 109     Ghostscript installed.
 110 @item  GUILE 1.3.4, check out @uref{http://www.gnu.org/programs/guile.html,http://www.gnu.org/software/guile/}
 111 @end itemize
 112
 113 For running LilyPond successfully you have to help TeX and MetaFont
 114 find various files.  The recommended way of doing so is adjusting the
 115 environment variables in the start-up scripts of your shell.  An
 116 example is given here for the Bourne shell:
 117 @example
 118 export MFINPUTS="/usr/local/share/lilypond/mf:"
 119 export TEXINPUTS="/usr/local/share/lilypond/tex:/usr/local/share/lilypond/ps:"
 120
 121 @end example
 122
 123 The empty path component
 124 represents TeX and MetaFont's default search paths.  Scripts with
 125 the proper paths for the bourne and C-shell respectively are generated in
 126 @file{buildscripts/out/lilypond-profile} and
 127 @file{buildscripts/out/lilypond-login} during compilation.
 128
 129 LilyPond is a hiddeously big, slow and bloated program.  A fast CPU
 130 and plenty of RAM is recommended for comfortable use.
 131
 132 @section Website
 133
 134 The website is the most convenient form to use for reading the
 135 documentation on-line documentation. It is made by entering @example
 136
 137   make htmldoc
 138
 139 @end example
 140 This does require a  functioning  LilyPond. The binary doesn't have to
 141 be installed.
 142
 143 If you want to auto-generate Lily's website, you'll need some additional
 144 conversion tools.
 145
 146 @itemize @bullet
 147 @item xpmtoppm (from the Portable Bitmap Utilities) (For RedHat Linux
 148              users: it is included within the package libgr-progs).
 149         the original is at
 150 @uref{ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz,ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz}
 151
 152 @item pnmtopng, which is also in libgr-progs for RedHat. The original is
 153 at
 154 @uref{ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz,ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz}.i
 155
 156 The version of @file{pnmtopng} that is distributed with RedHat 5.1 and
 157 5.2 contains a bug: pnmtopng is dynamically linked to the wrong
 158 version of libpng, which results in cropped images.  Recompile it from
 159 source, and make sure that the pnmtopng binary is linked statically to
 160 the libpng that is included in libgr.  RedHat 6.0 does not have this
 161 problem.
 162
 163 @example
 164  tar xzf libgr-2.0.13.tar.gz
 165       make
 166       cd png
 167       rm libpng.so*
 168       make pnmtopng
 169
 170 @end example
 171
 172 You can then install the new pnmtopng into @file{/usr/local/bin/}
 173
 174 @item @uref{http://pertsserver.cs.uiuc.edu/~hull/bib2html,Bib2html}.
 175     Which, in turn depends on man2html for proper installation.
 176 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}.
 177
 178 The website will build without this utility, but you will not see our
 179 hypertextified bibliography.
 180
 181 @item @uref{http://www.zib.de/Visual/software/doc++/index.html,DOC++}
 182     A documentation system for C++ sources, which is used for the
 183     LilyPond sources.
 184 @end itemize
 185
 186 @section Configuring and compiling
 187
 188 to install GNU LilyPond, simply type:
 189 @example
 190
 191         gunzip -c lilypond-x.y.z | tar xf -
 192         cd lilypond-x.y.z
 193         ./configure             # fill in your standard prefix with --prefix
 194         make
 195         make install
 196
 197 @end example
 198
 199 This will install a number of files, something close to:
 200
 201 @example
 202         /usr/local/man/man1/mi2mu.1
 203         /usr/local/man/man1/convert-mudela.1
 204         /usr/local/man/man1/mudela-book.1
 205         /usr/local/man/man1/lilypond.1
 206         /usr/local/bin/lilypond
 207         /usr/local/bin/mi2mu
 208         /usr/local/bin/convert-mudela
 209         /usr/local/bin/mudela-book
 210         /usr/local/bin/abc2ly
 211         /usr/local/share/lilypond/*
 212         /usr/local/share/locale/@{it,nl@}/LC_MESSAGES/lilypond.mo
 213 @end example
 214
 215
 216 The above assumes that you are root and have the GNU development
 217 tools, and your make is GNU make.  If this is not the case, you can
 218 adjust your environment variables to your taste:
 219
 220 @example
 221
 222         export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR"
 223         ./configure
 224
 225 @end example
 226
 227 @code{CPPFLAGS} are the preprocessor flags.
 228
 229 The configure script is Cygnus configure, and it will accept
 230 @code{--help}. If you are not root, you will probably have to make it
 231 with a different @code{--prefix} option.  Our favourite location is
 232
 233 @example
 234
 235         ./configure --prefix=$HOME/usr
 236
 237 @end example
 238
 239 In this case, you will have to set up MFINPUTS, and TEXINPUTS accordingly.
 240
 241 Since GNU LilyPond currently is beta, you are advised to also use
 242
 243 @example
 244
 245         --enable-debugging
 246         --enable-checking
 247
 248 @end example
 249
 250 Options to configure include:
 251
 252 @table @samp
 253 @item @code{--enable-printing}
 254     Enable debugging print routines (lilypond @code{-D} option)
 255 @item @code{--enable-optimise}
 256     Set maximum optimisation: compile with @code{-O2}.  This can be
 257 unreliable on some compiler/platform combinations (eg, DEC Alpha and PPC)
 258 @item @code{--enable-profiling}
 259     Compile with support for profiling.
 260 @item @code{--enable-config}
 261     Output to a different configuration file.  Needed for multi-platform
 262     builds
 263 @end table
 264
 265 All options are documented in the @file{configure} help
 266 The option @code{--enable-optimise} is recommended for Real Life usage.
 267
 268 If you do
 269
 270 @example
 271
 272         make all
 273
 274 @end example
 275
 276 everything will be compiled, but nothing will be installed.  The
 277 resulting binaries can be found in the subdirectories @file{out/} (which
 278 contain all files generated during compilation).
 279
 280 @section Configuring for multiple platforms
 281
 282 If you want to compile LilyPond with different configuration settings,
 283 then, you can use the @code{--enable-config} option.  Example: suppose I
 284 want to build with and   without profiling.  Then I'd use the
 285 following for the normal build,
 286
 287 @example
 288
 289       ./configure --prefix=~ --disable-optimise --enable-checking
 290       make
 291       make install
 292
 293 @end example
 294
 295 and for the profiling version, I specify a different configuration.
 296
 297 @example
 298
 299       ./configure --prefix=~ --enable-profiling --enable-config=optprof --enable-optimise --disable-checking
 300       make config=optprof
 301       make config=optprof install
 302
 303 @end example
 304
 305
 306 @section Installing
 307
 308 if you have done a successful @code{make}, then a simple
 309
 310 @example
 311
 312         make install
 313
 314 @end example
 315
 316 should do the trick.
 317
 318 If you are doing an upgrade, please remember to remove obsolete
 319 @file{.pk} and @file{.tfm} files of the fonts.  A script has been
 320 provided to do the work for you, see @file{bin/clean-fonts.sh}.
 321
 322
 323 @section Redhat linux
 324
 325 RedHat Linux users can compile an RPM. A spec file is in
 326 @file{make/out/lilypond.spec}, it is distributed along with the
 327 sources.
 328
 329 You can make the rpm by issuing
 330 @example
 331
 332         rpm -tb lilypond-x.y.z.tar.gz
 333         rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
 334
 335 @end example
 336
 337 Precompiled i386 RedHat RPMS are available from
 338 @uref{ftp://freshmeat.net/pub/rpms/lilypond/,ftp://freshmeat.net/pub/rpms/lilypond/} and
 339 @uref{http://linux.umbc.edu/software/lilypond/rpms/,http://linux.umbc.edu/software/lilypond/rpms/}.
 340
 341 For compilation on a RedHat system you need these packages,
 342 in addition to the those needed for running:
 343 @itemize @bullet
 344 @item glibc-devel
 345 @item libstdc++-devel
 346 @item guile-devel
 347 @item flex
 348 @item bison
 349 @item texinfo
 350 @end itemize
 351
 352 @section Debian GNU/linux
 353
 354 A Debian package is also available; see
 355 @uref{http://packages.debian.org/lilypond,http://packages.debian.org/lilypond}
 356 or contact Anthony Fok @email{foka@@debian.org} for more information.
 357 The build scripts are in the subdirectory @file{debian/}.
 358
 359 @section Windows NT/95
 360
 361 Separate instructions on building for W32 are available; See the files
 362 in @file{Documentation/ntweb/}, included with the sources.
 363
 364 @section Problems
 365
 366 For help and questions use @email{help-gnu-music@@gnu.org} and
 367 @email{gnu-music-discuss@@gnu.org}.  Please consult the faq before
 368 mailing your problems.
 369
 370 If you find bugs, please send bug reports to
 371 @email{bug-gnu-music@@gnu.org}.
 372
 373 Known bugs that are LilyPond's fault are listed in @file{TODO}, or
 374 demonstrated in @file{input/bugs/}.
 375
 376 Known bugs that are not LilyPond's fault are documented here.
 377
 378
 379 @unnumbered LinuxPPC Bugs:
 380
 381 @itemize @bullet
 382 @item egcs-1.1.2-12c (stock LinuxPPC R5) has a serious bug, upgrade to
 383 fixed in egcs-1.1.2-12f or gcc-2.95-0a, @uref{ftp://dev.linuxppc.org/users/fsirl/R5/RPMS/ppc/}
 384
 385 @item egcs-1.0.2 (LinuxPPC R4):
 386 all compiling with @code{-O2} is suspect, in particular guile-1.3, and
 387 Lily herself will break.
 388 @end itemize
 389
 390
 391
 392 @unnumbered Linux-i386
 393
 394 @itemize @bullet
 395 @item SuSE6.2 and similar platforms (glibc 2.1, libstdc++ 2.9.0)
 396
 397 Lily will crash during parsing (which suggests a C++ library
 398 incompatibility).  Precise cause, precise platform description or
 399 solution are not known.
 400
 401 Note that this only happens on some computers with the said platform.
 402
 403 @item libg++ 2.7
 404
 405 LilyPond occasionally crashes while parsing the initialisation files.
 406 This is a very obscure bug, and usually entering the commandline
 407 differently "fixes" it.
 408
 409 @example
 410         lilypond input.ly
 411 @end  example
 412
 413 and
 414 @example
 415         lilypond -I. ./input.ly
 416 @end example
 417 makes a difference
 418
 419 Typical stacktrace:
 420 @example
 421         SIGSEGV
 422         __libc_malloc (bytes=16384)
 423         ?? ()
 424         yyFlexLexer::yy_create_buffer ()
 425         Includable_lexer::new_input (this=0x8209a00, s=@{strh_ = @{
 426 @end example
 427
 428 This behaviour has been observed with machines that have old libg++
 429 versions (LinuxPPC feb '98, RedHat 4.x).
 430 @end itemize
 431
 432
 433
 434
 435 @unnumbered Solaris:
 436
 437 @itemize @bullet
 438 @item Sparc64/Solaris 2.6, GNU make-3.77
 439
 440 GNU make-3.77 is buggy on this platform, upgrade to 3.78.1 or newer.
 441
 442
 443 @item Sparc64/Solaris 2.6, ld
 444
 445 Not yet resolved.
 446 @end itemize
 447
 448
 449 @unnumbered AIX
 450
 451 @itemize @bullet
 452 @item AIX 4.3 ld
 453
 454 The following is from the gcc install/SPECIFIC file.
 455 @quotation
 456    Some versions of the AIX binder (linker) can fail with a relocation
 457    overflow severe error when the -bbigtoc option is used to link
 458    GCC-produced object files into an executable that overflows the TOC. A
 459    fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
 460    -BBIGTOC) is available from IBM Customer Support and from its
 461    27service.boulder.ibm.com website as PTF U455193.
 462
 463    Binutils does not support AIX 4.3 (at least through release 2.9). GNU
 464    as and GNU ld will not work properly and one should not configure GCC
 465    to use those GNU utilities. Use the native AIX tools which do
 466    interoperate with GCC.
 467 @end quotation
 468
 469 add -Wl,-bbigtoc to USER_LDFLAGS, ie:
 470 @example
 471     LDFLAGS='-Wl,-bbigtoc' ./configure
 472 @end example
 473
 474 @end itemize
 475
 476
 477 @bye
 478