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