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