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
  58 @section Requirements
  59
  60 @subsection Compilation
  61
  62 In addition to the packages needed for running Lilypond (see below),
  63 you need the following extra packages for building.
  64
  65 When installing a binary package FOO, you may need to install the
  66 FOO-devel, libFOO-dev or FOO-dev package too.
  67
  68 @itemize
  69
  70 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
  71
  72 @item New Century Schoolbook fonts, as PFB files. These are shipped
  73 with X11 and Ghostscript, and are named @file{c059033l.pfb}
  74 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}
  75
  76 @item @uref{http://www.xs4all.nl/~hanwen/mftrace/,mftrace} (1.1.19 or
  77 newer),
  78
  79 You will need to install some additional packages to get mftrace to
  80 work.
  81
  82 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
  83 (version 1.8.2 or newer).  If you are installing binary packages, you
  84 may need to install guile-devel or guile-dev or libguile-dev too.
  85
  86 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.8 or newer).
  87
  88 @item
  89 @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 4.x or
  90 newer).
  91
  92 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
  93
  94 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
  95
  96 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
  97
  98 @item @uref{http://www.gnu.org/software/flex/,Flex}
  99
 100 @item @uref{http://www.perl.org/,Perl}
 101
 102 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}
 103
 104 @item All packages required for running, including development packages with
 105 header files and libraries.
 106
 107 @end itemize
 108
 109 @subsection Running requirements
 110
 111 Running LilyPond requires proper installation of the following
 112 software
 113
 114 @itemize @bullet
 115
 116 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
 117 @item @uref{http://www.freetype.org/,FontConfig} (version 2.2).
 118 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
 119 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
 120 (version 1.8.2 or newer), or patch 1.8.1 with
 121 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
 122 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
 123 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
 124 newer. 8.50 recommended)
 125 @item Dejaview.  (This is normally installed by default)
 126 @end itemize
 127
 128 International fonts are required to create music with international text
 129 or lyrics.
 130
 131
 132 @subsection Building documentation
 133
 134 You can view the documentation online at
 135 @uref{http://lilypond.org/doc/}, but you can also build it locally.
 136 This process requires a successful compile of lilypond.  The
 137 documentation is built by issuing
 138 @quotation
 139 @example
 140 make web
 141 @end example
 142 @end quotation
 143
 144 Building the website requires some additional tools and packages
 145
 146 @itemize @bullet
 147 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
 148 @item ImageMagick
 149 @item International fonts (see input/regression/utf-8.ly for hints
 150 about which font packages are necessary for your platform)
 151 @item Ghostscript, 8.50 with the patch from
 152 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
 153 and the patch from
 154 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}.
 155 @end itemize
 156
 157 The HTML files can be installed into the standard documentation path
 158 by issuing
 159
 160 @quotation
 161 @example
 162 make out=www web-install
 163 @end example
 164 @end quotation
 165
 166 @section Testing LilyPond
 167
 168 @html
 169 <a name="testing"></a>
 170 @end html
 171
 172 LilyPond comes with an extensive suite that excercises the entire
 173 program. This suite can be used to automatically check the impact of a
 174 change. This is done as follows
 175
 176 @example
 177   make test-baseline
 178   @emph{## apply your changes, compile}
 179   make check
 180 @end example
 181
 182 This will leave an HTML page @file{out/test-results/index.html}.  This
 183 page shows all the important differences that your change introduced,
 184 whether in the layout, MIDI, performance or error reporting.
 185
 186 To rerun tests, use
 187
 188 @example
 189   make test-redo           @emph{## redo files differing from baseline}
 190   make test-clean          @emph{## remove all test results}
 191 @end example
 192
 193 @noindent
 194 and then run @code{make check} again.
 195
 196 For tracking memory usage as part of this test, you will need GUILE
 197 CVS; especially the following patch:
 198 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
 199
 200 For checking the coverage of the test suite, do the following
 201
 202 @example
 203   ./buildscripts/build-coverage.sh
 204   @emph{# uncovered files, least covered first}
 205   python ./buildscripts/coverage.py  --summary out-cov/*.cc
 206   @emph{# consecutive uncovered lines, longest first}
 207   python ./buildscripts/coverage.py  --uncovered out-cov/*.cc
 208 @end example
 209
 210 @section Building LilyPond
 211
 212 To install GNU LilyPond, type
 213 @quotation
 214 @example
 215 gunzip -c lilypond-x.y.z | tar xf -
 216 cd lilypond-x.y.z
 217 ./configure             # run with --help for applicable options
 218 make
 219 make install
 220 @end example
 221 @end quotation
 222
 223 If you are not root, you should choose a @code{--prefix} argument that
 224 points into your home directory, e.g.
 225 @quotation
 226 @example
 227 ./configure --prefix=$HOME/usr
 228 @end example
 229 @end quotation
 230
 231
 232 @subsection Configuring for multiple platforms
 233
 234 If you want to build multiple versions of LilyPond with different
 235 configuration settings, you can use the @code{--enable-config=CONF}
 236 option of configure.  You should use @samp{make conf=CONF} to generate
 237 the output in @file{out-CONF}.  Example: Suppose you want to build
 238 with and without profiling, then use the following for the normal
 239 build
 240
 241 @quotation
 242 @example
 243 ./configure --prefix=$HOME/usr/ --enable-checking
 244 make
 245 make install
 246 @end example
 247 @end quotation
 248
 249 and for the profiling version, specify a different configuration
 250
 251 @quotation
 252 @example
 253 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
 254 make conf=prof
 255 make conf=prof install
 256 @end example
 257 @end quotation
 258
 259
 260 @section Emacs mode
 261
 262 An Emacs mode for entering music and running LilyPond is contained in
 263 the source archive in the @file{elisp} directory.  Do @command{make
 264 install} to install it to @var{elispdir}.  The file @file{lilypond-init.el}
 265 should be placed to @var{load-path}@file{/site-start.d/} or appended
 266 to your @file{~/.emacs} or @file{~/.emacs.el}.
 267
 268 As a user, you may want add your source path (e.g. @file{~/site-lisp/}) to
 269 your @var{load-path} by appending the following line (as modified) to your
 270 @file{~/.emacs}
 271 @c any reason we do not advise:  (push "~/site-lisp" load-path)
 272 @quotation
 273 @example
 274 (setq load-path (append (list (expand-file-name "~/site-lisp")) load-path))
 275 @end example
 276 @end quotation
 277
 278
 279 @section Vim mode
 280
 281 A Vim mode for entering music and running LilyPond is contained in the
 282 source archive in @code{$VIM} directory.
 283
 284 The LilyPond file type is detected if the file @file{~/.vim/filetype.vim} @c
 285 has the following content
 286 @quotation
 287 @example
 288 if exists("did_load_filetypes")
 289   finish
 290 endif
 291 augroup filetypedetect
 292   au! BufNewFile,BufRead *.ly           setf lilypond
 293 augroup END
 294 @end example
 295 @end quotation
 296
 297 Please include this path by appending the following line to your
 298 @file{~/.vimrc}
 299
 300 @quotation
 301 @example
 302 set runtimepath+=/usr/local/share/lilypond/$@{LILYPOND_VERSION@}/vim/
 303 @end example
 304 @end quotation
 305
 306 @noindent
 307 where $@{LILYPOND_VERSION@} is your lilypond version.  If Lilypond was not
 308 installed in @file{/usr/local/}, then change this path accordingly.
 309
 310
 311 @section Problems
 312
 313 For help and questions use @email{lilypond-user@@gnu.org}.  Send bug
 314 reports to @email{bug-lilypond@@gnu.org}.
 315
 316 Bugs that are not fault of LilyPond are documented here.
 317
 318 @subsection Bison 1.875
 319
 320 There is a bug in bison-1.875: compilation fails with "parse error
 321 before `goto'" in line 4922 due to a bug in bison. To fix, please
 322 recompile bison 1.875 with the following fix
 323
 324 @quotation
 325 @example
 326 $ cd lily; make out/parser.cc
 327 $ vi +4919 out/parser.cc
 328 # append a semicolon to the line containing "__attribute__ ((__unused__))
 329 # save
 330 $ make
 331 @end example
 332 @end quotation
 333
 334
 335 @unnumberedsubsec MacOS X
 336
 337 For Fink, use the following command to compile.
 338
 339 @verbatim
 340 export GUILE=guile-1.6
 341 export GUILE_CONFIG=guile-1.6-config
 342 export PKG_CONFIG_PATH=/sw/lib/freetype219/lib/pkgconfig/:/sw/lib/fontconfig2/lib/pkgconfig/
 343 ./configure
 344 @end verbatim
 345
 346 @unnumberedsubsec  Solaris
 347
 348 @itemize @bullet
 349 @item Solaris7, ./configure
 350
 351 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
 352 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 353 is.  Run configure like
 354 @quotation
 355 @example
 356         CONFIG_SHELL=/bin/ksh ksh -c ./configure
 357 @end example
 358 @end quotation
 359 or
 360 @quotation
 361 @example
 362         CONFIG_SHELL=/bin/bash bash -c ./configure
 363 @end example
 364 @end quotation
 365
 366 @item FreeBSD
 367
 368 To use system fonts, dejaview must be installed.  With the default
 369 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
 370
 371 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
 372 following line just after the @code{<fontconfig>} line.  (Adjust as necessary
 373 for your hierarchy.)
 374
 375 @example
 376 <dir>/usr/X11R6/lib/X11/fonts</dir>
 377 @end example
 378
 379 @end itemize
 380
 381
 382 @section International fonts
 383
 384 On MacOs X, all fonts are installed by default.  However, finding all
 385 system fonts requires a bit of configuration; see
 386 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
 387 this post} on the @code{lilypond-user} mailing list.
 388
 389 On Linux, international fonts are installed by different means on
 390 every distribution.  We cannot list the exact commands or packages
 391 that are necessary, as each distribution is different, and the exact
 392 package names within each distribution changes.  Here are some
 393 hints, though:
 394
 395 @verbatim
 396 Red Hat Fedora
 397
 398     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
 399          ttfonts-zh_CN fonts-ja fonts-hebrew
 400
 401 Debian GNU/Linux
 402
 403    apt-get install emacs-intl-fonts xfonts-intl-.* \
 404         ttf-kochi-gothic ttf-kochi-mincho \
 405         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 406 @end verbatim
 407
 408
 409
 410
 411 @bye
 412