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