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 following:
  43
  44 itemize(
  45 it()TeX
  46 it()A PostScript printer and/or viewer (such as Ghostscript) is strongly
  47     recommended.  Xdvi will show all embedded PostScript too if you have
  48     Ghostscript installed.
  49 )
  50
  51 sect(RECOMMENDED)
  52
  53 Although not strictly necessary, these are recommended to have.
  54
  55 itemize(
  56 it()GNU make.
  57 Check out lurl(ftp://ftp.gnu.org)
  58 or any mirror of this site.
  59
  60 it()Flex (version 2.5.4 or newer).
  61 Check out lurl(ftp://ftp.gnu.org)
  62 or any mirror of this site.
  63 it()Bison (version 1.25 or newer).
  64 Check out lurl(ftp://ftp.gnu.org)
  65 or any mirror of this site.
  66
  67 it()Python (version 1.5 or newer).  Check out
  68 lurl(ftp://ftp.python.org) or lurl(ftp://ftp.cwi.nl/pub/python).
  69
  70 it()Yodl.  All documentation will be in Yodl. (1.30.17)
  71 lurl(ftp://pcnov095.win.tue.nl/pub/yodl)
  72     lurl(http://www.cs.uu.nl/~hanwen/yodl)
  73 it()Texinfo. (version 3.12 or newer)
  74
  75 it()GNU find
  76 Check out lurl(ftp://ftp.gnu.org)
  77 or any mirror of this site
  78
  79
  80 it() A fast computer (a full page of music typically takes 1 minute on my
  81     486/133, using the bf(--enable-checking) compile. It's lot slower than
  82     most MusiXTeX preprocessors)
  83 )
  84
  85 sect(WEBSITE)
  86
  87 If you want to auto-generate Lily's website, you'll need some additional
  88 conversion tools.
  89
  90 itemize(
  91 it()xpmtoppm (from the Portable Bitmap Utilities) (For RedHat Linux
  92              users: it is included within the package libgr-progs).
  93 it()Bib2html lurl(http://pertsserver.cs.uiuc.edu/~hull/bib2html.)
  94     Which, in turn depends on man2html for proper installation.
  95 man2html can be had from lurl(http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05).
  96
  97     TeTeX users should not forget to rerun texhash.
  98 )
  99
 100 sect(CONFIGURING and COMPILING)
 101
 102 to install GNU LilyPond, simply type:
 103 verb(
 104         configure  --enable-tex-dir=XXXX --enable-mf-dir=YYYY
 105         make
 106         make install
 107 )
 108
 109 This will install a number of files, something close to:
 110 verb(
 111         /usr/local/man/man1/mi2mu.1
 112         /usr/local/man/man1/convert-mudela.1
 113         /usr/local/man/man1/mudela-book.1
 114         /usr/local/man/man1/lilypond.1
 115         /usr/local/bin/lilypond
 116         /usr/local/bin/mi2mu
 117         /usr/local/share/lilypond/*
 118         /usr/local/share/locale/{it,nl}/LC_MESSAGES/lilypond.mo
 119         /usr/lib/texmf/texmf/tex/lilypond/*
 120 )
 121
 122
 123 You should specify directories that are in TeX()'s and MetaFont's
 124 include path with the options (--enable-tex-dir) and
 125 bf(--enable-mf-dir).  If you don't specify any directories, the TeX()
 126 include directory is detected dynamically, which is unreliable.  The
 127 above assumes that you are root and have the GNU development tools,
 128 and your make is GNU make.  If this is not the case, you can adjust
 129 your environment variables to your taste:
 130
 131 verb(
 132         export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR"
 133         configure
 134 )
 135
 136 code(CPPFLAGS) are the preprocessor flags.
 137
 138 The configure script is Cygnus configure, and it will accept
 139 bf(--help). If you are not root, you will probably have to make it
 140 with a different bf(--prefix) option.  Our favourite location is
 141
 142 verb(
 143         configure --prefix=$HOME/usr
 144 )
 145
 146 In this case, you will have to set up MFINPUTS, and TEXINPUTS accordingly.
 147
 148 If you want to install GNU LilyPond in file(/usr/local), and your TeX has
 149 no default hooks for local stuff, you can do:
 150
 151 verb(
 152         configure --prefix=/usr/local --enable-tex-prefix=/usr/lib/texmf
 153 )
 154
 155 Since GNU LilyPond currently is beta, you are advised to also use
 156
 157 verb(
 158         --enable-debugging
 159         --enable-checking
 160 )
 161
 162 Other options include:
 163
 164 description(
 165 dit(bf(--enable-shared))
 166     Make a shared library (gnu/linux, solaris (?) only )  (TEMPORARILY
 167 OUT OF ORDER)
 168
 169 dit(bf(--enable-printing))
 170     Enable debugging print routines (lilypond bf(-D) option)
 171 dit(bf(--enable-optimise))
 172     Set maximum optimisation: compile with bf(-O2)
 173 dit(bf(--enable-profiling))
 174     Compile with support for profiling.
 175 dit(bf(--enable-tex-prefix))
 176     Set the directory where TeX and Metafont live.
 177 dit(bf(--enable-tex-dir))
 178     Set then directory TeX input is in (detected as a subdir of
 179     tex-prefix).  This should be a directory that is reachable both for
 180     tex and latex.  On my system the best choice would be
 181     file(/usr/lib/texmf/texmf/tex/generic//).
 182 dit(bf(--enable-mf-dir))
 183     Set the directory metafont input is in (idem).   On my system the best
 184     choice would be file(/usr/lib/texmf/texmf/fonts/source/public/).
 185 dit(bf(--enable-config))
 186     Output to a different configuration file.  Needed for multi-platform
 187     builds
 188 )
 189
 190 All options are documented in the file(configure) help
 191 The option bf(--enable-optimise) is recommended for Real Life usage.
 192
 193 If you do
 194
 195 verb(
 196         make all
 197 )
 198
 199 everything will be compiled, but nothing will be installed.  The
 200 resulting binaries can be found in the subdirectories file(out/) (which
 201 contain all files generated during compilation).
 202
 203 sect(CONFIGURING FOR MULTIPLE PLATFORMS)
 204
 205 If you want to compile LilyPond with different configuration settings,
 206 then, you can use the bf(--enable-config) option.  Example: suppose I
 207 want to build with and   without profiling.  Then I'd use the
 208 following for the normal build,
 209
 210 verb(
 211       configure --prefix=~ --disable-optimise --enable-checking
 212       make
 213       make install
 214      )
 215
 216 and for the profiling version, I specify a different configuration.
 217
 218 verb(
 219       configure --prefix=~ --enable-profiling --enable-config=optprof --enable-optimise --disable-checking
 220       make config=optprof
 221       make config=optprof install
 222 )
 223
 224
 225 sect(INSTALLING)
 226
 227 If you have done a successful code(make), then a simple
 228
 229 verb(
 230         make install
 231 )
 232
 233 should do the trick.
 234
 235 If you are doing an upgrade, please remember to remove obsolete
 236 file(.pk) and file(.tfm) files of the fonts.  A script has been
 237 provided to do the work for you, see file(bin/clean-fonts.sh).
 238
 239 nsect(CAVEATS)
 240
 241 itemize(
 242 it()The -O2 option to gcc triggers a gcc bug on DEC Alpha in dstream.cc. You
 243     should turn off this flag for this file.
 244 )
 245
 246 nsect(EXAMPLE)
 247
 248 This is what I type in my xterm:
 249
 250 verb(
 251         lilypond someinput.ly
 252         tex someinput.tex
 253         xdvi someinput&
 254 )
 255
 256 This is what the output looks like over here:
 257
 258 verb(
 259         GNU LilyPond 0.0.78 #4/FlowerLib 1.1.24 #0
 260         Parsing ... [/home/hw/share/lilypond/init//
 261                 <..etc..>
 262                 init//performer.ly]]][input/kortjakje.ly]
 263         Creating elements ...[8][16][24][25]
 264         Preprocessing elements...
 265         Calculating column positions ... [14][25]
 266         Postprocessing elements...
 267         TeX output to someinput.tex ...
 268         Creating MIDI elements ...MIDI output to someinput.midi ...
 269
 270
 271         hw:~/musix/spacer$ xdvi someinput&
 272         [1] 855
 273 )
 274
 275 Check out the input files, some of them have comments
 276 Please refer to the man page for more information.
 277
 278 sect(REDHAT LINUX)
 279
 280 RedHat Linux users can compile an RPM. A spec file is in
 281 file(make/out/lilypond.spec).  You should install a gif file called
 282 file(lelie_icon.gif) along with the sources.  You can generate this
 283 gif file by typing
 284
 285 verb(
 286      make gifs
 287 )
 288
 289 in the directory file(Documentation).
 290
 291 You can make the rpm by issuing
 292
 293 verb(
 294         make rpm
 295 )
 296
 297
 298 sect(DEBIAN GNU/LINUX)
 299
 300 A Debian package is also available; contact Anthony Fok
 301 email(foka@debian.org).  The build scripts are in the subdirectory file(debian/)
 302
 303
 304 sect(WINDOWS NT/95)
 305 label(w32)
 306
 307
 308 Separate instructions on building for W32 are avaible
 309 url(in the file README-W32.yo)(../../DOEXPAND(outdir)/README-W32.html).
 310
 311 sect(AUTHORS)
 312
 313 nemail(Han-Wen Nienhuys)(hanwen@cs.uu.nl)
 314
 315 nemail(Jan Nieuwenhuizen)(janneke@gnu.org)
 316
 317
 318 Have fun!