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