INSTALL.txt

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