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