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