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