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