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
  38 =back
  39
  40 =head1 RUNNING
  41
  42 GNU LilyPond does use a lot of resources. For operation you need the following:
  43
  44
  45 =over 5
  46
  47 =item *
  48
  49 TeX
  50
  51 =item *
  52
  53 A PostScript printer and/or viewer (such as Ghostscript) is strongly
  54 recommended.  Xdvi will show all embedded PostScript too if you have
  55 Ghostscript installed.
  56
  57 =back
  58
  59 =head1 RECOMMENDED
  60
  61 Although not strictly necessary, these are recommended to have.
  62
  63 =over 5
  64
  65 =item *
  66
  67 GNU make.
  68
  69 =item *
  70
  71 Flex (version 2.5.4 or newer).
  72
  73 =item *
  74
  75 Bison (version 1.25 or newer).
  76 =item *
  77
  78 Perl-5.  Most documentation was created with the perl's Plain Old
  79 Documentation. (I use 5.003)
  80
  81 =item *
  82
  83 Python.  Although perl is nice, python is better.  We will shift
  84 towards python for build scripts
  85
  86 =item *
  87
  88 GNU find
  89
  90 =item *
  91
  92 A fast computer (a full page of music typically takes 1 minute on my
  93 486/133, using the B<--enable-checking> compile. It's lot slower than
  94 most MusiXTeX preprocessors)
  95
  96 =back
  97
  98
  99 =head1 CONFIGURING and COMPILING
 100
 101 to install GNU LilyPond, simply type:
 102
 103         configure
 104         make install
 105
 106 This will install the following files:
 107
 108         /usr/local/man/man1/mi2mu.1
 109         /usr/local/man/man1/convert-mudela.1
 110         /usr/local/man/man1/mudela-book.1
 111         /usr/local/man/man1/lilypond.1
 112         /usr/local/lib/libflower.{so,a}
 113         /usr/local/bin/lilypond
 114         /usr/local/bin/mi2mu
 115         /usr/local/share/lilypond/*
 116         /usr/lib/texmf/texmf/tex/lilypond/*
 117
 118 The TeX include directory is detected dynamically, but it can be
 119 adjusted with B<--enable-tex-prefix> and B<--enable-tex-dir>. The
 120 above assumes that you are root and have the GNU development tools,
 121 and your make is GNU make.  If this is not the case, you can adjust
 122 your environment variables to your taste:
 123
 124         export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR"
 125         configure
 126
 127 C<CPPFLAGS> are the preprocessor flags.
 128
 129 the configure script is Cygnus configure, and it will accept
 130 B<--help>. If you are not root, you will probably have to make it with
 131
 132         configure --prefix=/home/me_myself_and_I/
 133
 134 In this case, you will have to set MFINPUTS, and TEXINPUTS accordingly.
 135
 136 If you want to install GNU LilyPond in F</usr/local>, and your TeX has
 137 no default hooks for local stuff (mine is broken too), you can do:
 138
 139         configure --prefix=/usr/local --enable-tex-prefix=/usr/lib/texmf
 140
 141 Since GNU LilyPond currently is beta, you are advised to also use
 142
 143         --enable-debugging
 144         --enable-checking
 145
 146 other options include:
 147
 148 =over 4
 149
 150 =item B<--enable-shared>
 151
 152 Make a shared library (gnu/linux, solaris (?) only )
 153
 154 =item B<--enable-printing>
 155
 156 Enable debugging print routines (lilypond B<-d> option)
 157
 158 =item B<--enable-optimise>
 159
 160 Set maximum optimisation: compile with B<-O2>
 161
 162 =item B<--enable-profiling>
 163
 164 Compile with support for profiling
 165
 166 =item B<--enable-tex-prefix>
 167
 168 Set the directory where TeX and Metafont live
 169
 170 =item B<--enable-tex-dir>
 171
 172 Set then directory TeX input is in (detected as a subdir of tex-prefix)
 173
 174 =item B<--enable-mf-dir>
 175
 176 Set the directory mf input is in (idem)
 177
 178 =back
 179
 180 All options are documented in the F<configure> help
 181 The option B<--enable-optimise> is recommended for Real Life usage.
 182
 183 If you do
 184
 185         make all
 186
 187 everything will be compiled, but nothing will be installed.  The
 188 resulting binaries can be found in the subdirectories F<out/> (which
 189 contain all files generated during compilation).
 190
 191 =head1 INSTALLING
 192
 193 If you have done a successful C<make>, then a simple
 194
 195         make install
 196
 197 should do the trick.
 198
 199 If you are doing an upgrade, please remember to remove obsolete .pk
 200 and .tfm files of the fonts.  A script has been provided to do the
 201 work, see F<bin/clean-fonts.sh>.
 202
 203 =head1 CAVEATS
 204
 205 =over 5
 206
 207 =item *
 208
 209 The -O2 option to gcc triggers a gcc bug on DEC Alpha in dstream.cc. You
 210 should turn off this flag for this file.
 211
 212 =item *
 213
 214 Perl5.003 and Perl5.004 use different syntax for pod2html.
 215
 216 =back
 217
 218 =head1 EXAMPLE
 219
 220 This is what I type in my xterm:
 221
 222         lilypond someinput.ly
 223         tex someinput.tex
 224         xdvi someinput&
 225
 226 This is what the output looks like over here:
 227
 228         GNU LilyPond 0.0.78 #4/FlowerLib 1.1.24 #0
 229         Parsing ... [/home/hw/share/lilypond/init//
 230                 <..etc..>
 231                 init//performer.ly]]][input/kortjakje.ly]
 232         Creating elements ...[8][16][24][25]
 233         Preprocessing elements...
 234         Calculating column positions ... [14][25]
 235         Postprocessing elements...
 236         TeX output to someinput.tex ...
 237         Creating MIDI elements ...MIDI output to someinput.midi ...
 238
 239
 240         hw:~/musix/spacer$ xdvi someinput&
 241         [1] 855
 242
 243 Check out the input files, some of them have comments
 244 Please refer to the man page for more information.
 245
 246 =head1 REDHAT LINUX
 247
 248 RedHat Linux users should be able to get a RPM. A spec file is in
 249 F<make/out/lilypond.spec>. You should be able to create an rpm as a
 250 normal user. Be sure you have a F<~/.rpmrc>, and edit the RPM-dir in
 251 F<Variables.make>. (If you create the RPM as a normal user the
 252 permissions will not be set correctly, unfortunately)
 253
 254
 255 =head1 DEBIAN GNU/LINUX
 256
 257 A Debian package is also available; contact Anthony Fok
 258 <foka@debian.org>.  The build scripts are in the subdirectory debian/
 259
 260
 261 =head1 WINDOWS NT/95
 262
 263 So, you're stuck with Windows, eh?  Well, don't worry, you just
 264 need (to get) Cygnus' windows32 port of gnu development stuff;
 265 have a look at http://www.cygnus.com/gnu-win32.
 266
 267 To make GNU LilyPond under, brr, aargh, shudder... windows32, well,
 268 simply type:
 269
 270         bash configure
 271         make
 272
 273 B<Note> If you rely on broken DOS/Windows tools such as pkzip/WinZIP
 274 to unpack the distribution, make sure the B<entire> source tree
 275 is unpacked correctly, in particular the empty out directories
 276 (F<flower/out>, F<lib/out> et. al.)
 277
 278 =head1 MUSIXTEX
 279
 280 Previous versions (before 0.1.39) used fonts from the TeX macro
 281 package "MusixTeX".  You can still use these, but they are not
 282 supported.  Since LilyPond's Feta font is much prettier, you'd be
 283 seriously misguided if you used them, but anyway, here are the
 284 installation instructions for those deprecated fonts.
 285
 286
 287 [obsolete] I use the MusixTeX fonts those found in MusixTeX
 288 T.73. Beware, the clef symbol seems to have changed its position in
 289 some versions, (notably Egler's, a.k.a. OpusTeX). The MusixTeX fonts
 290 are included in MusixTeX (T73 or newer), which can be had from any
 291 CTAN site, e.g. at
 292
 293 =over 4
 294
 295 =item ftp://ftp.shsu.edu/tex-archive/macros/musixtex/taupin
 296
 297 =item ftp://ftp.tex.ac.uk/tex-archive/macros/musixtex/taupin
 298
 299 =item ftp://ftp.dante.de/tex-archive/macros/musixtex/taupin
 300
 301 =back
 302
 303 You only need the contents of the F<mf/> subdirectory of the
 304 package. The primary site of the Taupin version is
 305 ftp://hprib.lps.u-psud.fr/pub/music_zips/musixtex.zip
 306
 307 Install the musixtex fonts in a directory which TeX and MF knows (if
 308 you are root, look for a directory which contains the directories with
 309 AMS and CM source (*.mf) files. Create a subdir lilypond or musixtex
 310 and copy the fonts into that). Do not forget to rehash TeX (if
 311 applicable)
 312
 313 Example: my fonts are in F</usr/local/lib/texfonts/musixtex/>, and I
 314 have a symlink pointing to that in
 315 F</usr/lib/texmf/texmf/fonts/source/public/>. After I copied the
 316 files, I ran "texhash"
 317
 318 Andreas Egler's version of MusixTeX, now called OpusTeX, will also
 319 work. Andreas moved some characters around in the fonts, so you have
 320 to edit the definitions in F<tex/eglerdefs.tex>.
 321
 322
 323
 324 =head1 AUTHORS
 325
 326 Han-Wen Nienhuys <hanwen@cs.ruu.nl>
 327
 328 Jan Nieuwenhuizen <jan@digicash.com>
 329
 330
 331 Have fun!