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