Documentation/topdocs/INSTALL.texi

   1 @node Top, , , (dir)
   2 @top
   3 @comment  node-name,  next,  previous,  up\input texinfo @c -*-texinfo-*-
   4 @setfilename INSTALL.info
   5 @settitle INSTALL - compiling and installing GNU LilyPond
   6
   7 @contents
   8
   9 @chapter Compiling and installing on Unix
  10
  11
  12 @html
  13 <a name="download-source">
  14 @end html
  15
  16 @section Downloading
  17
  18 Even numbered versions are `stable'. The webpages for the stable version
  19 (1.4) reside @uref{http://www.gnu.org/software/lilypond, on the GNU
  20 servers}. Big enhancements go into the latest odd numbered version
  21 (1.5), whose webpages are on @uref{http://www.lilypond.org/,the lilypond
  22 site}.
  23
  24 Building LilyPond is an involved process. We advise to use binary
  25 packages if these are available for your platform.
  26
  27
  28
  29 @subsection Source code
  30
  31 Download source tarballs from here:
  32 @itemize @bullet
  33 @item Download development releases from
  34 @uref{ftp://ftp.lilypond.org/pub/LilyPond/} by FTP and
  35 @uref{http://www.lilypond.org/ftp/} by HTTP.
  36 @item @uref{ftp://sca.uwaterloo.ca/pub/} by FTP (Canadian mirror).
  37 @end itemize
  38
  39
  40 Use Xdelta to patch tarballs, e.g. to patch
  41 @file{lilypond-1.4.2.tar.gz} to @file{lilypond-1.4.3.tar.gz}, do
  42 @example
  43         xdelta patch lilypond-1.4.2-1.4.3.xd lilypond-1.4.2.tar.gz
  44 @end example
  45
  46 For information on packaging and CVS, see
  47 @uref{http://lilypond.org/}, under ``develoment''.
  48
  49
  50 @subsection Precompiled binaries
  51
  52 Check out @uref{http://lilypond.org} for up to date information on
  53 binary packages.
  54
  55
  56 @subsection Font problems
  57
  58 If you are upgrading from a previous version of LilyPond, be sure to
  59 remove all old font files. These include @file{.pk} and @file{.tfm} files
  60 that may be located in @file{/var/lib/texmf}, @file{/var/spool/texmf},
  61 @file{/var/tmp/texmf} or @file{@var{prefix}/share/lilypond/fonts/}.  A
  62 script automating this has been included, see
  63 @file{buildscripts/clean-fonts.sh}.
  64
  65
  66
  67
  68 @section Requirements
  69
  70 @subsection Compilation
  71
  72 You need the following packages to compile LilyPond:
  73
  74 @itemize
  75 @item
  76  @uref{http://gcc.gnu.org/,
  77 The GNU c++ compiler} (version 3.1 or newer).
  78 EGCS and 2.x are known to cause crashes.
  79
  80 @item @uref{http://www.python.org,Python} (version 2.1 or newer).
  81
  82 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version 1.6.0 or newer).
  83
  84 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
  85
  86 @item  @uref{http://www.gnu.org/software/flex/,Flex} (version 2.5.4a or newer).
  87
  88 WARNING: plain Flex 2.5.4(a) generates invalid C++ code.  GCC 3.x
  89 chokes on this.  If you wish to use GCC 3.x, make sure that your
  90 distribution supports g++ 3.x and flex.  For workarounds, see
  91 lexer-gcc-3.1.sh in the source directory.
  92
  93 @item @uref{http://www.gnu.org/software/bison/,Bison} (version 1.25 or
  94 newer, but not 1.50 or 1.75).
  95
  96 @item @TeX{}.
  97
  98 @TeX{} is used as an output backend.
  99
 100 Also, @TeX{}'s libkpathsea is used to find the fonts (@file{.mf},
 101 @file{.afm}, @file{.tfm}).  Make sure you have tetex 1.0 or newer
 102 (1.0.6 is known to work).  You may need to install a tetex-devel (or
 103 tetex-dev or libkpathsea-dev) package too.
 104
 105 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.2 or newer).
 106
 107 @item The
 108 @uref{ftp://ftp.ctan.org/tex-archive/macros/latex/contrib/supported/geometry,geometry
 109 package for LaTeX}.
 110
 111  This package is normally included with the @TeX{} distribution.
 112
 113 @item kpathsea, a library for searching (@TeX{}) files.
 114
 115 @ignore
 116 @code{kpathsea} is
 117 usually included with your installation of @TeX{}.  You may need to
 118 install a tetex-devel or tetex-dev package too. If kpathsea is not
 119 installed in a directory where the compiler normally looks, read the
 120 hints for Slackware below.
 121
 122 In the very unlikely case that kpathsea is not available for your
 123 platform (i.e., you're not running GNU/Linux, Windows, or any recent
 124 UNIX), you can compile LilyPond without kpathsea support.  In that case,
 125 you'll probably have to indicate where @TeX{}'s tfm files live.  Invoke
 126 configure something like:
 127
 128 @quotation
 129 @example
 130         ./configure --without-kpathsea --enable-tfm-path=/usr/share/texmf/fonts/tfm/public/cm/:/usr/share/texmf/fonts/tfm/ams/symbols
 131 @end example
 132 @end quotation
 133 @end ignore
 134
 135 @end itemize
 136
 137 @subsection Running requirements
 138
 139 GNU LilyPond does use a lot of resources. For operation you need the
 140 following software:
 141
 142 @itemize @bullet
 143 @item @TeX{}.
 144 @item Xdvi and Ghostscript.
 145 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} 1.6.0, or newer.
 146 @end itemize
 147
 148 For running LilyPond successfully
 149
 150 You have to help @TeX{} and MetaFont find LilyPond support
 151 files. After compiling, scripts to do this can be found in
 152 @file{buildscripts/out/lilypond-profile} and
 153 @file{buildscripts/out/lilypond-login}.
 154
 155 @subsection Building documentation
 156
 157 You can view the documentation online at
 158 @uref{http://www.lilypond.org/doc/}, but you can also build it
 159 locally. This process requires a successful compile of lilypond. The
 160 documentation is built by issuing:
 161 @example
 162         make web
 163 @end example
 164
 165 Building the website requires some additional tools:
 166
 167 @itemize @bullet
 168 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities} see
 169 @item ImageMagick
 170 @item @uref{http://www.cs.uu.nl/~hanwen/mftrace/,mftrace} (1.0.17 or
 171 newer),
 172
 173   You will need to install some additional packages to get mftrace to
 174 work.
 175 @end itemize
 176
 177 @section Building LilyPond
 178
 179 To install GNU LilyPond, type
 180 @example
 181 gunzip -c lilypond-x.y.z | tar xf -
 182 cd lilypond-x.y.z
 183 ./configure             # run with --help to see appropriate options
 184 make
 185 make install
 186 sh buildscripts/clean-fonts.sh
 187 @end example
 188
 189 If, in addition, you want to generate PDF files of your scores and have
 190 installed mftrace, type
 191 @example
 192 make pfa-fonts
 193 make install-pfa-fonts
 194 texhash
 195 @end example
 196
 197 PFA versions of the fonts for the latest LilyPond version can also be
 198 obtained from the internet: download the .deb file that corresponds to
 199 your version, eg.
 200
 201 @example
 202 wget http://ftp.us.debian.org/debian/pool/main/l/lilypond/lilypond_1.8.0-1_i386.deb
 203 @c ar p lilypond_1.8.0-1_i386.deb data.tar.gz | tar -C / -zxf - '.*.pfa' '.*.map'
 204 ar x lilypond_1.8.0-1_i386.deb data.tar.gz
 205 tar -C / -zxf data.tar.gz /usr/share/lilypond/1.8.0/fonts/type1/
 206 tar -C / -zxf data.tar.gz /usr/share/lilypond/1.8.0/dvips/
 207 texhash
 208 @end example
 209 If you are installing LilyPond somewhere else, unpack the appropriate
 210 files as shown, and move them to the appropriate paths. Of course, the
 211 .deb version number should correspond to what you are installing.
 212
 213
 214
 215 If you are doing an upgrade, you should remove all @file{feta}
 216 @code{.pk} and @code{.tfm} files.  A script has been provided to do the
 217 work for you, see @file{buildscripts/clean-fonts.sh}.
 218
 219 If you are not root, you should choose a @code{--prefix} argument that
 220 points into your home directory, e.g.:
 221 @example
 222         ./configure --prefix=$HOME/usr
 223 @end example
 224
 225 In this case, you have to insert the contents of
 226 @code{buildscripts/out/lilypond-login} or
 227 @code{buildscripts/out/lilypond-profile} into your start up scripts by
 228 hand.
 229
 230
 231
 232 @subsection Configuring for multiple platforms
 233
 234 If you want to build multiple versions of LilyPond with different
 235 configuration settings, you can use the @code{--enable-config=CONF}
 236 option of configure.  You should use @samp{make conf=CONF} to generate
 237 the output in @file{out-CONF}.  Example: Suppose I want to build with
 238 and without profiling.  Then I'd use the following for the normal
 239 build:
 240 @c prefix=~ ?
 241 @example
 242         ./configure --prefix=$HOME/usr/ --enable-checking
 243         make
 244         make install
 245 @end example
 246
 247 and for the profiling version, I specify a different configuration:
 248
 249 @example
 250         ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
 251         make conf=prof
 252         make conf=prof install
 253 @end example
 254
 255
 256
 257 @section Emacs mode
 258
 259 An Emacs mode for entering music and running LilyPond is contained in
 260 the source archive as @file{lilypond-mode.el},
 261 @file{lilypond-indent.el}, @file{lilypond-font-lock.el} and
 262 @file{lilypond.words}.  You should install these files to a directory
 263 included in your @var{load-path}. File @file{lilypond-init.el} should
 264 be placed to @var{load-path}@file{/site-start.d/} or appended to your
 265 @file{~/.emacs} or @file{~/.emacs.el}.
 266
 267 As a user, you may want add your source path or, e.g., @file{~/site-lisp/}
 268 to your @var{load-path}. Append the following line (modified) to your
 269 @file{~/.emacs}:
 270 @quotation
 271 @example
 272         (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
 273 @end example
 274 @end quotation
 275
 276
 277 @section Vim mode
 278
 279 A Vim mode for entering music and running LilyPond is contained in
 280 the source archive. Append the content of @file{vimrc} to @file{~/.vimrc}
 281 to get shortcuts. Install file @file{lilypond.words} to @file{~/.vim/} to
 282 get auto-completion. Syntax highlighting you get by installing
 283 @file{lilypond.vim} to @file{~/.vim/syntax/} and appending the following
 284 to @file{~/.vim/filetype.vim}:
 285 @quotation
 286 @example
 287         " my filetype file
 288         if exists("did_load_filetypes")
 289           finish
 290         endif
 291         augroup filetypedetect
 292           au! BufRead,BufNewFile  *.ly          setfiletype lilypond
 293         augroup
 294 @end example
 295 @end quotation
 296
 297
 298
 299 @section Problems
 300
 301 For help and questions use @email{lilypond-user@@gnu.org}.  Please
 302 consult the FAQ before mailing your problems.  If you find bugs, please
 303 send bug reports to @email{bug-lilypond@@gnu.org}.
 304
 305 Bugs that are not fault of LilyPond are documented here.
 306
 307 @subsection Linking to kpathsea
 308
 309 If kpathsea and the corresponding header files are installed in some
 310 directory where GCC does not search by default, for example in
 311 @file{/usr/local/lib/} and @file{/usr/local/include/} respectively,
 312 you have to explicitly tell configure where to find it. To do this:
 313
 314 @itemize
 315 @item @code{rm config.cache}
 316 @item @code{export LDFLAGS=-L/usr/share/texmf/lib}
 317 @item @code{export CPPFLAGS=-I/usr/share/texmf/include}
 318 @item @code{./configure}
 319 @end itemize
 320 Once configure has found them, the paths are stored in
 321 @file{config.make} and will be used even if you don't have the
 322 environment variables set during make.
 323
 324
 325 @unnumberedsubsec Gcc-3.0.4
 326
 327 Gcc 3.0.4 is flaky;  upgrade GCC.
 328
 329 @unnumberedsubsec Flex-2.5.4a and gcc-3.x
 330
 331 Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code.  To compile
 332 LilyPond with gcc-3.1.1 you may do
 333
 334 @example
 335         CONF=gcc-3.1 ./lexer-gcc-3.1.sh
 336         CPPFLAGS=-I$(pwd)/lily/out-gcc-3.1 CC=gcc-3.1 CXX=g++-3.1 \
 337             ./configure --enable-config=gcc-3.1
 338         CONF=gcc-3.1 ./lexer-gcc-3.1.sh
 339         make conf=gcc-3.1
 340 @end example
 341
 342
 343 @unnumberedsubsec OpenBSD
 344
 345 @itemize @bullet
 346 @item
 347  Refer to the section ``Linking to kpathsea'': GCC on OpenBSD doesn't
 348 set include paths for kpathsea.
 349 @end itemize
 350
 351 @unnumberedsubsec NetBSD
 352
 353 @itemize @bullet
 354 @item The flex precompiled in NetBSD-1.4.2 is broken.
 355 Upgrade to flex-2.5.4a.
 356
 357 @ignore
 358 @c is this current?
 359 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 360 release)) does not include @file{/usr/pkg} paths.  Configure it using:
 361 @example
 362
 363         CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 364
 365 @end example
 366 @end ignore
 367
 368 @end itemize
 369
 370 @unnumberedsubsec  Solaris
 371
 372 @itemize @bullet
 373 @item Solaris7, ./configure
 374
 375 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
 376 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 377 is.  Please run configure like:
 378 @example
 379         CONFIG_SHELL=/bin/ksh ksh -c ./configure
 380 @end example
 381 or:
 382 @example
 383         CONFIG_SHELL=/bin/bash bash -c ./configure
 384 @end example
 385
 386 @item Sparc64/Solaris 2.6, ld
 387
 388 Not yet resolved.
 389 @end itemize
 390
 391
 392 @unnumberedsubsec   AIX
 393
 394 @itemize @bullet
 395 @item AIX 4.3 ld
 396
 397 The following is from the gcc install/SPECIFIC file:
 398 @quotation
 399    Some versions of the AIX binder (linker) can fail with a relocation
 400    overflow severe error when the -bbigtoc option is used to link
 401    GCC-produced object files into an executable that overflows the TOC.
 402    A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
 403    -BBIGTOC) is available from IBM Customer Support and from its
 404    27service.boulder.ibm.com website as PTF U455193.
 405
 406    Binutils does not support AIX 4.3 (at least through release 2.9). GNU
 407    as and GNU ld will not work properly and one should not configure GCC
 408    to use those GNU utilities. Use the native AIX tools which do
 409    interoperate with GCC.
 410 @end quotation
 411
 412 add -Wl,-bbigtoc to USER_LDFLAGS, i.e.:
 413 @example
 414         LDFLAGS='-Wl,-bbigtoc' ./configure
 415 @end example
 416
 417 @end itemize
 418
 419
 420 @bye
 421