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