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