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