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         tar -C /usr/lib/texmf/fonts/source/ -zxf musixtex-T73.tgz 'mf/*'
  17
  18 The detailed instructions follow here.
  19
  20 =head1 PREREQUISITES
  21
  22 For compilation you need.
  23
  24 =over 5
  25
  26 =item *
  27
  28 A Unix system with GNU tools. GNU LilyPond is known to run on these
  29 unices: Linux, AIX, Digital Unix and Solaris.
  30
  31 If you have the Cygnus WINDOWS32 port of the GNU utils, it will even
  32 work in Windows NT/95, but we don't promise to support it.
  33
  34 =item *
  35
  36 GNU C++ v2.7 or better, with libg++ installed.  Version 2.7.2
  37 or better recommended.
  38
  39 =item *
  40
  41 GNU make.
  42
  43 =item *
  44
  45 Flex (2.5.1 or better).
  46
  47 =item *
  48
  49 Bison. (Version 1.25 or better)
  50
  51 =back
  52
  53 =head1 RUNNING
  54
  55 GNU LilyPond does use a lot of resources. For operation you need the following:
  56
  57
  58 =over 5
  59
  60 =item *
  61
  62 TeX
  63
  64 =item *
  65
  66 The MusixTeX fonts (I included those found in MusixTeX T.73). Beware,
  67 the clef symbol seems to have changed its position in some versions,
  68 (notably Egler's, a.k.a. OpusTeX). The MusixTeX fonts are included in
  69 MusixTeX (T73 or better), which can be had from any CTAN site, e.g. at
  70
  71 =over 4
  72
  73 =item ftp://ftp.shsu.edu/tex-archive/macros/musixtex/taupin
  74
  75 =item ftp://ftp.tex.ac.uk/tex-archive/macros/musixtex/taupin
  76
  77 =item ftp://ftp.dante.de/tex-archive/macros/musixtex/taupin
  78
  79 =back
  80
  81 You only need the contents of the F<mf/> subdirectory of the
  82 package. The primary site of the Taupin version is
  83 ftp://hprib.lps.u-psud.fr/pub/music_zips/musixtex.zip
  84
  85 Andreas Egler's version of MusixTeX, now called OpusTeX, will also
  86 work. Andreas moved some characters around in the fonts, so you have
  87 to edit the definitions in tex/eglerdefs.tex (patch appreciated)
  88
  89
  90 =head1 RECOMMENDED
  91
  92 Although not strictly necessary, these are recommended to have.
  93
  94 =over 5
  95
  96 =item *
  97
  98 Perl.  Most scripts are written in Perl. Most  documentation was created
  99 with the perl's Plain Old Documentation.
 100
 101 =item *
 102
 103 GNU find
 104
 105 =item *
 106
 107 A fast computer (a full page of music typically takes 1 minute
 108 on my 486/133, using the B<--enable-checking> compile. It's lot slower
 109 than most MusiXTeX preprocessors)
 110
 111 =back
 112
 113
 114 =head1 CONFIGURING and COMPILING
 115
 116 to install GNU LilyPond, simply type:
 117
 118         configure
 119         make install
 120
 121 This will install the following files:
 122
 123         /usr/local/man/man1/mi2mu.1
 124         /usr/local/man/man1/convert-mudela.1
 125         /usr/local/man/man1/mudela-book.1
 126         /usr/local/man/man1/lilypond.1
 127         /usr/local/lib/libflower.{so,a}
 128         /usr/local/bin/lilypond
 129         /usr/local/bin/mi2mu
 130         /usr/local/share/lilypond/*
 131         /usr/lib/texmf/texmf/tex/lilypond/*
 132
 133 The TeX include directory is detected dynamically, but it can be
 134 adjusted with B<--enable-tex-prefix> and B<--enable-tex-dir>. The
 135 above assumes that you are root and have the GNU development tools,
 136 and your make is GNU make.  If this is not the case, you can adjust
 137 your environment variables to your taste:
 138
 139         export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR"
 140         configure
 141
 142 C<CPPFLAGS> are the preprocessor flags.
 143
 144 the configure script is Cygnus configure, and it will accept
 145 B<--help>. If you are not root, you will probably have to make it with
 146
 147         configure --prefix=/home/me_myself_and_I/
 148
 149 In this case, you will have to set MFINPUTS, and TEXINPUTS accordingly.
 150
 151 If you want to install GNU LilyPond in F</usr/local>, and your TeX has
 152 no default hooks for local stuff (mine is broken too), you can do:
 153
 154         configure --prefix=/usr/local --enable-tex-prefix=/usr/lib/texmf
 155
 156 Since GNU LilyPond currently is beta, you are advised to also use
 157
 158         --enable-debugging
 159         --enable-checking
 160
 161 other options include:
 162
 163 =over 4
 164
 165 =item --enable-shared
 166
 167 Make a shared library (gnu/linux, solaris (?) only )
 168
 169 =item --enable-printing
 170
 171 Enable debugging print routines (lilypond B<-d> option)
 172
 173 =item --enable-optimise
 174
 175 Set maximum optimisation: compile with B<-O2>
 176
 177 =item --enable-profiling
 178
 179 Compile with support for profiling
 180
 181 =item --enable-tex-prefix
 182
 183 Set the directory where TeX and Metafont live
 184
 185 =item --enable-tex-dir
 186
 187 Set then directory TeX input is in (detected as a subdir of tex-prefix)
 188
 189 =item --enable-mf-dir
 190
 191 Set then directory mf input is in (idem) [obsolete]
 192
 193 =back
 194
 195 All options are documented in the F<configure> help
 196 The option B<--enable-optimise> is recommended for Real Life usage.
 197
 198 If you do
 199
 200         make all
 201
 202 everything will be compiled, but nothing will be installed.  The
 203 resulting binaries can be found in the subdirectories F<out/> (which
 204 contain all files generated during compilation).
 205
 206
 207 =head1 INSTALLING
 208
 209 If you have done a successful C<make>, then a simple
 210
 211         make install
 212
 213 should do the trick.
 214
 215 Install the musixtex fonts in a directory which TeX and MF knows (if
 216 you are root, look for a directory which contains the directories with
 217 AMS and CM source (*.mf) files. Create a subdir lilypond or musixtex
 218 and copy the fonts into that). Do not forget to rehash TeX (if
 219 applicable)
 220
 221 Example: my fonts are in F</usr/local/lib/texfonts/musixtex/>, and I
 222 have a symlink pointing to that in
 223 F</usr/lib/texmf/texmf/fonts/source/public/>. After I copied the
 224 files, I ran "texhash"
 225
 226 =head1 CAVEATS
 227
 228 =over 5
 229
 230 =item *
 231
 232 The -O2 option to gcc triggers a gcc bug on DEC Alpha in dstream.cc. You
 233 should turn off this flag for this file.
 234
 235 =back
 236
 237 =head1 EXAMPLE
 238
 239 This is what I type in my xterm:
 240
 241         lilypond someinput.ly
 242         tex lelie.tex
 243         xdvi test&
 244
 245 This is what the output looks like over here:
 246
 247         GNU LilyPond 0.0.78 #4/FlowerLib 1.1.24 #0
 248         Parsing ... [/home/hw/share/lilypond/init//
 249                 <..etc..>
 250                 init//performer.ly]]][input/kortjakje.ly]
 251         Creating elements ...[8][16][24][25]
 252         Preprocessing elements...
 253         Calculating column positions ... [14][25]
 254         Postprocessing elements...
 255         TeX output to lelie.tex ...
 256         Creating MIDI elements ...MIDI output to lelie.midi ...
 257
 258
 259         hw:~/musix/spacer$ xdvi lelie&
 260         [1] 855
 261
 262 Check out the input files, some of them have comments
 263 Please refer to the man page for more information.
 264
 265 =head1 REDHAT LINUX
 266
 267 RedHat Linux users should be able to get a RPM. A spec file is in
 268 F<make/out/lilypond.spec>. You should be able to create an rpm as a normal
 269 user. Be sure you have a ~/.rpmrc, and edit the RPM-dir in
 270 F<Variables.make>. (If you create the RPM as a normal user the
 271 permissions will not be set correctly, unfortunately)
 272
 273
 274 =head1 WINDOZE
 275
 276 Windows NT:
 277
 278 you need the cygnus windows32 gnu port development stuff; have a look
 279 at http://www.cygnus.com/gnu-win32.
 280
 281 to make GNU LilyPond under, brr, aargh, shudder.. windows32, well,
 282 simply type:
 283
 284         bash configure
 285         make windows32
 286
 287 =head1 AUTHORS
 288
 289 Han-Wen Nienhuys <hanwen@stack.nl>
 290
 291 Jan Nieuwenhuizen <jan@digicash.com>
 292
 293
 294 Have fun!