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 International fonts are required to create music with international text
 127 or lyrics.
 128
 129
 130 @subsection Building documentation
 131
 132 You can view the documentation online at
 133 @uref{http://lilypond.org/doc/}, but you can also build it locally.
 134 This process requires a successful compile of lilypond.  The
 135 documentation is built by issuing
 136 @quotation
 137 @example
 138 make web
 139 @end example
 140 @end quotation
 141
 142 Building the website requires some additional tools and packages
 143
 144 @itemize @bullet
 145 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
 146 @item ImageMagick
 147 @item International fonts (see input/regression/utf-8.ly for hints
 148 about which font packages are necessary for your platform)
 149 @item Ghostscript, 8.50 with the patch from
 150 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
 151 and the patch from
 152 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
 153 @end itemize
 154
 155 The HTML files can be installed into the standard documentation path
 156 by issuing
 157
 158 @quotation
 159 @example
 160 make out=www web-install
 161 @end example
 162 @end quotation
 163
 164 @section Testing LilyPond
 165
 166 @html
 167 <a name="testing"></a>
 168 @end html
 169
 170 LilyPond comes with an extensive suite that excercises the entire
 171 program. This suite can be used to automatically check the impact of a
 172 change. This is done as follows
 173
 174 @example
 175   make test-baseline
 176   @emph{## apply your changes, compile}
 177   make check
 178 @end example
 179
 180 This will leave an HTML page @file{out/test-results/index.html}.  This
 181 page shows all the important differences that your change introduced,
 182 whether in the layout, MIDI, performance or error reporting.
 183
 184 To rerun tests, use
 185
 186 @example
 187   make test-redo           @emph{## redo files differing from baseline}
 188   make test-clean          @emph{## remove all test results}
 189 @end example
 190
 191 @noindent
 192 and then run @code{make check} again.
 193
 194 For tracking memory usage as part of this test, you will need GUILE
 195 CVS; especially the following patch:
 196 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
 197
 198 For checking the coverage of the test suite, do the following
 199
 200 @example
 201   ./buildscripts/build-coverage.sh
 202   @emph{# uncovered files, least covered first}
 203   python ./buildscripts/coverage.py  --summary out-cov/*.cc
 204   @emph{# consecutive uncovered lines, longest first}
 205   python ./buildscripts/coverage.py  --uncovered out-cov/*.cc
 206 @end example
 207
 208 @section Building LilyPond
 209
 210 To install GNU LilyPond, type
 211 @quotation
 212 @example
 213 gunzip -c lilypond-x.y.z | tar xf -
 214 cd lilypond-x.y.z
 215 ./configure             # run with --help for applicable options
 216 make
 217 make install
 218 @end example
 219 @end quotation
 220
 221 If you are not root, you should choose a @code{--prefix} argument that
 222 points into your home directory, e.g.
 223 @quotation
 224 @example
 225 ./configure --prefix=$HOME/usr
 226 @end example
 227 @end quotation
 228
 229
 230 @subsection Configuring for multiple platforms
 231
 232 If you want to build multiple versions of LilyPond with different
 233 configuration settings, you can use the @code{--enable-config=CONF}
 234 option of configure.  You should use @samp{make conf=CONF} to generate
 235 the output in @file{out-CONF}.  Example: Suppose you want to build
 236 with and without profiling, then use the following for the normal
 237 build
 238
 239 @quotation
 240 @example
 241 ./configure --prefix=$HOME/usr/ --enable-checking
 242 make
 243 make install
 244 @end example
 245 @end quotation
 246
 247 and for the profiling version, specify a different configuration
 248
 249 @quotation
 250 @example
 251 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
 252 make conf=prof
 253 make conf=prof install
 254 @end example
 255 @end quotation
 256
 257
 258 @section Emacs mode
 259
 260 An Emacs mode for entering music and running LilyPond is contained in
 261 the source archive in the @file{elisp} directory.  Do @command{make
 262 install} to install it to @var{elispdir}.  The file @file{lilypond-init.el}
 263 should be placed to @var{load-path}@file{/site-start.d/} or appended
 264 to your @file{~/.emacs} or @file{~/.emacs.el}.
 265
 266 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
 267 your @var{load-path} by appending the following line (as modified) to your
 268 @file{~/.emacs}
 269 @c any reason we do not advise:  (push "~/site-lisp" load-path)
 270 @quotation
 271 @example
 272 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
 273 @end example
 274 @end quotation
 275
 276
 277 @section Vim mode
 278
 279 A Vim mode for entering music and running LilyPond is contained in the
 280 source archive in @code{$VIM} directory.
 281
 282 The LilyPond file type is detected if the file @file{~/.vim/filetype.vim} @c
 283 has the following content
 284 @quotation
 285 @example
 286 if exists("did_load_filetypes")
 287   finish
 288 endif
 289 augroup filetypedetect
 290   au! BufNewFile,BufRead *.ly           setf lilypond
 291 augroup END
 292 @end example
 293 @end quotation
 294
 295 Please include this path by appending the following line to your
 296 @file{~/.vimrc}
 297
 298 @quotation
 299 @example
 300 set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
 301 @end example
 302 @end quotation
 303
 304 @noindent
 305 where $@{LILYPOND_VERISON@} is your lilypond version.  If Lilypond was not
 306 installed in @file{/usr/local/}, then change this path accordingly.
 307
 308
 309 @section Problems
 310
 311 For help and questions use @email{lilypond-user@@gnu.org}.  Send bug
 312 reports to @email{bug-lilypond@@gnu.org}.
 313
 314 Bugs that are not fault of LilyPond are documented here.
 315
 316 @subsection Bison 1.875
 317
 318 There is a bug in bison-1.875: compilation fails with "parse error
 319 before `goto'" in line 4922 due to a bug in bison. To fix, please
 320 recompile bison 1.875 with the following fix
 321
 322 @quotation
 323 @example
 324 $ cd lily; make out/parser.cc
 325 $ vi +4919 out/parser.cc
 326 # append a semicolon to the line containing "__attribute__ ((__unused__))
 327 # save
 328 $ make
 329 @end example
 330 @end quotation
 331
 332
 333 @unnumberedsubsec MacOS X
 334
 335 For Fink, use the following command to compile.
 336
 337 @verbatim
 338 export GUILE=guile-1.6
 339 export GUILE_CONFIG=guile-1.6-config
 340 export PKG_CONFIG_PATH=/sw/lib/freetype219/lib/pkgconfig/:/sw/lib/fontconfig2/lib/pkgconfig/
 341 ./configure
 342 @end verbatim
 343
 344 @unnumberedsubsec  Solaris
 345
 346 @itemize @bullet
 347 @item Solaris7, ./configure
 348
 349 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
 350 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 351 is.  Run configure like
 352 @quotation
 353 @example
 354         CONFIG_SHELL=/bin/ksh ksh -c ./configure
 355 @end example
 356 @end quotation
 357 or
 358 @quotation
 359 @example
 360         CONFIG_SHELL=/bin/bash bash -c ./configure
 361 @end example
 362 @end quotation
 363
 364 @end itemize
 365
 366 @section International fonts
 367
 368 On MacOs X, all fonts are installed by default.
 369
 370 On Linux, international fonts are installed by different means on
 371 every distribution.  We cannot list the exact commands or packages
 372 that are necessary, as each distribution is different, and the exact
 373 package names within each distribution changes.  Here are some
 374 hints, though:
 375
 376 @verbatim
 377 Red Hat Fedora
 378
 379     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
 380          ttfonts-zh_CN fonts-ja fonts-hebrew
 381
 382 Debian GNU/Linux
 383
 384    apt-get install emacs-intl-fonts xfonts-intl-.* \
 385         ttf-kochi-gothic ttf-kochi-mincho \
 386         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 387 @end verbatim
 388
 389
 390 @bye
 391