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