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 The HTML files can be installed into the standard documentation path
 178 by issuing
 179
 180 @example
 181         make out=www web-install
 182 @end example
 183
 184
 185 @section Building LilyPond
 186
 187 To install GNU LilyPond, type
 188 @example
 189 gunzip -c lilypond-x.y.z | tar xf -
 190 cd lilypond-x.y.z
 191 ./configure             # run with --help to see appropriate options
 192 make
 193 make install
 194 sh buildscripts/clean-fonts.sh
 195 @end example
 196
 197 If, in addition, you want to generate PDF files of your scores and have
 198 installed mftrace, type
 199 @example
 200 make pfa-fonts
 201 make install-pfa-fonts
 202 texhash
 203 @end example
 204
 205 PFA versions of the fonts for the latest LilyPond version can also be
 206 obtained from the internet: download the .deb file that corresponds to
 207 your version, eg.
 208
 209 @example
 210 wget http://ftp.us.debian.org/debian/pool/main/l/lilypond/lilypond_1.8.0-1_i386.deb
 211 @c ar p lilypond_1.8.0-1_i386.deb data.tar.gz | tar -C / -zxf - '.*.pfa' '.*.map'
 212 ar x lilypond_1.8.0-1_i386.deb data.tar.gz
 213 tar -C / -zxf data.tar.gz /usr/share/lilypond/1.8.0/fonts/type1/
 214 tar -C / -zxf data.tar.gz /usr/share/lilypond/1.8.0/dvips/
 215 texhash
 216 @end example
 217 If you are installing LilyPond somewhere else, unpack the appropriate
 218 files as shown, and move them to the appropriate paths. Of course, the
 219 .deb version number should correspond to what you are installing.
 220
 221 If you are doing an upgrade, you should remove all @file{feta}
 222 @code{.pk} and @code{.tfm} files.  A script has been provided to do the
 223 work for you, see @file{buildscripts/clean-fonts.sh}.
 224
 225 If you are not root, you should choose a @code{--prefix} argument that
 226 points into your home directory, e.g.:
 227 @example
 228         ./configure --prefix=$HOME/usr
 229 @end example
 230
 231 In this case, you have to insert the contents of
 232 @code{buildscripts/out/lilypond-login} or
 233 @code{buildscripts/out/lilypond-profile} into your start up scripts by
 234 hand.
 235
 236
 237
 238 @subsection Configuring for multiple platforms
 239
 240 If you want to build multiple versions of LilyPond with different
 241 configuration settings, you can use the @code{--enable-config=CONF}
 242 option of configure.  You should use @samp{make conf=CONF} to generate
 243 the output in @file{out-CONF}.  Example: Suppose I want to build with
 244 and without profiling.  Then I'd use the following for the normal
 245 build:
 246 @c prefix=~ ?
 247 @example
 248         ./configure --prefix=$HOME/usr/ --enable-checking
 249         make
 250         make install
 251 @end example
 252
 253 and for the profiling version, I specify a different configuration:
 254
 255 @example
 256         ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
 257         make conf=prof
 258         make conf=prof install
 259 @end example
 260
 261
 262
 263 @section Emacs mode
 264
 265 An Emacs mode for entering music and running LilyPond is contained in
 266 the source archive as @file{lilypond-mode.el},
 267 @file{lilypond-indent.el}, @file{lilypond-font-lock.el} and
 268 @file{lilypond.words.el}.  You should install these files to a directory
 269 included in your @var{load-path}. File @file{lilypond-init.el} should
 270 be placed to @var{load-path}@file{/site-start.d/} or appended to your
 271 @file{~/.emacs} or @file{~/.emacs.el}.
 272
 273 As a user, you may want add your source path or, e.g., @file{~/site-lisp/}
 274 to your @var{load-path}. Append the following line (modified) to your
 275 @file{~/.emacs}:
 276 @quotation
 277 @example
 278         (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
 279 @end example
 280 @end quotation
 281
 282
 283 @section Vim mode
 284
 285 A Vim mode for entering music and running LilyPond is contained in
 286 the source archive. Append the content of @file{vimrc} to @file{~/.vimrc}
 287 to get shortcuts. Install file @file{lilypond.words.el} to @file{~/.vim/} to
 288 get auto-completion. Syntax highlighting you get by installing
 289 @file{lilypond.vim} to @file{~/.vim/syntax/} and appending the following
 290 to @file{~/.vim/filetype.vim}:
 291 @quotation
 292 @example
 293         " my filetype file
 294         if exists("did_load_filetypes")
 295           finish
 296         endif
 297         augroup filetypedetect
 298           au! BufRead,BufNewFile  *.ly          setfiletype lilypond
 299         augroup
 300 @end example
 301 @end quotation
 302
 303
 304
 305 @section Problems
 306
 307 For help and questions use @email{lilypond-user@@gnu.org}.  Please
 308 consult the FAQ before mailing your problems.  If you find bugs, please
 309 send bug reports to @email{bug-lilypond@@gnu.org}.
 310
 311 Bugs that are not fault of LilyPond are documented here.
 312
 313 @subsection Linking to kpathsea
 314
 315 If kpathsea and the corresponding header files are installed in some
 316 directory where GCC does not search by default, for example in
 317 @file{/usr/local/lib/} and @file{/usr/local/include/} respectively,
 318 you have to explicitly tell configure where to find it. To do this:
 319
 320 @itemize
 321 @item @code{rm config.cache}
 322 @item @code{export LDFLAGS=-L/usr/share/texmf/lib}
 323 @item @code{export CPPFLAGS=-I/usr/share/texmf/include}
 324 @item @code{./configure}
 325 @end itemize
 326 Once configure has found them, the paths are stored in
 327 @file{config.make} and will be used even if you don't have the
 328 environment variables set during make.
 329
 330
 331 @unnumberedsubsec Gcc-3.0.4
 332
 333 Gcc 3.0.4 is flaky;  upgrade GCC.
 334
 335 @unnumberedsubsec Flex-2.5.4a and gcc-3.x
 336
 337 Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code.  To compile
 338 LilyPond with gcc-3.1.1 you may do
 339
 340 @example
 341         CONF=gcc-3.1 ./lexer-gcc-3.1.sh
 342         CPPFLAGS=-I$(pwd)/lily/out-gcc-3.1 CC=gcc-3.1 CXX=g++-3.1 \
 343             ./configure --enable-config=gcc-3.1
 344         CONF=gcc-3.1 ./lexer-gcc-3.1.sh
 345         make conf=gcc-3.1
 346 @end example
 347
 348
 349 @unnumberedsubsec OpenBSD
 350
 351 @itemize @bullet
 352 @item
 353  Refer to the section ``Linking to kpathsea'': GCC on OpenBSD doesn't
 354 set include paths for kpathsea.
 355 @end itemize
 356
 357 @unnumberedsubsec NetBSD
 358
 359 @itemize @bullet
 360 @item The flex precompiled in NetBSD-1.4.2 is broken.
 361 Upgrade to flex-2.5.4a.
 362
 363 @ignore
 364 @c is this current?
 365 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 366 release)) does not include @file{/usr/pkg} paths.  Configure it using:
 367 @example
 368
 369         CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 370
 371 @end example
 372 @end ignore
 373
 374 @end itemize
 375
 376 @unnumberedsubsec  Solaris
 377
 378 @itemize @bullet
 379 @item Solaris7, ./configure
 380
 381 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
 382 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 383 is.  Please run configure like:
 384 @example
 385         CONFIG_SHELL=/bin/ksh ksh -c ./configure
 386 @end example
 387 or:
 388 @example
 389         CONFIG_SHELL=/bin/bash bash -c ./configure
 390 @end example
 391
 392 @item Sparc64/Solaris 2.6, ld
 393
 394 Not yet resolved.
 395 @end itemize
 396
 397
 398 @unnumberedsubsec   AIX
 399
 400 @itemize @bullet
 401 @item AIX 4.3 ld
 402
 403 The following is from the gcc install/SPECIFIC file:
 404 @quotation
 405    Some versions of the AIX binder (linker) can fail with a relocation
 406    overflow severe error when the -bbigtoc option is used to link
 407    GCC-produced object files into an executable that overflows the TOC.
 408    A fix for APAR IX75823 (OVERFLOW DURING LINK WHEN USING GCC AND
 409    -BBIGTOC) is available from IBM Customer Support and from its
 410    27service.boulder.ibm.com website as PTF U455193.
 411
 412    Binutils does not support AIX 4.3 (at least through release 2.9). GNU
 413    as and GNU ld will not work properly and one should not configure GCC
 414    to use those GNU utilities. Use the native AIX tools which do
 415    interoperate with GCC.
 416 @end quotation
 417
 418 add -Wl,-bbigtoc to USER_LDFLAGS, i.e.:
 419 @example
 420         LDFLAGS='-Wl,-bbigtoc' ./configure
 421 @end example
 422
 423 @end itemize
 424
 425
 426 @bye
 427