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