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
 102 =head1 CONFIGURING and COMPILING
 103
 104 to install GNU LilyPond, simply type:
 105
 106         configure
 107         make
 108         make install
 109
 110 This will install the following files:
 111
 112         /usr/local/man/man1/mi2mu.1
 113         /usr/local/man/man1/convert-mudela.1
 114         /usr/local/man/man1/mudela-book.1
 115         /usr/local/man/man1/lilypond.1
 116         /usr/local/lib/libflower.{so,a}
 117         /usr/local/bin/lilypond
 118         /usr/local/bin/mi2mu
 119         /usr/local/share/lilypond/*
 120         /usr/lib/texmf/texmf/tex/lilypond/*
 121
 122 The TeX include directory is detected dynamically, but it can be
 123 adjusted with B<--enable-tex-prefix> and B<--enable-tex-dir>. The
 124 above assumes that you are root and have the GNU development tools,
 125 and your make is GNU make.  If this is not the case, you can adjust
 126 your environment variables to your taste:
 127
 128         export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR"
 129         configure
 130
 131 C<CPPFLAGS> are the preprocessor flags.
 132
 133 the configure script is Cygnus configure, and it will accept
 134 B<--help>. If you are not root, you will probably have to make it with
 135
 136         configure --prefix=/home/me_myself_and_I/
 137
 138 In this case, you will have to set MFINPUTS, and TEXINPUTS accordingly.
 139
 140 If you want to install GNU LilyPond in F</usr/local>, and your TeX has
 141 no default hooks for local stuff (mine is broken too), you can do:
 142
 143         configure --prefix=/usr/local --enable-tex-prefix=/usr/lib/texmf
 144
 145 Since GNU LilyPond currently is beta, you are advised to also use
 146
 147         --enable-debugging
 148         --enable-checking
 149
 150 other options include:
 151
 152 =over 4
 153
 154 =item B<--enable-shared>
 155
 156 Make a shared library (gnu/linux, solaris (?) only )
 157
 158 =item B<--enable-printing>
 159
 160 Enable debugging print routines (lilypond B<-d> option)
 161
 162 =item B<--enable-optimise>
 163
 164 Set maximum optimisation: compile with B<-O2>
 165
 166 =item B<--enable-profiling>
 167
 168 Compile with support for profiling
 169
 170 =item B<--enable-tex-prefix>
 171
 172 Set the directory where TeX and Metafont live
 173
 174 =item B<--enable-tex-dir>
 175
 176 Set then directory TeX input is in (detected as a subdir of
 177 tex-prefix).  This should be a directory that is reachable both for
 178 tex and latex.  On my system the best choice would be
 179 F</usr/lib/texmf/texmf/tex/generic//>.
 180
 181 =item B<--enable-mf-dir>
 182
 183 Set the directory mf input is in (idem).   On my system the best
 184 choice would be F</usr/lib/texmf/texmf/fonts/source/public/>.
 185
 186 =item B<--enable-config>
 187
 188 Output to different configuration files.  Needed for multi-platform
 189 builds
 190
 191
 192 =back
 193
 194 All options are documented in the F<configure> help
 195 The option B<--enable-optimise> is recommended for Real Life usage.
 196
 197 If you do
 198
 199         make all
 200
 201 everything will be compiled, but nothing will be installed.  The
 202 resulting binaries can be found in the subdirectories F<out/> (which
 203 contain all files generated during compilation).
 204
 205 =head1 CONFIGURING FOR MULTIPLE PLATFORMS
 206
 207 If you want to compile LilyPond with different configuration settings,
 208 then, you can use the B<--enable-config> option.  Example: suppose I
 209 want to build with and   without profiling.  Then I'd use the
 210 following for the normal build,
 211
 212       configure --prefix=~ --disable-optimise --enable-checking
 213       make
 214       make install
 215
 216 and for the profiling version, I specify a different configuration.
 217
 218       configure --prefix=~ --enable-profiling --enable-config=optprof --enable-optimise --disable-checking
 219       make configuration=optprof
 220       make configuration=optprof install
 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 If you are doing an upgrade, please remember to remove obsolete .pk
 232 and .tfm files of the fonts.  A script has been provided to do the
 233 work, see F<bin/clean-fonts.sh>.
 234
 235 =head1 CAVEATS
 236
 237 =over 5
 238
 239 =item *
 240
 241 The -O2 option to gcc triggers a gcc bug on DEC Alpha in dstream.cc. You
 242 should turn off this flag for this file.
 243
 244 =item *
 245
 246 Perl5.003 and Perl5.004 use different syntax for pod2html.
 247
 248 =back
 249
 250 =head1 EXAMPLE
 251
 252 This is what I type in my xterm:
 253
 254         lilypond someinput.ly
 255         tex someinput.tex
 256         xdvi someinput&
 257
 258 This is what the output looks like over here:
 259
 260         GNU LilyPond 0.0.78 #4/FlowerLib 1.1.24 #0
 261         Parsing ... [/home/hw/share/lilypond/init//
 262                 <..etc..>
 263                 init//performer.ly]]][input/kortjakje.ly]
 264         Creating elements ...[8][16][24][25]
 265         Preprocessing elements...
 266         Calculating column positions ... [14][25]
 267         Postprocessing elements...
 268         TeX output to someinput.tex ...
 269         Creating MIDI elements ...MIDI output to someinput.midi ...
 270
 271
 272         hw:~/musix/spacer$ xdvi someinput&
 273         [1] 855
 274
 275 Check out the input files, some of them have comments
 276 Please refer to the man page for more information.
 277
 278 =head1 REDHAT LINUX
 279
 280 RedHat Linux users can compile an RPM. A spec file is in
 281 F<make/out/lilypond.spec>.  You should install a gif file called
 282 F<lelie_icon.gif> along with the sources.  You can generate this gif
 283 file by typing
 284
 285      make gifs
 286
 287 in the directory F<Documentation>.
 288
 289
 290
 291 =head1 DEBIAN GNU/LINUX
 292
 293 A Debian package is also available; contact Anthony Fok
 294 <foka@debian.org>.  The build scripts are in the subdirectory debian/
 295
 296
 297 =head1 WINDOWS NT/95
 298
 299 So, you're stuck with Windows, eh?  Well, don't worry, you just
 300 need (to get) Cygnus' windows32 port of gnu development stuff;
 301 have a look at http://www.cygnus.com/gnu-win32.
 302
 303 To make GNU LilyPond under, brr, aargh, shudder... windows32, well,
 304 simply type:
 305
 306         bash configure
 307         make
 308
 309 B<Note> If you rely on broken DOS/Windows tools such as pkzip/WinZIP
 310 to unpack the distribution, make sure the B<entire> source tree
 311 is unpacked correctly, in particular the empty out directories
 312 (F<flower/out>, F<lib/out> et. al.)
 313
 314 =head1 AUTHORS
 315
 316 Han-Wen Nienhuys <hanwen@cs.ruu.nl>
 317
 318 Jan Nieuwenhuizen <jan@digicash.com>
 319
 320
 321 Have fun!