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 IMPORTANT
  10
  11 if you have downloaded a
  12
  13         *.pre*
  14
  15 version, then this is version is I<not> meant for producing nice
  16 output, but to keep your patchsets up to date.  It might not even compile.
  17
  18 =head1 PREREQUISITES
  19
  20 For compilation you need.
  21
  22 =over 5
  23
  24 =item *
  25
  26 A Unix system with GNU tools. GNU LilyPond is known to run on these
  27 unices: Linux, AIX, Digital Unix and Solaris.
  28
  29 If you have the Cygnus WINDOWS32 port of the GNU utils, it will even
  30 work in Windows NT/95, but don't promise to support it.
  31
  32 =item *
  33
  34 GNU C++ v2.7 or better, with libg++ installed.  Version 2.7.2
  35 or better recommended.
  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 RECOMMENDED
  52
  53 =over 5
  54
  55 =item *
  56
  57 Perl.  Most scripts are written in Perl. The documentation was created
  58 with the perl's Plain Old Documentation.
  59
  60 =item *
  61
  62 (GNU) find
  63
  64 =back
  65
  66 =head1 CONFIGURING and COMPILING
  67
  68 to install GNU LilyPond, simply type:
  69
  70         configure
  71         make install
  72
  73 This will install the following files:
  74
  75         /usr/local/man/man1/mi2mu.1
  76         /usr/local/man/man5/mudela.5
  77         /usr/local/man/man1/lilypond.1
  78         /usr/local/lib/libflower.{so,a}
  79         /usr/local/bin/lilypond
  80         /usr/local/bin/mi2mu
  81         /usr/local/share/lilypond/*
  82         /usr/lib/texmf/texmf/tex/lilypond/*
  83         /usr/lib/texmf/texmf/fonts/source/lilypond/*
  84
  85 The TeX include directory is detected dynamically, but it can be
  86 adjusted with B<--enable-tex-prefix> and B<--enable-tex-dir>. The
  87 above assumes that you are root and have the gnu development tools,
  88 and your make is gnu make.  If this is not the case, you can adjust
  89 your environment variables to your taste:
  90
  91         export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR"
  92         configure
  93
  94 C<CPPFLAGS> are the preprocessor flags.
  95
  96 the configure script is Cygnus configure, and it will accept
  97 B<--help>. If you are not root, you will probably have to make it with
  98
  99         configure --prefix=/home/me_myself_and_I/
 100
 101 In this case, you will have to set MFINPUTS, and TEINPUTS accordingly.
 102
 103 If you want to install GNU LilyPond in F</usr/local>, and your TeX has
 104 no default hooks for local stuff (mine is broken too), you can do:
 105
 106         configure --prefix=/usr/local --enable-tex-prefix=/usr/lib/texmf
 107
 108 Since GNU LilyPond currently is beta, you are advised to also use
 109
 110         --enable-debugging
 111         --enable-checking
 112
 113 other options include:
 114
 115 =over 4
 116
 117 =item --enable-shared
 118
 119 Make a shared library (gnu/linux, solaris (?) only )
 120
 121 =item   --enable-printing
 122
 123 Enable debugging print routines (lilypond B<-d> option)
 124
 125 =item   --enable-optimise
 126
 127 Set maximum optimisation
 128
 129 =item   --enable-profiling
 130
 131 Compile with support for profiling
 132
 133 =item   --enable-tex-prefix
 134
 135 Set the directory where texmf lives
 136
 137 =item --enable-tex-dir
 138
 139 Set then directory tex input is in (detected as a subdir of tex-prefix)
 140
 141 =item --enable-mf-dir
 142
 143 Set then directory tex input is in (idem)
 144
 145 =back
 146
 147 All options are documented in the F<configure> help
 148 The option B<--enable-optimise> is recommended for Real Life usage.
 149
 150 If you do
 151
 152         make all
 153
 154 everything will be compiled, but nothing will be installed.  The
 155 resulting binaries can be found in the subdirectories F<out/> (which
 156 contain all files generated during compilation).
 157
 158
 159 =head1 INSTALLING
 160
 161 If you have done a successful C<make>, then a simple
 162
 163         make install
 164
 165 should do the trick.
 166
 167 [todo. Obsolete; fonts are in distribution now.]
 168
 169 Install the musixtex fonts in a directory which TeX and MF knows (if
 170 you are root, look for a directory which contains the directories with
 171 AMS and CM source (*.mf) files. Create a subdir lilypond or musixtex
 172 and copy the fonts into that). Do not forget to rehash TeX (if
 173 applicable)
 174
 175 Example: my fonts are in F</usr/local/lib/texfonts/musixtex/>, and I
 176 have a symlink pointing to that in
 177 F</usr/lib/texmf/texmf/fonts/source/public/>
 178
 179 =head1 CAVEATS
 180
 181
 182
 183 =over 5
 184
 185 =item *
 186
 187 The -O2 option to gcc triggers a gcc bug on DEC Alpha in dstream.cc. You
 188 should turn off this flag for this file.
 189
 190 =back
 191
 192 =head1 RUNNING
 193
 194 GNU LilyPond does use a lot of resources. For operation you need the following:
 195
 196
 197 =over 5
 198
 199 =item *
 200
 201 A fast computer (a full page of music typically takes 1 minute
 202 on my 486/66, using the B<--enable-checking> compile. It's lot slower
 203 than most MusiXTeX preprocessors)
 204
 205 =item *
 206
 207 TeX
 208
 209 =item *
 210
 211 The MusixTeX fonts (I included those found in MusixTeX T.73). Beware,
 212 the clef symbol has changed position in the Egler version,
 213 a.k.a. OpusTeX)
 214
 215 =back
 216
 217 At this time, GNU LilyPond output looks nice, but is not of production
 218 quality. If you're not discouraged; this is what I type in my xterm:
 219
 220         lilypond someinput.ly
 221         tex lelie.tex
 222         xdvi test&
 223
 224 This is what the output looks like over here:
 225
 226         hw:~/musix/spacer$ lilypond input/kortjakje.ly
 227         GNU LilyPond 0.0.71 #20/FlowerLib 1.1.20 #0
 228         Parsing ... [/home/hw/share/lilypond/init//symbol.ini  <..snip..>
 229         ..      .ini]][input/kortjakje.ly]
 230         Creating elements ...
 231         Preprocessing elements...
 232         Calculating column positions ... [3][8][13][17][21][25]
 233         Postprocessing elements...
 234         TeX output to lelie.tex ...
 235
 236         hw:~/musix/spacer$ tex lelie
 237         This is TeX, Version 3.14159 (C version 6.1)
 238         (lelie.tex
 239         Hyphenation patterns for english, dutch, german, loaded.
 240         (/home/hw/lib/texmf/tex/lilypond/lilyponddefs.tex) [1] )
 241         Output written on lelie.dvi (1 page, 8944 bytes).
 242         Transcript written on lelie.log.
 243
 244         hw:~/musix/spacer$ xdvi lelie&
 245         [1] 855
 246
 247 Check out the input files, some of them have comments
 248 Please refer to the man page for more information.
 249
 250 =head1 REDHAT LINUX
 251
 252 RedHat Linux users should be able to get a RPM. A spec file is in
 253 F<make/lilypond.spec>. You should be able to create an rpm as a normal
 254 user. Be sure you have a ~/.rpmrc, and edit the RPM-dir in
 255 F<Variables.make>
 256
 257
 258 =head1 WINDOZE
 259
 260 Windows NT:
 261
 262 you need the cygnus windows32 gnu port development stuff; have a look
 263 at http://www.cygnus.com/gnu-win32.
 264
 265 to make GNU LilyPond under, brr, aargh, well, simply type:
 266
 267         bash configure
 268         make windows32
 269
 270 =head1 PLATFORMS
 271
 272 GNU LilyPond (pl 0.0.39) is known to compile on the following platforms:
 273
 274 Unix:
 275
 276         * gnu/linux 2.0.x, g++ 2.7.2[.1]
 277         * aix 4.1, g++ 2.7.2
 278         * solaris 2.5, g++ 2.7.2
 279
 280 Other:
 281
 282         * windows-nt 4.0, cygnus gnu-windows32 beta17.1 (~=g++ 2.7.2)
 283         * gnu/linux 2.0.28 X to doze, gcc-go32 (~=g++ 2.7.2) [exec. untested]
 284
 285 =head1 AUTHORS
 286
 287 Han-Wen Nienhuys <hanwen@stack.nl>
 288
 289 Jan Nieuwenhuizen <jan@digicash.com>
 290
 291
 292 Have fun!