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 the directory mf input is in (idem) [obsolete]
 192
 193 =item --enable-out-dir
 194
 195 Set the directory for machine generated output.
 196
 197 =back
 198
 199 All options are documented in the F<configure> help
 200 The option B<--enable-optimise> is recommended for Real Life usage.
 201
 202 If you do
 203
 204         make all
 205
 206 everything will be compiled, but nothing will be installed.  The
 207 resulting binaries can be found in the subdirectories F<out/> (which
 208 contain all files generated during compilation).
 209
 210 =head2 Building for multiple hosts
 211
 212 LilyPond does not follow the GNU standards when it comes to
 213 configuring and making Makefiles. In LilyPond, F<make> generates I<all>
 214 output in output directories (called F<out/>, by default).
 215 You can have multiple compiles from the same source-tree, by
 216 overriding the setting for the output directory.
 217
 218 Example: on my system, I do debugging and lots compiling. For this I
 219 use the configuration as follows:
 220
 221         configure --prefix=~ --enable-debugging --enable-printing --enable-checking
 222         make all
 223
 224 and I want to do profiling. For that I use
 225
 226         configure --prefix=~ --enable-debugging --disable-printing\
 227                 --disable-checking --enable-profiling --enable-optimise\
 228                 --enable-out-dir=out-profile
 229
 230         make OUTDIR_NAME=out-profile all
 231
 232 These two commands build two entirely separate versions of
 233 LilyPond. In Real Life, you would probably also want to have two
 234 different prefixes. On my machine this is no problem; I never do
 235 C<make install>. My prefix dirs are linked back to my source directory.
 236
 237
 238 =head1 INSTALLING
 239
 240 If you have done a successful C<make>, then a simple
 241
 242         make install
 243
 244 should do the trick.
 245
 246 Install the musixtex fonts in a directory which TeX and MF knows (if
 247 you are root, look for a directory which contains the directories with
 248 AMS and CM source (*.mf) files. Create a subdir lilypond or musixtex
 249 and copy the fonts into that). Do not forget to rehash TeX (if
 250 applicable)
 251
 252 Example: my fonts are in F</usr/local/lib/texfonts/musixtex/>, and I
 253 have a symlink pointing to that in
 254 F</usr/lib/texmf/texmf/fonts/source/public/>. After I copied the
 255 files, I ran "texhash"
 256
 257 =head1 CAVEATS
 258
 259 =over 5
 260
 261 =item *
 262
 263 The -O2 option to gcc triggers a gcc bug on DEC Alpha in dstream.cc. You
 264 should turn off this flag for this file.
 265
 266 =item *
 267
 268 Perl5.003 and Perl5.004 use different syntax for pod2html:
 269
 270 =back
 271
 272 =head1 EXAMPLE
 273
 274 This is what I type in my xterm:
 275
 276         lilypond someinput.ly
 277         tex lelie.tex
 278         xdvi test&
 279
 280 This is what the output looks like over here:
 281
 282         GNU LilyPond 0.0.78 #4/FlowerLib 1.1.24 #0
 283         Parsing ... [/home/hw/share/lilypond/init//
 284                 <..etc..>
 285                 init//performer.ly]]][input/kortjakje.ly]
 286         Creating elements ...[8][16][24][25]
 287         Preprocessing elements...
 288         Calculating column positions ... [14][25]
 289         Postprocessing elements...
 290         TeX output to lelie.tex ...
 291         Creating MIDI elements ...MIDI output to lelie.midi ...
 292
 293
 294         hw:~/musix/spacer$ xdvi lelie&
 295         [1] 855
 296
 297 Check out the input files, some of them have comments
 298 Please refer to the man page for more information.
 299
 300 =head1 REDHAT LINUX
 301
 302 RedHat Linux users should be able to get a RPM. A spec file is in
 303 F<make/out/lilypond.spec>. You should be able to create an rpm as a normal
 304 user. Be sure you have a ~/.rpmrc, and edit the RPM-dir in
 305 F<Variables.make>. (If you create the RPM as a normal user the
 306 permissions will not be set correctly, unfortunately)
 307
 308
 309 =head1 DEBIAN GNU/LINUX
 310
 311 A Debian package is in the works
 312
 313
 314 =head1 WINDOZE
 315
 316 Windows NT:
 317
 318 you need the cygnus windows32 gnu port development stuff; have a look
 319 at http://www.cygnus.com/gnu-win32.
 320
 321 to make GNU LilyPond under, brr, aargh, shudder.. windows32, well,
 322 simply type:
 323
 324         bash configure
 325         make windows32
 326
 327 =head1 AUTHORS
 328
 329 Han-Wen Nienhuys <hanwen@stack.nl>
 330
 331 Jan Nieuwenhuizen <jan@digicash.com>
 332
 333
 334 Have fun!