Documentation/topdocs/INSTALL.yo

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