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