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