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 GNU system: GNU LilyPond is known to run on these GNU systems:
  29 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-5.  Most documentation was created with the perl's Plain Old
  99 Documentation. (I use 5.003)
 100
 101 =item *
 102
 103 Python.  Although perl is nice, python is better.  We will shift
 104 towards python for build scripts
 105
 106 =item *
 107
 108 GNU find
 109
 110 =item *
 111
 112 A fast computer (a full page of music typically takes 1 minute on my
 113 486/133, using the B<--enable-checking> compile. It's lot slower than
 114 most MusiXTeX preprocessors)
 115
 116 =back
 117
 118
 119 =head1 CONFIGURING and COMPILING
 120
 121 to install GNU LilyPond, simply type:
 122
 123         configure
 124         make install
 125
 126 This will install the following files:
 127
 128         /usr/local/man/man1/mi2mu.1
 129         /usr/local/man/man1/convert-mudela.1
 130         /usr/local/man/man1/mudela-book.1
 131         /usr/local/man/man1/lilypond.1
 132         /usr/local/lib/libflower.{so,a}
 133         /usr/local/bin/lilypond
 134         /usr/local/bin/mi2mu
 135         /usr/local/share/lilypond/*
 136         /usr/lib/texmf/texmf/tex/lilypond/*
 137
 138 The TeX include directory is detected dynamically, but it can be
 139 adjusted with B<--enable-tex-prefix> and B<--enable-tex-dir>. The
 140 above assumes that you are root and have the GNU development tools,
 141 and your make is GNU make.  If this is not the case, you can adjust
 142 your environment variables to your taste:
 143
 144         export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR"
 145         configure
 146
 147 C<CPPFLAGS> are the preprocessor flags.
 148
 149 the configure script is Cygnus configure, and it will accept
 150 B<--help>. If you are not root, you will probably have to make it with
 151
 152         configure --prefix=/home/me_myself_and_I/
 153
 154 In this case, you will have to set MFINPUTS, and TEXINPUTS accordingly.
 155
 156 If you want to install GNU LilyPond in F</usr/local>, and your TeX has
 157 no default hooks for local stuff (mine is broken too), you can do:
 158
 159         configure --prefix=/usr/local --enable-tex-prefix=/usr/lib/texmf
 160
 161 Since GNU LilyPond currently is beta, you are advised to also use
 162
 163         --enable-debugging
 164         --enable-checking
 165
 166 other options include:
 167
 168 =over 4
 169
 170 =item --enable-shared
 171
 172 Make a shared library (gnu/linux, solaris (?) only )
 173
 174 =item --enable-printing
 175
 176 Enable debugging print routines (lilypond B<-d> option)
 177
 178 =item --enable-optimise
 179
 180 Set maximum optimisation: compile with B<-O2>
 181
 182 =item --enable-profiling
 183
 184 Compile with support for profiling
 185
 186 =item --enable-tex-prefix
 187
 188 Set the directory where TeX and Metafont live
 189
 190 =item --enable-tex-dir
 191
 192 Set then directory TeX input is in (detected as a subdir of tex-prefix)
 193
 194 =item --enable-mf-dir
 195
 196 Set the directory mf input is in (idem)
 197
 198 =item --enable-out-dir
 199
 200 Set the directory for machine generated output.
 201
 202 =back
 203
 204 All options are documented in the F<configure> help
 205 The option B<--enable-optimise> is recommended for Real Life usage.
 206
 207 If you do
 208
 209         make all
 210
 211 everything will be compiled, but nothing will be installed.  The
 212 resulting binaries can be found in the subdirectories F<out/> (which
 213 contain all files generated during compilation).
 214
 215 =head2 Building for multiple hosts
 216
 217 LilyPond does not follow the GNU standards when it comes to
 218 configuring and making Makefiles. In LilyPond, F<make> generates I<all>
 219 output in output directories (called F<out/>, by default).
 220 You can have multiple compiles from the same source-tree, by
 221 overriding the setting for the output directory.
 222
 223 Example: on my system, I do debugging and lots compiling. For this I
 224 use the configuration as follows:
 225
 226         configure --prefix=~ --enable-debugging --enable-printing --enable-checking
 227         make all
 228
 229 and I want to do profiling. For that I use
 230
 231         configure --prefix=~ --enable-debugging --disable-printing\
 232                 --disable-checking --enable-profiling --enable-optimise\
 233                 --enable-out-dir=out-profile
 234
 235         make OUTDIR_NAME=out-profile all
 236
 237 These two commands build two entirely separate versions of
 238 LilyPond. In Real Life, you would probably also want to have two
 239 different prefixes. On my machine this is no problem; I never do
 240 C<make install>. My prefix dirs are linked back to my source directory.
 241
 242
 243 =head1 INSTALLING
 244
 245 If you have done a successful C<make>, then a simple
 246
 247         make install
 248
 249 should do the trick.
 250
 251 Install the musixtex fonts in a directory which TeX and MF knows (if
 252 you are root, look for a directory which contains the directories with
 253 AMS and CM source (*.mf) files. Create a subdir lilypond or musixtex
 254 and copy the fonts into that). Do not forget to rehash TeX (if
 255 applicable)
 256
 257 Example: my fonts are in F</usr/local/lib/texfonts/musixtex/>, and I
 258 have a symlink pointing to that in
 259 F</usr/lib/texmf/texmf/fonts/source/public/>. After I copied the
 260 files, I ran "texhash"
 261
 262 =head1 CAVEATS
 263
 264 =over 5
 265
 266 =item *
 267
 268 The -O2 option to gcc triggers a gcc bug on DEC Alpha in dstream.cc. You
 269 should turn off this flag for this file.
 270
 271 =item *
 272
 273 Perl5.003 and Perl5.004 use different syntax for pod2html:
 274
 275 =back
 276
 277 =head1 EXAMPLE
 278
 279 This is what I type in my xterm:
 280
 281         lilypond someinput.ly
 282         tex lelie.tex
 283         xdvi test&
 284
 285 This is what the output looks like over here:
 286
 287         GNU LilyPond 0.0.78 #4/FlowerLib 1.1.24 #0
 288         Parsing ... [/home/hw/share/lilypond/init//
 289                 <..etc..>
 290                 init//performer.ly]]][input/kortjakje.ly]
 291         Creating elements ...[8][16][24][25]
 292         Preprocessing elements...
 293         Calculating column positions ... [14][25]
 294         Postprocessing elements...
 295         TeX output to lelie.tex ...
 296         Creating MIDI elements ...MIDI output to lelie.midi ...
 297
 298
 299         hw:~/musix/spacer$ xdvi lelie&
 300         [1] 855
 301
 302 Check out the input files, some of them have comments
 303 Please refer to the man page for more information.
 304
 305 =head1 REDHAT LINUX
 306
 307 RedHat Linux users should be able to get a RPM. A spec file is in
 308 F<make/out/lilypond.spec>. You should be able to create an rpm as a normal
 309 user. Be sure you have a ~/.rpmrc, and edit the RPM-dir in
 310 F<Variables.make>. (If you create the RPM as a normal user the
 311 permissions will not be set correctly, unfortunately)
 312
 313
 314 =head1 DEBIAN GNU/LINUX
 315
 316 A Debian package is in the works
 317
 318
 319 =head1 WINDOWS NT/95
 320
 321 So, you're stuck with Windows, eh?  Well, don't worry, you just
 322 need (to get) Cygnus' windows32 port of gnu development stuff;
 323 have a look at http://www.cygnus.com/gnu-win32.
 324
 325 To make GNU LilyPond under, brr, aargh, shudder... windows32, well,
 326 simply type:
 327
 328         bash configure
 329         make
 330
 331 Note: If you rely on broken DOS/Windows tools such as pkzip/WinZIP
 332       to unpack the distribution, make sure the B<entire> source tree
 333       is unpacked correctly, in particular the empty out directories
 334       (F<flower/out>, F<lib/out> et. al.)
 335
 336 =head1 AUTHORS
 337
 338 Han-Wen Nienhuys <hanwen@stack.nl>
 339
 340 Jan Nieuwenhuizen <jan@digicash.com>
 341
 342
 343 Have fun!