Documentation/topdocs/INSTALL.yo

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