Documentation/INSTALL.pod

   1 =head1 NAME
   2
   3 INSTALL - installing GNU LilyPond
   4
   5 =head1 DESCRIPTION
   6
   7 This page documents installation and compilation of GNU LilyPond
   8
   9 =head1 ABSTRACT
  10
  11 You do something which looks remotely like
  12
  13         configure
  14         make
  15         make install
  16
  17 The detailed instructions follow here.
  18
  19 =head1 PREREQUISITES
  20
  21 For compilation you need.
  22
  23 =over 5
  24
  25 =item *
  26
  27 A GNU system: GNU LilyPond is known to run on these GNU systems: Linux
  28 (PPC, intel), FreeBSD, AIX, NeXTStep, IRIX, Digital Unix and Solaris.
  29
  30 If you have the Cygnus WINDOWS32 port of the GNU utils, it will even
  31 work in Windows NT/95, but we don't promise to support it.
  32
  33 =item *
  34
  35 GNU C++ version 2.7 or newer (yes, 2.8 is fine).
  36
  37 =item *
  38
  39 Python
  40
  41 =back
  42
  43 =head1 RUNNING
  44
  45 GNU LilyPond does use a lot of resources. For operation you need the following:
  46
  47 =over 5
  48
  49 =item *
  50
  51 TeX
  52
  53 =item *
  54
  55 A PostScript printer and/or viewer (such as Ghostscript) is strongly
  56 recommended.  Xdvi will show all embedded PostScript too if you have
  57 Ghostscript installed.
  58
  59 =back
  60
  61 =head1 RECOMMENDED
  62
  63 Although not strictly necessary, these are recommended to have.
  64
  65 =over 5
  66
  67 =item *
  68
  69 GNU make.
  70
  71 =item *
  72
  73 Flex (version 2.5.4 or newer).
  74
  75 =item *
  76
  77 Bison (version 1.25 or newer).
  78
  79 =item *
  80
  81 Perl-5.  Most documentation was created with the perl's Plain Old
  82 Documentation. (I use 5.003)
  83
  84 =item *
  85
  86 Python.  Although perl is nice, python is better.  We will shift
  87 towards python for build scripts
  88
  89 =item *
  90
  91 GNU find
  92
  93 =item *
  94
  95 A fast computer (a full page of music typically takes 1 minute on my
  96 486/133, using the B<--enable-checking> compile. It's lot slower than
  97 most MusiXTeX preprocessors)
  98
  99 =back
 100
 101 =head1 WEBSITE
 102
 103 If you want to auto-generate Lily's website, you'll need some additional
 104 conversion tools.
 105
 106 =over 5
 107
 108 =item *
 109
 110 Xpmtoppm (from the libgr-progs package).
 111
 112 =item *
 113
 114 Bib2html (http://pertsserver.cs.uiuc.edu/~hull/bib2html.)
 115 Which, in turn depends on Man2htlm (http://askdonald.ask.uni-karlsruhe.de/
 116 hppd/hpux/Networking/WWW/Man2html-1.05) for proper installation (ugh).
 117 TeTeX users, don't forget to rerun texhash.
 118
 119 =back
 120
 121 =head1 CONFIGURING and COMPILING
 122
 123 to install GNU LilyPond, simply type:
 124
 125         configure
 126         make
 127         make install
 128
 129 This will install the following files:
 130
 131         /usr/local/man/man1/mi2mu.1
 132         /usr/local/man/man1/convert-mudela.1
 133         /usr/local/man/man1/mudela-book.1
 134         /usr/local/man/man1/lilypond.1
 135         /usr/local/lib/libflower.{so,a}
 136         /usr/local/bin/lilypond
 137         /usr/local/bin/mi2mu
 138         /usr/local/share/lilypond/*
 139         /usr/lib/texmf/texmf/tex/lilypond/*
 140
 141 The TeX include directory is detected dynamically, but it can be
 142 adjusted with B<--enable-tex-prefix> and B<--enable-tex-dir>. The
 143 above assumes that you are root and have the GNU development tools,
 144 and your make is GNU make.  If this is not the case, you can adjust
 145 your environment variables to your taste:
 146
 147         export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR"
 148         configure
 149
 150 C<CPPFLAGS> are the preprocessor flags.
 151
 152 the configure script is Cygnus configure, and it will accept
 153 B<--help>. If you are not root, you will probably have to make it with
 154
 155         configure --prefix=/home/me_myself_and_I/
 156
 157 In this case, you will have to set MFINPUTS, and TEXINPUTS accordingly.
 158
 159 If you want to install GNU LilyPond in F</usr/local>, and your TeX has
 160 no default hooks for local stuff (mine is broken too), you can do:
 161
 162         configure --prefix=/usr/local --enable-tex-prefix=/usr/lib/texmf
 163
 164 Since GNU LilyPond currently is beta, you are advised to also use
 165
 166         --enable-debugging
 167         --enable-checking
 168
 169 other options include:
 170
 171 =over 4
 172
 173 =item B<--enable-shared>
 174
 175 Make a shared library (gnu/linux, solaris (?) only )
 176
 177 =item B<--enable-printing>
 178
 179 Enable debugging print routines (lilypond B<-d> option)
 180
 181 =item B<--enable-optimise>
 182
 183 Set maximum optimisation: compile with B<-O2>
 184
 185 =item B<--enable-profiling>
 186
 187 Compile with support for profiling
 188
 189 =item B<--enable-tex-prefix>
 190
 191 Set the directory where TeX and Metafont live
 192
 193 =item B<--enable-tex-dir>
 194
 195 Set then directory TeX input is in (detected as a subdir of
 196 tex-prefix).  This should be a directory that is reachable both for
 197 tex and latex.  On my system the best choice would be
 198 F</usr/lib/texmf/texmf/tex/generic//>.
 199
 200 =item B<--enable-mf-dir>
 201
 202 Set the directory mf input is in (idem).   On my system the best
 203 choice would be F</usr/lib/texmf/texmf/fonts/source/public/>.
 204
 205 =item B<--enable-config>
 206
 207 Output to different configuration files.  Needed for multi-platform
 208 builds
 209
 210
 211 =back
 212
 213 All options are documented in the F<configure> help
 214 The option B<--enable-optimise> is recommended for Real Life usage.
 215
 216 If you do
 217
 218         make all
 219
 220 everything will be compiled, but nothing will be installed.  The
 221 resulting binaries can be found in the subdirectories F<out/> (which
 222 contain all files generated during compilation).
 223
 224 =head1 CONFIGURING FOR MULTIPLE PLATFORMS
 225
 226 If you want to compile LilyPond with different configuration settings,
 227 then, you can use the B<--enable-config> option.  Example: suppose I
 228 want to build with and   without profiling.  Then I'd use the
 229 following for the normal build,
 230
 231       configure --prefix=~ --disable-optimise --enable-checking
 232       make
 233       make install
 234
 235 and for the profiling version, I specify a different configuration.
 236
 237       configure --prefix=~ --enable-profiling --enable-config=optprof --enable-optimise --disable-checking
 238       make configuration=optprof
 239       make configuration=optprof install
 240
 241
 242 =head1 INSTALLING
 243
 244 If you have done a successful C<make>, then a simple
 245
 246         make install
 247
 248 should do the trick.
 249
 250 If you are doing an upgrade, please remember to remove obsolete .pk
 251 and .tfm files of the fonts.  A script has been provided to do the
 252 work, see F<bin/clean-fonts.sh>.
 253
 254 =head1 CAVEATS
 255
 256 =over 5
 257
 258 =item *
 259
 260 The -O2 option to gcc triggers a gcc bug on DEC Alpha in dstream.cc. You
 261 should turn off this flag for this file.
 262
 263 =item *
 264
 265 Perl5.003 and Perl5.004 use different syntax for pod2html.
 266
 267 =back
 268
 269 =head1 EXAMPLE
 270
 271 This is what I type in my xterm:
 272
 273         lilypond someinput.ly
 274         tex someinput.tex
 275         xdvi someinput&
 276
 277 This is what the output looks like over here:
 278
 279         GNU LilyPond 0.0.78 #4/FlowerLib 1.1.24 #0
 280         Parsing ... [/home/hw/share/lilypond/init//
 281                 <..etc..>
 282                 init//performer.ly]]][input/kortjakje.ly]
 283         Creating elements ...[8][16][24][25]
 284         Preprocessing elements...
 285         Calculating column positions ... [14][25]
 286         Postprocessing elements...
 287         TeX output to someinput.tex ...
 288         Creating MIDI elements ...MIDI output to someinput.midi ...
 289
 290
 291         hw:~/musix/spacer$ xdvi someinput&
 292         [1] 855
 293
 294 Check out the input files, some of them have comments
 295 Please refer to the man page for more information.
 296
 297 =head1 REDHAT LINUX
 298
 299 RedHat Linux users can compile an RPM. A spec file is in
 300 F<make/out/lilypond.spec>.  You should install a gif file called
 301 F<lelie_icon.gif> along with the sources.  You can generate this gif
 302 file by typing
 303
 304      make gifs
 305
 306 in the directory F<Documentation>.
 307
 308
 309
 310 =head1 DEBIAN GNU/LINUX
 311
 312 A Debian package is also available; contact Anthony Fok
 313 <foka@debian.org>.  The build scripts are in the subdirectory debian/
 314
 315
 316 =head1 WINDOWS NT/95
 317
 318 So, you're stuck with Windows, eh?  Well, don't worry, you just
 319 need (to get) Cygnus' windows32 port of gnu development stuff;
 320 have a look at http://www.cygnus.com/gnu-win32.
 321
 322 To make GNU LilyPond under, brr, aargh, shudder... windows32, well,
 323 simply type:
 324
 325         bash configure
 326         make
 327
 328 B<Note> If you rely on broken DOS/Windows tools such as pkzip/WinZIP
 329 to unpack the distribution, make sure the B<entire> source tree
 330 is unpacked correctly, in particular the empty out directories
 331 (F<flower/out>, F<lib/out> et. al.)
 332
 333 =head1 AUTHORS
 334
 335 Han-Wen Nienhuys <hanwen@cs.ruu.nl>
 336
 337 Jan Nieuwenhuizen <jan@digicash.com>
 338
 339
 340 Have fun!