Documentation/topdocs/INSTALL.texi

   1 \input texinfo @c -*-texinfo-*-
   2 @setfilename INSTALL.info
   3 @settitle INSTALL - compiling and installing GNU LilyPond
   4
   5 @node Top, , , (dir)
   6 @top
   7 @menu
   8 * INSTALL - compiling and installing GNU LilyPond::INSTALL - compiling and installing GNU LilyPond
   9 @end menu
  10
  11
  12 @node INSTALL - compiling and installing GNU LilyPond, abstract, , Top
  13 @menu
  14 * abstract::                      abstract
  15 * obtaining::                     obtaining
  16 * PREREQUISITES::                 PREREQUISITES
  17 * running::                       running
  18 * WEBSITE::                       WEBSITE
  19 * CONFIGURING and COMPILING::     CONFIGURING and COMPILING
  20 * CONFIGURING FOR MULTIPLE PLATFORMS::CONFIGURING FOR MULTIPLE PLATFORMS
  21 * INSTALLING::                    INSTALLING
  22 * REDHAT LINUX::                  REDHAT LINUX
  23 * DEBIAN GNU/LINUX::              DEBIAN GNU/LINUX
  24 * WINDOWS NT/95::                 WINDOWS NT/95
  25 * w32::                           w32
  26 * BUGS::                          BUGS
  27 * AUTHORS::                       AUTHORS
  28 @end menu
  29 @chapter INSTALL - compiling and installing GNU LilyPond
  30
  31
  32 @node abstract, obtaining, INSTALL - compiling and installing GNU LilyPond, INSTALL - compiling and installing GNU LilyPond
  33 @section abstract
  34
  35 TODO: document xdeltas
  36
  37 This document explains what you need to install LilyPond, and what you
  38 should do.  If you are going to compile and install LilyPond often,
  39 e.g. when doing development, you might want to check out the
  40 @file{buildscripts/set-lily.sh} script.  It sets some environment
  41 variables and symlinks, which comes in handly when you have to compile
  42 LilyPond more often.
  43
  44 @node obtaining, PREREQUISITES, abstract, INSTALL - compiling and installing GNU LilyPond
  45 @section obtaining
  46
  47 You can get the latest version of LilyPond at
  48 @url{ ftp://ftp.cs.uu.nl/pub/GNU/LilyPond/}.  Refer to the links
  49 document for mirror sites.
  50
  51 @emph{If you upgrade by patching do remember to rerun autoconf after
  52 applying the patch}.
  53
  54 @node PREREQUISITES, running, obtaining, INSTALL - compiling and installing GNU LilyPond
  55 @section PREREQUISITES
  56
  57 For compilation you need:
  58
  59 @itemize @bullet
  60 @item A GNU system: GNU LilyPond is known to run on these GNU systems: Linux
  61     (PPC, intel), FreeBSD, AIX, NeXTStep, IRIX, Digital Unix and
  62 Solaris.
  63
  64 @item Lots of disk space: LilyPond takes between 30 and 100 mb to
  65 compile if you use debugging information.  If you are short on
  66 disk-space run configure with @code{--disable-debugging}.
  67
  68 Although we recommend to use Unix, LilyPond is known to run on Windows
  69 NT/95/98 as well.  See Section @xref{w32}.
  70
  71 @item  EGCS 1.1 or newer. Check out @url{ ftp://ftp.gnu.org/pub/gcc/}
  72
  73 @item  Python 1.5,
  74 Check out
  75 @url{ftp://ftp.python.org} or @url{ftp://ftp.cwi.nl/pub/python}.
  76
  77 @item  GUILE 1.3,  check out @url{http://www.gnu.org/software/guile/guile.html}.
  78
  79 @item GNU make.
  80 Check out @url{ftp://ftp.gnu.org/make/}.
  81
  82 @item Flex (version 2.5.4 or newer).
  83 Check out @url{ftp://ftp.gnu.org/flex/}.
  84
  85 @item Bison (version 1.25 or newer).
  86 Check out @url{ftp://ftp.gnu.org/bison/}.
  87
  88 @item Texinfo. Check out @url{ftp://ftp.gnu.org/pub/texinfo/}.
  89 Most documentation is in texinfo.
  90
  91 @item The geometry package for LaTeX is needed to use ly2dvi.
  92 Available at
  93 @url{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry}
  94 or at mirror site @url{ftp://ftp.dante.de}
  95
  96 @item MetaPost, if you want to use direct PostScript output. Please
  97 note  that  tetex-0.4pl8 (included with Redhat 5.x) does not include
  98 @file{mfplain.mp}, which is needed  for producing the scaleable font files.
  99
 100 @end itemize
 101
 102 @node running, WEBSITE, PREREQUISITES, INSTALL - compiling and installing GNU LilyPond
 103 @section running
 104
 105 GNU LilyPond does use a lot of resources. For operation you need the
 106 following software
 107
 108 @itemize @bullet
 109 @item TeX
 110 @item A PostScript printer and/or viewer (such as Ghostscript) is strongly
 111     recommended.  Xdvi will show all embedded PostScript too if you have
 112     Ghostscript installed.
 113 @item  GUILE 1.3, check out @url{http://www.gnu.org/programs/guile.html}
 114 @end itemize
 115
 116 For running LilyPond successfully you have to help TeX and MetaFont
 117 find various files.  The recommended way of doing so is adjusting the
 118 environment variables in the start-up scripts of your shell.  An
 119 example is given here for the Bourne shell:
 120 @example
 121 export MFINPUTS="/usr/local/share/lilypond/mf:"
 122 export TEXINPUTS="/usr/local/share/lilypond/tex:/usr/local/share/lilypond/ps:"
 123
 124 @end example
 125
 126 The empty path component
 127 represents TeX and MetaFont's default search paths.  Scripts with
 128 the proper paths for the bourne and C-shell respectively are generated in
 129 @file{buildscripts/out/lilypond-profile} and
 130 @file{buildscripts/out/lilypond-login} during compilation.
 131
 132 LilyPond is a hiddeously big, slow and bloated program.  A fast CPU
 133 and plenty of RAM is recommended for comfortable use.
 134
 135 @node WEBSITE, CONFIGURING and COMPILING, running, INSTALL - compiling and installing GNU LilyPond
 136 @section WEBSITE
 137
 138 The website is the most convenient form to use for reading the
 139 documentation on-line documentation. It is made by entering @example
 140
 141   make website
 142
 143 @end example
 144 This does require a fully functioning
 145
 146 If you want to auto-generate Lily's website, you'll need some additional
 147 conversion tools.
 148
 149 @itemize @bullet
 150 @item xpmtoppm (from the Portable Bitmap Utilities) (For RedHat Linux
 151              users: it is included within the package libgr-progs).
 152         the original is at
 153 @url{ftp://ftp.x.org/contrib/utilities/netpbm-1mar1994.p1.tar.gz}
 154
 155 @item pnmtopng, which is also in libgr-progs for RedHat. The original is
 156 at
 157 @url{ftp://swrinde.nde.swri.edu/pub/png/applications/pnmtopng-2.37.2.tar.gz}.i
 158
 159 The version of @file{pnmtopng} that is distributed with RedHat 5.1 and
 160 5.2 contains a bug: pnmtopng is dynamically linked to the wrong
 161 version of libpng, which results in cropped images.  Recompile it from
 162 source, and make sure that the pnmtopng binary is linked statically to
 163 the libpng that is included in libgr.  RedHat 6.0 does not have this
 164 problem.
 165
 166 @example
 167  tar xzf libgr-2.0.13.tar.gz
 168       make
 169       cd png
 170       rm libpng.so*
 171       make pnmtopng
 172
 173 @end example
 174
 175 You can then install the new pnmtopng into @file{/usr/local/bin/}
 176
 177 @item Bib2html @url{http://pertsserver.cs.uiuc.edu/~hull/bib2html.}
 178     Which, in turn depends on man2html for proper installation.
 179 man2html can be had from @url{http://askdonald.ask.uni-karlsruhe.de/hppd/hpux/Networking/WWW/Man2html-1.05}.
 180
 181 The website will build without this utility, but you will not see our
 182 hypertextified bibliography.
 183
 184 @item Doc++ (optional) to read the source code.
 185
 186 @end itemize
 187
 188 You also have to install @file{buildscripts/out/ps-to-gifs} in a
 189 directory that is in the path.
 190
 191 @node CONFIGURING and COMPILING, CONFIGURING FOR MULTIPLE PLATFORMS, WEBSITE, INSTALL - compiling and installing GNU LilyPond
 192 @section CONFIGURING and COMPILING
 193
 194 to install GNU LilyPond, simply type:
 195 @example
 196
 197         gunzip -c lilypond-x.y.z | tar xf -
 198         cd lilypond-x.y.z
 199         ./configure             # fill in your standard prefix with --prefix
 200         make
 201         make install
 202
 203 @end example
 204
 205 This will install a number of files, something close to:
 206 @example
 207
 208         /usr/local/man/man1/mi2mu.1
 209         /usr/local/man/man1/convert-mudela.1
 210         /usr/local/man/man1/mudela-book.1
 211         /usr/local/man/man1/lilypond.1
 212         /usr/local/bin/lilypond
 213         /usr/local/bin/mi2mu
 214         /usr/local/share/lilypond/*
 215         /usr/local/share/locale/@{it,nl@}/LC_MESSAGES/lilypond.mo
 216
 217 @end example
 218
 219
 220 The above assumes that you are root and have the GNU development
 221 tools, and your make is GNU make.  If this is not the case, you can
 222 adjust your environment variables to your taste:
 223
 224 @example
 225
 226         export CPPFLAGS="-I /home/me/my_include -DWEIRD_FOOBAR"
 227         ./configure
 228
 229 @end example
 230
 231 @code{CPPFLAGS} are the preprocessor flags.
 232
 233 The configure script is Cygnus configure, and it will accept
 234 @strong{--help}. If you are not root, you will probably have to make it
 235 with a different @strong{--prefix} option.  Our favourite location is
 236
 237 @example
 238
 239         ./configure --prefix=$HOME/usr
 240
 241 @end example
 242
 243 In this case, you will have to set up MFINPUTS, and TEXINPUTS accordingly.
 244
 245 Since GNU LilyPond currently is beta, you are advised to also use
 246
 247 @example
 248
 249         --enable-debugging
 250         --enable-checking
 251
 252 @end example
 253
 254 Options to configure include:
 255
 256 @table @samp
 257 @item @strong{--enable-printing}
 258     Enable debugging print routines (lilypond @strong{-D} option)
 259 @item @strong{--enable-optimise}
 260     Set maximum optimisation: compile with @strong{-O2}.  This can be
 261 unreliable on some compiler/platform combinations (eg, DEC Alpha and PPC)
 262 @item @strong{--enable-profiling}
 263     Compile with support for profiling.
 264 @item @strong{--enable-config}
 265     Output to a different configuration file.  Needed for multi-platform
 266     builds
 267 @end table
 268
 269 All options are documented in the @file{configure} help
 270 The option @strong{--enable-optimise} is recommended for Real Life usage.
 271
 272 If you do
 273
 274 @example
 275
 276         make all
 277
 278 @end example
 279
 280 everything will be compiled, but nothing will be installed.  The
 281 resulting binaries can be found in the subdirectories @file{out/} (which
 282 contain all files generated during compilation).
 283
 284 @node CONFIGURING FOR MULTIPLE PLATFORMS, INSTALLING, CONFIGURING and COMPILING, INSTALL - compiling and installing GNU LilyPond
 285 @section CONFIGURING FOR MULTIPLE PLATFORMS
 286
 287 If you want to compile LilyPond with different configuration settings,
 288 then, you can use the @strong{--enable-config} option.  Example: suppose I
 289 want to build with and   without profiling.  Then I'd use the
 290 following for the normal build,
 291
 292 @example
 293
 294       ./configure --prefix=~ --disable-optimise --enable-checking
 295       make
 296       make install
 297
 298 @end example
 299
 300 and for the profiling version, I specify a different configuration.
 301
 302 @example
 303
 304       ./configure --prefix=~ --enable-profiling --enable-config=optprof --enable-optimise --disable-checking
 305       make config=optprof
 306       make config=optprof install
 307
 308 @end example
 309
 310
 311 @node INSTALLING, REDHAT LINUX, CONFIGURING FOR MULTIPLE PLATFORMS, INSTALL - compiling and installing GNU LilyPond
 312 @section INSTALLING
 313
 314 If you have done a successful @code{make}, then a simple
 315
 316 @example
 317
 318         make install
 319
 320 @end example
 321
 322 should do the trick.
 323
 324 If you are doing an upgrade, please remember to remove obsolete
 325 @file{.pk} and @file{.tfm} files of the fonts.  A script has been
 326 provided to do the work for you, see @file{bin/clean-fonts.sh}.
 327
 328 @unnumberedsec CAVEATS
 329
 330
 331 @itemize @bullet
 332 @item The -O2 option  triggers  bugs on various platforms (PowerPC, Alpha).
 333     If you experience problems, you  should first try  turning off
 334     this.
 335 @item  On PPC you need at least EGCS-1.1.2f.
 336 @end itemize
 337
 338 @node REDHAT LINUX, DEBIAN GNU/LINUX, INSTALLING, INSTALL - compiling and installing GNU LilyPond
 339 @section REDHAT LINUX
 340
 341 RedHat Linux users can compile an RPM. A spec file is in
 342 @file{make/out/lilypond.spec}, it is distributed along with the
 343 sources.
 344
 345 You can make the rpm by issuing
 346 @example
 347
 348         rpm -tb lilypond-x.y.z.tar.gz
 349         rpm -i /usr/src/redhat/RPMS/i386/lilypond-x.y.z
 350
 351 @end example
 352
 353 Precompiled i386 RedHat RPMS are available from
 354 @url{ftp://freshmeat.net/pub/rpms/lilypond/} and
 355 @url{http://linux.umbc.edu/software/lilypond/rpms/}.
 356
 357 For compilation on a RedHat system you need these packages,
 358 in addition to the those needed for running:
 359 @itemize @bullet
 360 @item glibc-devel
 361 @item libstdc++-devel
 362 @item guile-devel
 363 @item flex
 364 @item bison
 365 @item texinfo
 366 @end itemize
 367
 368 @node DEBIAN GNU/LINUX, WINDOWS NT/95, REDHAT LINUX, INSTALL - compiling and installing GNU LilyPond
 369 @section DEBIAN GNU/LINUX
 370
 371 A Debian package is also available; contact Anthony Fok
 372 @email{foka@@debian.org}.  The build scripts are in the subdirectory
 373 @file{debian/}.
 374
 375 @node WINDOWS NT/95, w32, DEBIAN GNU/LINUX, INSTALL - compiling and installing GNU LilyPond
 376 @section WINDOWS NT/95
 377 @node w32, BUGS, WINDOWS NT/95, INSTALL - compiling and installing GNU LilyPond
 378
 379
 380 Separate instructions on building for W32 are available
 381 @url{../../outdir/README-W32.html}.
 382
 383 @node BUGS, AUTHORS, w32, INSTALL - compiling and installing GNU LilyPond
 384 @section BUGS
 385
 386 Send bug reports to bug-gnu-music@@gnu.org.  For help and questions use
 387 help-gnu-music@@gnu.org and gnu-music-discuss@@gnu.org.  Please consult
 388 the faq before mailing your problems.
 389
 390 @node AUTHORS, Top, BUGS, INSTALL - compiling and installing GNU LilyPond
 391 @section AUTHORS
 392
 393 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}
 394
 395 @email{janneke@@gnu.org, Jan Nieuwenhuizen}
 396
 397 In case of problems, please use the mailing list for help.
 398
 399 Have fun!
 400
 401 @bye