Documentation/user/install.itexi

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @c This file is part of lilypond-program.tely
   3 @ignore
   4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
   5
   6     When revising a translation, copy the HEAD committish of the
   7     version that you are working on.  See TRANSLATION for details.
   8 @end ignore
   9
  10 @c was "INSTALL - compiling and installing GNU LilyPond"
  11 @node Install
  12 @chapter Install
  13
  14 @html
  15 <a name="download-source">
  16 @end html
  17
  18 @section Downloading
  19
  20 Even numbered minor versions are `stable' (2.6, 2.8, etc), while odd
  21 version are development releases (2.7, 2.9, etc).  Building LilyPond
  22 is an involved process.  If possible
  23 @uref{http://lilypond.org/install,download a precompiled binary} for
  24 your platform.
  25
  26 @subsection Source code
  27
  28 Download source
  29 @itemize @bullet
  30 @item tarballs from
  31 @uref{http://lilypond.org/download/} by HTTP.
  32 @item tarballs from
  33 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
  34 @item
  35 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
  36 @example
  37 git clone git://git.sv.gnu.org/lilypond.git
  38 @end example
  39
  40 The repository does not contain generated files.  To create
  41 @file{configure}, run
  42 @example
  43 ./autogen.sh
  44 @end example
  45 @end itemize
  46
  47 For information on packaging, see @uref{http://lilypond.org/devel}.
  48
  49 @subsection Precompiled binary packages
  50
  51 Check out @uref{http://lilypond.org/web/install/} for up to date
  52 information on binary packages for your platform.
  53
  54
  55
  56 @section Requirements
  57
  58 @subsection Compilation
  59
  60 In addition to the packages needed for running Lilypond (see below),
  61 you need the following extra packages for building.
  62
  63 When installing a binary package FOO, you may need to install the
  64 FOO-devel, libFOO-dev or FOO-dev package too.
  65
  66 @itemize
  67
  68 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
  69
  70 @item New Century Schoolbook fonts, as PFB files. These are shipped
  71 with X11 and Ghostscript, and are named @file{c059033l.pfb}
  72 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}
  73
  74 @item @uref{http://www.xs4all.nl/~hanwen/mftrace/,mftrace} (1.1.19 or
  75 newer),
  76
  77 You will need to install some additional packages to get mftrace to
  78 work.
  79
  80 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
  81 (version 1.8.2 or newer).  If you are installing binary packages, you
  82 may need to install guile-devel or guile-dev or libguile-dev too.
  83
  84 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.8 or newer).
  85
  86 @item
  87 @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 4.x or
  88 newer).
  89
  90 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
  91
  92 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
  93
  94 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
  95
  96 @item @uref{http://www.gnu.org/software/flex/,Flex}
  97
  98 @item @uref{http://www.perl.org/,Perl}
  99
 100 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}
 101
 102 @item All packages required for running, including development packages with
 103 header files and libraries.
 104
 105 @end itemize
 106
 107 @subsection Running requirements
 108
 109 Running LilyPond requires proper installation of the following
 110 software
 111
 112 @itemize @bullet
 113
 114 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
 115 @item @uref{http://www.freetype.org/,FontConfig} (version 2.2).
 116 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
 117 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
 118 (version 1.8.2 or newer), or patch 1.8.1 with
 119 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
 120 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
 121 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
 122 newer. 8.50 recommended)
 123 @item Dejaview.  (This is normally installed by default)
 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
 259 @section Problems
 260
 261 For help and questions use @email{lilypond-user@@gnu.org}.  Send bug
 262 reports to @email{bug-lilypond@@gnu.org}.
 263
 264 Bugs that are not fault of LilyPond are documented here.
 265
 266 @subsection Bison 1.875
 267
 268 There is a bug in bison-1.875: compilation fails with "parse error
 269 before `goto'" in line 4922 due to a bug in bison. To fix, please
 270 recompile bison 1.875 with the following fix
 271
 272 @quotation
 273 @example
 274 $ cd lily; make out/parser.cc
 275 $ vi +4919 out/parser.cc
 276 # append a semicolon to the line containing "__attribute__ ((__unused__))
 277 # save
 278 $ make
 279 @end example
 280 @end quotation
 281
 282
 283 @unnumberedsubsec MacOS X
 284
 285 For Fink, use the following command to compile.
 286
 287 @verbatim
 288 export GUILE=guile-1.6
 289 export GUILE_CONFIG=guile-1.6-config
 290 export PKG_CONFIG_PATH=/sw/lib/freetype219/lib/pkgconfig/:/sw/lib/fontconfig2/lib/pkgconfig/
 291 ./configure
 292 @end verbatim
 293
 294 @unnumberedsubsec  Solaris
 295
 296 @itemize @bullet
 297 @item Solaris7, ./configure
 298
 299 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
 300 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
 301 is.  Run configure like
 302 @quotation
 303 @example
 304         CONFIG_SHELL=/bin/ksh ksh -c ./configure
 305 @end example
 306 @end quotation
 307 or
 308 @quotation
 309 @example
 310         CONFIG_SHELL=/bin/bash bash -c ./configure
 311 @end example
 312 @end quotation
 313
 314 @item FreeBSD
 315
 316 To use system fonts, dejaview must be installed.  With the default
 317 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
 318
 319 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
 320 following line just after the @code{<fontconfig>} line.  (Adjust as necessary
 321 for your hierarchy.)
 322
 323 @example
 324 <dir>/usr/X11R6/lib/X11/fonts</dir>
 325 @end example
 326
 327 @end itemize
 328
 329
 330 @section International fonts
 331
 332 On MacOs X, all fonts are installed by default.  However, finding all
 333 system fonts requires a bit of configuration; see
 334 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
 335 this post} on the @code{lilypond-user} mailing list.
 336
 337 On Linux, international fonts are installed by different means on
 338 every distribution.  We cannot list the exact commands or packages
 339 that are necessary, as each distribution is different, and the exact
 340 package names within each distribution changes.  Here are some
 341 hints, though:
 342
 343 @verbatim
 344 Red Hat Fedora
 345
 346     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
 347          ttfonts-zh_CN fonts-ja fonts-hebrew
 348
 349 Debian GNU/Linux
 350
 351    apt-get install emacs-intl-fonts xfonts-intl-.* \
 352         ttf-kochi-gothic ttf-kochi-mincho \
 353         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
 354 @end verbatim
 355