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++ version 2.7 or newer (yes, 2.8 is fine).
  36
  37 =item *
  38
  39 Python
  40
  41 =back
  42
  43 =head1 RUNNING
  44
  45 GNU LilyPond does use a lot of resources. For operation you need the following:
  46
  47 =over 5
  48
  49 =item *
  50
  51 TeX
  52
  53 =item *
  54
  55 A PostScript printer and/or viewer (such as Ghostscript) is strongly
  56 recommended.  Xdvi will show all embedded PostScript too if you have
  57 Ghostscript installed.
  58
  59 =back
  60
  61 =head1 RECOMMENDED
  62
  63 Although not strictly necessary, these are recommended to have.
  64
  65 =over 5
  66
  67 =item *
  68
  69 GNU make.
  70
  71 =item *
  72
  73 Flex (version 2.5.4 or newer).
  74
  75 =item *
  76
  77 Bison (version 1.25 or newer).
  78
  79 =item *
  80
  81 Perl-5.  Most documentation was created with the perl's Plain Old
  82 Documentation. (I use 5.003)
  83
  84 =item *
  85
  86 Python.  Although perl is nice, python is better.  We will shift
  87 towards python for build scripts
  88
  89 =item *
  90
  91 GNU find
  92
  93 =item *
  94
  95 A fast computer (a full page of music typically takes 1 minute on my
  96 486/133, using the B<--enable-checking> compile. It's lot slower than
  97 most MusiXTeX preprocessors)
  98
  99 =back
 100
 101 =head1 WEBSITE
 102
 103 If you want to auto-generate Lily's website, you'll need some additional
 104 conversion tools.
 105
 106 =over 5
 107
 108 =item *
 109
 110 xpmtoppm (from the Portable Bitmap Utilities) (included within the
 111 RedHat package libgr-progs).
 112
 113 =item *
 114
 115 Bib2html (http://pertsserver.cs.uiuc.edu/~hull/bib2html.)
 116 Which, in turn depends on Man2htlm (http://askdonald.ask.uni-karlsruhe.de/
 117 hppd/hpux/Networking/WWW/Man2html-1.05) for proper installation (ugh).
 118 TeTeX users, don't forget to rerun texhash.
 119
 120 =back
 121
 122 =head1 CONFIGURING and COMPILING
 123
 124 to install GNU LilyPond, simply type:
 125
 126         configure
 127         make
 128         make install
 129
 130 This will install the following files:
 131
 132         /usr/local/man/man1/mi2mu.1
 133         /usr/local/man/man1/convert-mudela.1
 134         /usr/local/man/man1/mudela-book.1
 135         /usr/local/man/man1/lilypond.1
 136         /usr/local/lib/libflower.{so,a}
 137         /usr/local/bin/lilypond
 138         /usr/local/bin/mi2mu
 139         /usr/local/share/lilypond/*
 140         /usr/lib/texmf/texmf/tex/lilypond/*
 141
 142 The TeX include directory is detected dynamically, but it can be
 143 adjusted with B<--enable-tex-prefix> and B<--enable-tex-dir>. The
 144 above assumes that you are root and have the GNU development tools,
 145 and your make is GNU make.  If this is not the case, you can adjust
 146 your environment variables to your taste:
 147
 148         export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR"
 149         configure
 150
 151 C<CPPFLAGS> are the preprocessor flags.
 152
 153 the configure script is Cygnus configure, and it will accept
 154 B<--help>. If you are not root, you will probably have to make it with
 155
 156         configure --prefix=/home/me_myself_and_I/
 157
 158 In this case, you will have to set MFINPUTS, and TEXINPUTS accordingly.
 159
 160 If you want to install GNU LilyPond in F</usr/local>, and your TeX has
 161 no default hooks for local stuff (mine is broken too), you can do:
 162
 163         configure --prefix=/usr/local --enable-tex-prefix=/usr/lib/texmf
 164
 165 Since GNU LilyPond currently is beta, you are advised to also use
 166
 167         --enable-debugging
 168         --enable-checking
 169
 170 other options include:
 171
 172 =over 4
 173
 174 =item B<--enable-shared>
 175
 176 Make a shared library (gnu/linux, solaris (?) only )
 177
 178 =item B<--enable-printing>
 179
 180 Enable debugging print routines (lilypond B<-d> option)
 181
 182 =item B<--enable-optimise>
 183
 184 Set maximum optimisation: compile with B<-O2>
 185
 186 =item B<--enable-profiling>
 187
 188 Compile with support for profiling
 189
 190 =item B<--enable-tex-prefix>
 191
 192 Set the directory where TeX and Metafont live
 193
 194 =item B<--enable-tex-dir>
 195
 196 Set then directory TeX input is in (detected as a subdir of
 197 tex-prefix).  This should be a directory that is reachable both for
 198 tex and latex.  On my system the best choice would be
 199 F</usr/lib/texmf/texmf/tex/generic//>.
 200
 201 =item B<--enable-mf-dir>
 202
 203 Set the directory mf input is in (idem).   On my system the best
 204 choice would be F</usr/lib/texmf/texmf/fonts/source/public/>.
 205
 206 =item B<--enable-config>
 207
 208 Output to different configuration files.  Needed for multi-platform
 209 builds
 210
 211
 212 =back
 213
 214 All options are documented in the F<configure> help
 215 The option B<--enable-optimise> is recommended for Real Life usage.
 216
 217 If you do
 218
 219         make all
 220
 221 everything will be compiled, but nothing will be installed.  The
 222 resulting binaries can be found in the subdirectories F<out/> (which
 223 contain all files generated during compilation).
 224
 225 =head1 CONFIGURING FOR MULTIPLE PLATFORMS
 226
 227 If you want to compile LilyPond with different configuration settings,
 228 then, you can use the B<--enable-config> option.  Example: suppose I
 229 want to build with and   without profiling.  Then I'd use the
 230 following for the normal build,
 231
 232       configure --prefix=~ --disable-optimise --enable-checking
 233       make
 234       make install
 235
 236 and for the profiling version, I specify a different configuration.
 237
 238       configure --prefix=~ --enable-profiling --enable-config=optprof --enable-optimise --disable-checking
 239       make configuration=optprof
 240       make configuration=optprof install
 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 If you are doing an upgrade, please remember to remove obsolete .pk
 252 and .tfm files of the fonts.  A script has been provided to do the
 253 work, see F<bin/clean-fonts.sh>.
 254
 255 =head1 CAVEATS
 256
 257 =over 5
 258
 259 =item *
 260
 261 The -O2 option to gcc triggers a gcc bug on DEC Alpha in dstream.cc. You
 262 should turn off this flag for this file.
 263
 264 =item *
 265
 266 Perl5.003 and Perl5.004 use different syntax for pod2html.
 267
 268 =back
 269
 270 =head1 EXAMPLE
 271
 272 This is what I type in my xterm:
 273
 274         lilypond someinput.ly
 275         tex someinput.tex
 276         xdvi someinput&
 277
 278 This is what the output looks like over here:
 279
 280         GNU LilyPond 0.0.78 #4/FlowerLib 1.1.24 #0
 281         Parsing ... [/home/hw/share/lilypond/init//
 282                 <..etc..>
 283                 init//performer.ly]]][input/kortjakje.ly]
 284         Creating elements ...[8][16][24][25]
 285         Preprocessing elements...
 286         Calculating column positions ... [14][25]
 287         Postprocessing elements...
 288         TeX output to someinput.tex ...
 289         Creating MIDI elements ...MIDI output to someinput.midi ...
 290
 291
 292         hw:~/musix/spacer$ xdvi someinput&
 293         [1] 855
 294
 295 Check out the input files, some of them have comments
 296 Please refer to the man page for more information.
 297
 298 =head1 REDHAT LINUX
 299
 300 RedHat Linux users can compile an RPM. A spec file is in
 301 F<make/out/lilypond.spec>.  You should install a gif file called
 302 F<lelie_icon.gif> along with the sources.  You can generate this gif
 303 file by typing
 304
 305      make gifs
 306
 307 in the directory F<Documentation>.
 308
 309
 310
 311 =head1 DEBIAN GNU/LINUX
 312
 313 A Debian package is also available; contact Anthony Fok
 314 <foka@debian.org>.  The build scripts are in the subdirectory debian/
 315
 316
 317 =head1 WINDOWS NT/95
 318
 319 So, you're stuck with Windows, eh?  Well, don't worry, you just
 320 need (to get) Cygnus' windows32 port of gnu development stuff;
 321 have a look at http://www.cygnus.com/gnu-win32.
 322
 323 To make GNU LilyPond under, brr, aargh, shudder... windows32, well,
 324 simply type:
 325
 326         bash configure
 327         make
 328
 329 B<Note> If you rely on broken DOS/Windows tools such as pkzip/WinZIP
 330 to unpack the distribution, make sure the B<entire> source tree
 331 is unpacked correctly, in particular the empty out directories
 332 (F<flower/out>, F<lib/out> et. al.)
 333
 334 =head1 AUTHORS
 335
 336 Han-Wen Nienhuys <hanwen@cs.ruu.nl>
 337
 338 Jan Nieuwenhuizen <jan@digicash.com>
 339
 340
 341 Have fun!