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