INSTALL.txt

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