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