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