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