Documentation/topdocs/INSTALL.texi

   1 \input texinfo @c -*-texinfo-*-
   2 @setfilename INSTALL.info
   3 @settitle INSTALL - compiling and installing GNU LilyPond
   4
   5 @documentencoding utf-8
   6 @documentlanguage en
   7
   8 @node Top
   9 @top
  10
  11 @contents
  12
  13 @chapter Compiling and installing on Unix
  14
  15
  16 @html
  17 <a name="download-source">
  18 @end html
  19
  20 @section Downloading
  21
  22 Even numbered minor versions are `stable' (2.6, 2.8, etc), while odd
  23 version are development releases (2.7, 2.9, etc).  Building LilyPond
  24 is an involved process.  If possible
  25 @uref{http://lilypond.org/install,download a precompiled binary} for
  26 your platform.
  27
  28 @subsection Source code
  29
  30 Download source
  31 @itemize @bullet
  32 @item tarballs from
  33 @itemize @bullet
  34 @uref{http://lilypond.org/download/} by HTTP.
  35 @end itemize
  36 @item
  37 CVS from @uref{http://savannah.gnu.org/cvs/?group=lilypond,savannah.gnu.org}
  38 @itemize @bullet
  39 @c @quotation
  40 @example
  41 CVS_RSH=ssh cvs -d:pserver:anonymous@cvs.savannah.gnu.org:/cvsroot/lilypond co lilypond
  42 @end example
  43 @c @end quotation
  44 The CVS repository does not contain generated files.  To create
  45 @file{configure}, run
  46 @example
  47 ./autogen.sh
  48 @end example
  49 @end itemize
  50 @end itemize
  51
  52 For information on packaging, see @uref{http://lilypond.org/devel}.
  53
  54 @subsection Precompiled binary packages
  55
  56 Check out @uref{http://lilypond.org/web/install/} for up to date
  57 information on binary packages for your platform.
  58
  59
  60 @section Requirements
  61
  62 @subsection Compilation
  63
  64 In addition to the packages needed for running Lilypond (see below),
  65 you need the following extra packages for building.
  66
  67 When installing a binary package FOO, you may need to install the
  68 FOO-devel, libFOO-dev or FOO-dev package too.
  69
  70 @itemize
  71
  72 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
  73
  74 @item New Century Schoolbook fonts, as PFB files. These are shipped
  75 with X11 and Ghostscript, and are named @file{c059033l.pfb}
  76 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}
  77
  78 @item @uref{http://www.xs4all.nl/~hanwen/mftrace/,mftrace} (1.1.19 or
  79 newer),
  80
  81 You will need to install some additional packages to get mftrace to
  82 work.
  83
  84 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
  85 (version 1.6.7 or newer).  If you are installing binary packages, you
  86 may need to install guile-devel or guile-dev or libguile-dev too.
  87
  88 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.8 or newer).
  89
  90 @item
  91  @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 4.x or
  92 newer).
  93
  94 @item @uref{http://www.python.org,Python} (version 2.3 or newer)
  95
  96 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
  97
  98 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
  99
 100
 101 @item @uref{http://www.gnu.org/software/flex/,Flex}
 102
 103 @item @uref{http://www.perl.org/,Perl}
 104
 105 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}
 106
 107 @item All packages required for running, including development packages with
 108 header files and libraries.
 109
 110 @end itemize
 111
 112 @subsection Running requirements
 113
 114 Running LilyPond requires proper installation of the following
 115 software
 116
 117 @itemize @bullet
 118
 119 @item @uref{http://www.freetype.org/,Freetype} (version 2).
 120 @item @uref{http://www.freetype.org/,FontConfig} (version 2.2).
 121 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
 122 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
 123 (version 1.8.0 or newer).
 124 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
 125 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
 126 newer. 8.50 recommended)
 127 @end itemize
 128
 129 @subsection Building documentation
 130
 131 You can view the documentation online at
 132 @uref{http://lilypond.org/doc/}, but you can also build it locally.
 133 This process requires a successful compile of lilypond.  The
 134 documentation is built by issuing
 135 @quotation
 136 @example
 137 make web
 138 @end example
 139 @end quotation
 140
 141 Building the website requires some additional tools and packages
 142
 143 @itemize @bullet
 144 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
 145 @item ImageMagick
 146 @item International fonts (see input/regression/utf-8.ly for hints
 147 about which font packages are necessary for your platform)
 148 @item Ghostscript, 8.50 with the patch from
 149 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
 150 and the patch from
 151 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
 152 @end itemize
 153
 154 The HTML files can be installed into the standard documentation path
 155 by issuing
 156
 157 @quotation
 158 @example
 159 make out=www web-install
 160 @end example
 161 @end quotation
 162
 163
 164 @section Building LilyPond
 165
 166 To install GNU LilyPond, type
 167 @quotation
 168 @example
 169 gunzip -c lilypond-x.y.z | tar xf -
 170 cd lilypond-x.y.z
 171 ./configure             # run with --help for applicable options
 172 make
 173 make install
 174 @end example
 175 @end quotation
 176
 177 If you are not root, you should choose a @code{--prefix} argument that
 178 points into your home directory, e.g.
 179 @quotation
 180 @example
 181 ./configure --prefix=$HOME/usr
 182 @end example
 183 @end quotation
 184
 185
 186 @subsection Configuring for multiple platforms
 187
 188 If you want to build multiple versions of LilyPond with different
 189 configuration settings, you can use the @code{--enable-config=CONF}
 190 option of configure.  You should use @samp{make conf=CONF} to generate
 191 the output in @file{out-CONF}.  Example: Suppose you want to build
 192 with and without profiling, then use the following for the normal
 193 build
 194
 195 @quotation
 196 @example
 197 ./configure --prefix=$HOME/usr/ --enable-checking
 198 make
 199 make install
 200 @end example
 201 @end quotation
 202
 203 and for the profiling version, specify a different configuration
 204
 205 @quotation
 206 @example
 207 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
 208 make conf=prof
 209 make conf=prof install
 210 @end example
 211 @end quotation
 212
 213
 214 @section Emacs mode
 215
 216 An Emacs mode for entering music and running LilyPond is contained in
 217 the source archive in the @file{elisp} directory.  Do @command{make
 218 install} to install it to @var{elispdir}.  The file @file{lilypond-init.el}
 219 should be placed to @var{load-path}@file{/site-start.d/} or appended
 220 to your @file{~/.emacs} or @file{~/.emacs.el}.
 221
 222 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
 223 your @var{load-path} by appending the following line (as modified) to your
 224 @file{~/.emacs}
 225 @c any reason we do not advise:  (push "~/site-lisp" load-path)
 226 @quotation
 227 @example
 228 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
 229 @end example
 230 @end quotation
 231
 232
 233 @section Vim mode
 234
 235 A Vim mode for entering music and running LilyPond is contained in the
 236 source archive in @code{$VIM} directory.
 237
 238 The LilyPond file type is detected if the file @file{~/.vim/filetype.vim} @c
 239 has the following content
 240 @quotation
 241 @example
 242 if exists("did_load_filetypes")
 243   finish
 244 endif
 245 augroup filetypedetect
 246   au! BufNewFile,BufRead *.ly           setf lilypond
 247 augroup END
 248 @end example
 249 @end quotation
 250
 251 Please include this path by appending the following line to your
 252 @file{~/.vimrc}
 253
 254 @quotation
 255 @example
 256 set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
 257 @end example
 258 @end quotation
 259
 260 @noindent
 261 where $@{LILYPOND_VERISON@} is your lilypond version.  If Lilypond was not
 262 installed in @file{/usr/local/}, then change this path accordingly.
 263
 264
 265 @section Problems
 266
 267 For help and questions use @email{lilypond-user@@gnu.org}.  Send bug
 268 reports to @email{bug-lilypond@@gnu.org}.
 269
 270 Bugs that are not fault of LilyPond are documented here.
 271
 272 @subsection Bison 1.875
 273
 274 There is a bug in bison-1.875: compilation fails with "parse error
 275 before `goto'" in line 4922 due to a bug in bison. To fix, please
 276 recompile bison 1.875 with the following fix
 277
 278 @quotation
 279 @example
 280 $ cd lily; make out/parser.cc
 281 $ vi +4919 out/parser.cc
 282 # append a semicolon to the line containing "__attribute__ ((__unused__))
 283 # save
 284 $ make
 285 @end example
 286 @end quotation
 287
 288
 289 @unnumberedsubsec Flex-2.5.4a and gcc-3.x
 290
 291 Flex 2.5.4a does not produce g++-3.1.1 compliant C++ code.  To compile
 292 LilyPond with gcc-3.1.1 or higher you may do
 293
 294 @quotation
 295 @example
 296 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
 297 CPPFLAGS=-I$(pwd)/lily/out-gcc-3.1 CC=gcc-3.1 CXX=g++-3.1 \
 298 ./configure --enable-config=gcc-3.1
 299 CONF=gcc-3.1 ./lexer-gcc-3.1.sh
 300 make conf=gcc-3.1
 301 @end example
 302 @end quotation
 303
 304 @unnumberedsubsec MacOS X
 305
 306 For Fink, use the following command to compile.
 307
 308 @verbatim
 309 export GUILE=guile-1.6
 310 export GUILE_CONFIG=guile-1.6-config
 311 export PKG_CONFIG_PATH=/sw/lib/freetype219/lib/pkgconfig/:/sw/lib/fontconfig2/lib/pkgconfig/
 312 ./configure
 313 @end verbatim
 314
 315 @unnumberedsubsec NetBSD
 316
 317 @itemize @bullet
 318 @item The flex precompiled in NetBSD-1.4.2 is broken.
 319 Upgrade to flex-2.5.4a.
 320 @end itemize
 321
 322 @unnumberedsubsec  Solaris
 323
 324 @itemize @bullet
 325 @item Solaris7, ./configure
 326
 327 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
 328 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 329 is.  Run configure like
 330 @quotation
 331 @example
 332         CONFIG_SHELL=/bin/ksh ksh -c ./configure
 333 @end example
 334 @end quotation
 335 or
 336 @quotation
 337 @example
 338         CONFIG_SHELL=/bin/bash bash -c ./configure
 339 @end example
 340 @end quotation
 341
 342 @end itemize
 343
 344 @bye
 345