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