INSTALL.txt

   1
   2
   3 INSTALL - compiling and installing GNU LilyPond
   4 ***********************************************
   5
   6 Abstract
   7 ========
   8
   9    TODO: document xdeltas
  10
  11    This document explains what you need to install LilyPond, and what
  12 you should do.  If you are going to compile and install LilyPond often,
  13 e.g. when doing development, you might want to check out the
  14 `buildscripts/set-lily.sh' script.  It sets some environment variables
  15 and symlinks, which comes in handly when you have to compile LilyPond
  16 more often.
  17
  18 Obtaining
  19 =========
  20
  21    You can get the latest version of LilyPond at
  22 ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/
  23 (ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/).  Refer to the links document
  24 for mirror sites.
  25
  26    _If you upgrade by patching do remember to rerun autoconf after
  27 applying the patch_.
  28
  29 Prerequisites
  30 =============
  31
  32    For compilation you need:
  33
  34    * A GNU system: GNU LilyPond is known to run on these GNU systems:
  35      Linux     (PPC, intel), FreeBSD, AIX, NeXTStep, IRIX, Digital Unix
  36      and Solaris.
  37
  38    * Lots of disk space: LilyPond takes between 30 and 100 mb to
  39      compile if you use debugging information.  If you are short on
  40      disk-space run configure with `--disable-debugging'.
  41
  42      Although we recommend to use Unix, LilyPond is known to run on
  43      Windows NT/95/98 as well.  See Section Windows NT/95,es.
  44
  45    * EGCS 1.1 or newer. Check out ftp://ftp.gnu.org/pub/gcc/
  46      (ftp://ftp.gnu.org/pub/gcc/)
  47
  48    * Python 1.5, Check out ftp://ftp.python.org (ftp://ftp.python.org)
  49      or ftp://ftp.cwi.nl/pub/python (ftp://ftp.cwi.nl/pub/python).
  50
  51    * GUILE 1.3,  check out http://www.gnu.org/software/guile/guile.html
  52      (http://www.gnu.org/software/guile/guile.html).
  53
  54    * GNU make.  Check out ftp://ftp.gnu.org/make/
  55      (ftp://ftp.gnu.org/make/).
  56
  57    * Flex (version 2.5.4 or newer).  Check out ftp://ftp.gnu.org/flex/
  58      (ftp://ftp.gnu.org/flex/).
  59
  60    * Bison (version 1.25 or newer).  Check out ftp://ftp.gnu.org/bison/
  61      (ftp://ftp.gnu.org/bison/).
  62
  63    * Texinfo. Check out ftp://ftp.gnu.org/pub/texinfo/
  64      (ftp://ftp.gnu.org/pub/texinfo/).  Most documentation is in
  65      texinfo.
  66
  67    * The geometry package for LaTeX is needed to use ly2dvi.  Available
  68      at
  69      ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry
  70      (ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry)
  71      or at mirror site ftp://ftp.dante.de (ftp://ftp.dante.de)
  72
  73    * MetaPost, if you want to use direct PostScript output. Please note
  74      that  tetex-0.4pl8 (included with Redhat 5.x) does not include
  75      `mfplain.mp', which is needed  for producing the scaleable font
  76      files.
  77
  78
  79 Running
  80 =======
  81
  82    GNU LilyPond does use a lot of resources. For operation you need the
  83 following software
  84
  85    * TeX
  86
  87    * A PostScript printer and/or viewer (such as Ghostscript) is
  88      strongly     recommended.  Xdvi will show all embedded PostScript
  89      too if you have     Ghostscript installed.
  90
  91    * GUILE 1.3, check out http://www.gnu.org/programs/guile.html
  92      (http://www.gnu.org/programs/guile.html)
  93
  94    For running LilyPond successfully you have to help TeX and MetaFont
  95 find various files.  The recommended way of doing so is adjusting the
  96 environment variables in the start-up scripts of your shell.  An
  97 example is given here for the Bourne shell:
  98      export MFINPUTS="/usr/local/share/lilypond/mf:"
  99      export TEXINPUTS="/usr/local/share/lilypond/tex:/usr/local/share/lilypond/ps:"
 100
 101    The empty path component represents TeX and MetaFont's default
 102 search paths.  Scripts with the proper paths for the bourne and C-shell
 103 respectively are generated in `buildscripts/out/lilypond-profile' and
 104 `buildscripts/out/lilypond-login' during compilation.
 105
 106    LilyPond is a hiddeously big, slow and bloated program.  A fast CPU
 107 and plenty of RAM is recommended for comfortable use.
 108
 109 Website
 110 =======
 111
 112    The website is the most convenient form to use for reading the
 113 documentation on-line documentation. It is made by entering
 114
 115        make website
 116    This does require a fully functioning
 117
 118    If you want to auto-generate Lily's website, you'll need some
 119 additional conversion tools.
 120
 121    * xpmtoppm (from the Portable Bitmap Utilities) (For RedHat Linux
 122       users: it is included within the package libgr-progs).
 123      the original is at
 124      ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz
 125      (ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz)
 126
 127    * pnmtopng, which is also in libgr-progs for RedHat. The original is
 128      at
 129      ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz
 130      (ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz).i
 131
 132      The version of `pnmtopng' that is distributed with RedHat 5.1 and
 133      5.2 contains a bug: pnmtopng is dynamically linked to the wrong
 134      version of libpng, which results in cropped images.  Recompile it
 135      from source, and make sure that the pnmtopng binary is linked
 136      statically to the libpng that is included in libgr.  RedHat 6.0
 137      does not have this problem.
 138
 139            tar xzf libgr-2.0.13.tar.gz
 140                 make
 141                 cd png
 142                 rm libpng.so*
 143                 make pnmtopng
 144
 145      You can then install the new pnmtopng into `/usr/local/bin/'
 146
 147    * Bib2html http://pertsserver.cs.uiuc.edu/~hull/bib2html.
 148      (http://pertsserver.cs.uiuc.edu/~hull/bib2html.)      Which, in
 149      turn depends on man2html for proper installation.  man2html can be
 150      had from
 151      http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05
 152      (http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05).
 153
 154      The website will build without this utility, but you will not see
 155      our hypertextified bibliography.
 156
 157    * Doc++ (optional) to read the source code.
 158
 159
 160    You also have to install `buildscripts/out/ps-to-gifs' in a
 161 directory that is in the path.
 162
 163 configuring and compiling
 164 =========================
 165
 166    to install GNU LilyPond, simply type:
 167
 168         gunzip -c lilypond-x.y.z | tar xf -
 169         cd lilypond-x.y.z
 170         ./configure             # fill in your standard prefix with --prefix
 171         make
 172         make install
 173
 174    This will install a number of files, something close to:
 175
 176         /usr/local/man/man1/mi2mu.1
 177         /usr/local/man/man1/convert-mudela.1
 178         /usr/local/man/man1/mudela-book.1
 179         /usr/local/man/man1/lilypond.1
 180         /usr/local/bin/lilypond
 181         /usr/local/bin/mi2mu
 182         /usr/local/share/lilypond/*
 183         /usr/local/share/locale/{it,nl}/LC_MESSAGES/lilypond.mo
 184
 185    The above assumes that you are root and have the GNU development
 186 tools, and your make is GNU make.  If this is not the case, you can
 187 adjust your environment variables to your taste:
 188
 189
 190         export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR"
 191         ./configure
 192
 193    `CPPFLAGS' are the preprocessor flags.
 194
 195    The configure script is Cygnus configure, and it will accept
 196 `--help'. If you are not root, you will probably have to make it with a
 197 different `--prefix' option.  Our favourite location is
 198
 199
 200         ./configure --prefix=$HOME/usr
 201
 202    In this case, you will have to set up MFINPUTS, and TEXINPUTS
 203 accordingly.
 204
 205    Since GNU LilyPond currently is beta, you are advised to also use
 206
 207
 208         --enable-debugging
 209         --enable-checking
 210
 211    Options to configure include:
 212
 213 ``--enable-printing''
 214      Enable debugging print routines (lilypond `-D' option)
 215
 216 ``--enable-optimise''
 217      Set maximum optimisation: compile with `-O2'.  This can be
 218      unreliable on some compiler/platform combinations (eg, DEC Alpha
 219      and PPC)
 220
 221 ``--enable-profiling''
 222      Compile with support for profiling.
 223
 224 ``--enable-config''
 225      Output to a different configuration file.  Needed for
 226      multi-platform     builds
 227
 228    All options are documented in the `configure' help The option
 229 `--enable-optimise' is recommended for Real Life usage.
 230
 231    If you do
 232
 233
 234         make all
 235
 236    everything will be compiled, but nothing will be installed.  The
 237 resulting binaries can be found in the subdirectories `out/' (which
 238 contain all files generated during compilation).
 239
 240 configuring for multiple platforms
 241 ==================================
 242
 243    If you want to compile LilyPond with different configuration
 244 settings, then, you can use the `--enable-config' option.  Example:
 245 suppose I want to build with and   without profiling.  Then I'd use the
 246 following for the normal build,
 247
 248
 249            ./configure --prefix=~ --disable-optimise --enable-checking
 250            make
 251            make install
 252
 253    and for the profiling version, I specify a different configuration.
 254
 255
 256            ./configure --prefix=~ --enable-profiling --enable-config=optprof --enable-optimise --disable-checking
 257            make config=optprof
 258            make config=optprof install
 259
 260 Installing
 261 ==========
 262
 263    if you have done a successful `make', then a simple
 264
 265
 266         make install
 267
 268    should do the trick.
 269
 270    If you are doing an upgrade, please remember to remove obsolete
 271 `.pk' and `.tfm' files of the fonts.  A script has been provided to do
 272 the work for you, see `bin/clean-fonts.sh'.
 273
 274 CAVEATS
 275 =======
 276
 277    * The -O2 option  triggers  bugs on various platforms (PowerPC,
 278      Alpha).      If you experience problems, you  should first try
 279      turning off     this.
 280
 281    * On PPC you need at least EGCS-1.1.2f.
 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 file
 324 README-W32, included with the sources.
 325
 326 Bugs
 327 ====
 328
 329    Send bug reports to bug-gnu-music@gnu.org.  For help and questions
 330 use help-gnu-music@gnu.org and gnu-music-discuss@gnu.org.  Please
 331 consult the faq before mailing your problems.
 332
 333 Authors
 334 =======
 335
 336    Han-Wen Nienhuys <hanwen@cs.uu.nl>
 337
 338    Jan Nieuwenhuizen <janneke@gnu.org>
 339
 340    In case of problems, please use the mailing list for help.
 341
 342    Have fun!
 343