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 ``development''.
  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 You have to help @TeX{} and MetaFont find LilyPond support
 135 files. After compiling, scripts to do this can be found in
 136 @file{buildscripts/out/lilypond-profile} and
 137 @file{buildscripts/out/lilypond-login}.
 138
 139 @subsection Building documentation
 140
 141 You can view the documentation online at
 142 @uref{http://www.lilypond.org/doc/}, but you can also build it
 143 locally. This process requires a successful compile of lilypond. The
 144 documentation is built by issuing:
 145 @example
 146         make web
 147 @end example
 148
 149 Building the website requires some additional tools:
 150
 151 @itemize @bullet
 152 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
 153 @item ImageMagick
 154 @end itemize
 155
 156 The HTML files can be installed into the standard documentation path
 157 by issuing
 158
 159 @example
 160         make out=www web-install
 161 @end example
 162
 163
 164 @section Building LilyPond
 165
 166 To install GNU LilyPond, type
 167 @example
 168 gunzip -c lilypond-x.y.z | tar xf -
 169 cd lilypond-x.y.z
 170 ./configure             # run with --help to see appropriate options
 171 make
 172 make install
 173 sh buildscripts/clean-fonts.sh
 174 @end example
 175
 176 The most time-consuming part of compiling LilyPond is tracing the
 177 Type1 fonts. You can shortcut this operation by issuing
 178 one of the following commands:
 179
 180 @example
 181   make -C mf get-pfa                # requires rpm2cpio
 182   make -C mf get-debian-pfa         # may not be up to date
 183 @end example
 184
 185 If you are doing an upgrade, you should remove all @file{feta}
 186 @code{.pk} and @code{.tfm} files.  A script has been provided to do the
 187 work for you, see @file{buildscripts/clean-fonts.sh}.
 188
 189 If you are not root, you should choose a @code{--prefix} argument that
 190 points into your home directory, e.g.:
 191 @example
 192         ./configure --prefix=$HOME/usr
 193 @end example
 194
 195 In this case, you have to insert the contents of
 196 @code{buildscripts/out/lilypond-login} or
 197 @code{buildscripts/out/lilypond-profile} into your start up scripts by
 198 hand.
 199
 200
 201
 202 @subsection Configuring for multiple platforms
 203
 204 If you want to build multiple versions of LilyPond with different
 205 configuration settings, you can use the @code{--enable-config=CONF}
 206 option of configure.  You should use @samp{make conf=CONF} to generate
 207 the output in @file{out-CONF}.  Example: Suppose I want to build with
 208 and without profiling.  Then I'd use the following for the normal
 209 build:
 210
 211 @example
 212         ./configure --prefix=$HOME/usr/ --enable-checking
 213         make
 214         make install
 215 @end example
 216
 217 and for the profiling version, I specify a different configuration:
 218
 219 @example
 220         ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
 221         make conf=prof
 222         make conf=prof install
 223 @end example
 224
 225
 226
 227 @section Emacs mode
 228
 229 An Emacs mode for entering music and running LilyPond is contained in
 230 the source archive in the @file{elisp} directory.  @command{make
 231 install} installs it @var{elispdir}.  The file @file{lilypond-init.el}
 232 should be placed to @var{load-path}@file{/site-start.d/} or appended
 233 to your @file{~/.emacs} or @file{~/.emacs.el}.
 234
 235 As a user, you may want add your source path or, e.g., @file{~/site-lisp/}
 236 to your @var{load-path}. Append the following line (modified) to your
 237 @file{~/.emacs}:
 238 @c any reason we do not advise:  (push "~/site-lisp" load-path)
 239 @quotation
 240 @example
 241 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
 242 @end example
 243 @end quotation
 244
 245
 246 @section Vim mode
 247
 248 @c lilypond.words.el for vim auto-completion?
 249 A Vim mode for entering music and running LilyPond is contained in
 250 the source archive. Append the content of @file{vimrc} to @file{~/.vimrc}
 251 to get shortcuts. Install file @file{lilypond.words.el} to @file{~/.vim/} to
 252 get auto-completion. Syntax highlighting you get by installing files
 253 @file{lilypond.vim} and @file{lilypond.words.vim} to @file{~/.vim/syntax/}
 254 and appending the following to @file{~/.vim/filetype.vim}:
 255 @quotation
 256 @example
 257         " my filetype file
 258         if exists("did_load_filetypes")
 259           finish
 260         endif
 261         augroup filetypedetect
 262           au! BufRead,BufNewFile  *.ly          setfiletype lilypond
 263         augroup
 264 @end example
 265 @end quotation
 266
 267
 268
 269 @section Problems
 270
 271 For help and questions use @email{lilypond-user@@gnu.org}.  Send bug
 272 reports to @email{bug-lilypond@@gnu.org}.
 273
 274 Bugs that are not fault of LilyPond are documented here.
 275
 276 @subsection Linking to kpathsea
 277
 278 If kpathsea and the corresponding header files are installed in some
 279 directory where GCC does not search by default, for example in
 280 @file{/usr/local/lib/} and @file{/usr/local/include/} respectively,
 281 you have to explicitly tell configure where to find it. To do this:
 282
 283 @itemize
 284 @item @code{rm config.cache}
 285 @item @code{export LDFLAGS=-L/usr/share/texmf/lib}
 286 @item @code{export CPPFLAGS=-I/usr/share/texmf/include}
 287 @item @code{./configure}
 288 @end itemize
 289 Once configure has found them, the paths are stored in
 290 @file{config.make} and will be used even if you don't have the
 291 environment variables set during make.
 292
 293
 294 @unnumberedsubsec Gcc-3.0.4
 295
 296 Gcc 3.0.4 is flaky;  upgrade GCC.
 297
 298 @unnumberedsubsec Flex-2.5.4a and gcc-3.x
 299
 300 Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code.  To compile
 301 LilyPond with gcc-3.1.1 you may do
 302
 303 @example
 304         CONF=gcc-3.1 ./lexer-gcc-3.1.sh
 305         CPPFLAGS=-I$(pwd)/lily/out-gcc-3.1 CC=gcc-3.1 CXX=g++-3.1 \
 306             ./configure --enable-config=gcc-3.1
 307         CONF=gcc-3.1 ./lexer-gcc-3.1.sh
 308         make conf=gcc-3.1
 309 @end example
 310
 311
 312 @unnumberedsubsec OpenBSD
 313
 314 @itemize @bullet
 315 @item
 316  Refer to the section ``Linking to kpathsea'': GCC on OpenBSD doesn't
 317 set include paths for kpathsea.
 318 @end itemize
 319
 320 @unnumberedsubsec NetBSD
 321
 322 @itemize @bullet
 323 @item The flex precompiled in NetBSD-1.4.2 is broken.
 324 Upgrade to flex-2.5.4a.
 325
 326 @ignore
 327 @c is this current?
 328 @item The configuration of Gcc (egcs-2.91.60 19981201 (egcs-1.1.1
 329 release)) does not include @file{/usr/pkg} paths.  Configure it using:
 330 @example
 331
 332         CFLAGS='-I /usr/pkg/include' LDFLAGS='-L/usr/pkg/lib' ./configure
 333
 334 @end example
 335 @end ignore
 336
 337 @end itemize
 338
 339 @unnumberedsubsec  Solaris
 340
 341 @itemize @bullet
 342 @item Solaris7, ./configure
 343
 344 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
 345 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 346 is.   Run configure like:
 347 @example
 348         CONFIG_SHELL=/bin/ksh ksh -c ./configure
 349 @end example
 350 or:
 351 @example
 352         CONFIG_SHELL=/bin/bash bash -c ./configure
 353 @end example
 354
 355 @end itemize
 356
 357 @bye
 358