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