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