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