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