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