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