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