]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/install.itely
Factorize the format-metronome-markup
[lilypond.git] / Documentation / user / install.itely
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 \version "2.11.61"
11
12 @ifclear INSTALL
13 @node Install
14 @chapter Install
15 @end ifclear
16
17 There are two sets of releases for LilyPond: stable releases, and
18 unstable development releases.  Stable versions have an even-numbered
19 @q{minor} version number (i.e. 2.8, 2.10, 2.12, etc).  Development
20 versions have an odd-numbered @q{minor} version number (i.e. 2.7, 2.9,
21 2.11, etc).
22
23 Building LilyPond is a very involved process, so we @strong{highly}
24 recommend using the precompiled binaries.
25
26 @menu
27 * Precompiled binaries::
28 * Compiling from source::
29 @end menu
30
31
32 @node Precompiled binaries
33 @section Precompiled binaries
34
35 @unnumberedsubsec Downloading
36
37 Check out @uref{http://lilypond.org/web/install/} for up to date
38 information on binary packages for your platform.  If your operating
39 system is not covered on that general page, please see the complete list
40 at @uref{http://download.linuxaudio.org/lilypond/binaries/}
41
42 We currently create binaries for
43
44 @example
45 darwin-ppc  - MacOS X powerpc
46 darwin-x86  - MacOS X intel
47 freebsd-64  - FreeBSD 6.x, x86_64
48 freebsd-x86 - FreeBSD 4.x, x86
49 linux-64    - Any GNU/Linux distribution, x86_64
50 linux-ppc   - Any GNU/Linux distribution, powerpc
51 linux-x86   - Any GNU/Linux distribution, x86
52 mingw       - Windows x86
53 @end example
54
55 @knownissues
56
57 If you have MacOS 10.3 or 10.4 and you would like to use Python
58 scripts such as @command{convert-ly} and @command{lilypond-book}, see
59 @ref{Setup for MacOS X,,,lilypond-program,Application Usage}.
60
61
62 @node Compiling from source
63 @section Compiling from source
64
65 @ignore
66 You can also compile LilyPond directly from the source code. This
67 requires that you can read English, so this section is not
68 translated.  If you really want to compile LilyPond, see
69 @iftex
70 @c DO NOT translate the following line at all.
71 @ref{Compiling from source,,,lilypond-program,Application Usage}.
72 @end iftex
73 @ifhtml
74 @c Please translate the following line (but not the .html file name)
75 the @uref{Compiling-from-source.html,documentation in English}.
76 @end ifhtml
77 @end ignore
78
79 @c TRANSLATORS:
80 @c   Please **do not** translate anything below this line.  Users
81 @c   should not be compiling LilyPond themselves; if they really
82 @c   want to do so, they should be able to read the English docs,
83 @c   because they'll probably need to ask questions in English
84 @c   on the -devel list.   -gp
85 @c Instead, please uncomment and translate the paragraph above,
86 @c and remove all stuff (menu, nodes, contents) below this line.
87
88 @menu
89 * Downloading source code::
90 * Requirements::
91 * Building LilyPond::
92 * Building documentation::
93 * Testing LilyPond::
94 * Problems::
95 @end menu
96
97 @node Downloading source code
98 @subsection Downloading source code
99
100 Download source
101
102 @itemize
103 @item tarballs from
104 @uref{http://lilypond.org/download/} by HTTP.
105 @item tarballs from
106 @uref{http://download.linuxaudio.org/lilypond/} by HTTP.
107 @item
108 GIT from @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=summary,git.sv.gnu.org}
109
110 @example
111 git clone git://git.sv.gnu.org/lilypond.git
112 @end example
113
114 The repository does not contain generated files.  To create
115 @file{configure}, run
116 @example
117 ./autogen.sh
118 @end example
119 @end itemize
120
121 For information on packaging, see @uref{http://lilypond.org/devel}.
122
123
124 @node Requirements
125 @subsection Requirements
126
127 @unnumberedsubsubsec Compilation
128
129 In addition to the packages needed for running LilyPond (see below), you
130 need the following extra packages for building.
131
132 When installing a binary package FOO, you may need to install the
133 FOO-devel, libFOO-dev or FOO-dev package too.
134
135 @itemize
136
137 @item @uref{http://fontforge.sf.net/,FontForge} 20060125 or newer.
138
139 @item @uref{http://metafont.tutorial.free.fr/,MetaFont} (mf-nowin, mf, mfw or
140 mfont binaries) and @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html,MetaPost}
141 (mpost binary), usually packaged with a @LaTeX{} distribution like
142 tetex or texlive.
143
144 @item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils,t1utils}
145 (version 1.33 or newer recommended).
146
147 @item New Century Schoolbook fonts, as PFB files.  These are shipped with
148 X11 and Ghostscript, and are named @file{c059033l.pfb}
149 @file{c059036l.pfb}, @file{c059013l.pfb} and @file{c059016l.pfb}.
150
151 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE} (version
152 1.8.2 or newer).  If you are installing binary packages, you may need to
153 install guile-devel or guile-dev or libguile-dev too.
154
155 @item @uref{ftp://ftp.gnu.org/gnu/texinfo/,Texinfo} (version 4.11 or newer).
156
157 @item @uref{http://gcc.gnu.org/, The GNU c++ compiler} (version 3.4 or
158 newer.  4.x is strongly recommended).
159
160 @item @uref{http://www.python.org,Python} (version 2.4 or newer)
161
162 @item @uref{ftp://ftp.gnu.org/gnu/make/,GNU Make} (version 3.78 or newer).
163
164 @item @uref{http://www.gnu.org/software/gettext/gettext.html,gettext}.
165
166 @item @uref{http://www.gnu.org/software/flex/,Flex}.
167
168 @item @uref{http://www.perl.org/,Perl}.
169
170 @item @uref{http://www.gnu.org/software/flex/,GNU Bison}.
171
172 @item All packages required for running, including development packages with
173 header files and libraries.
174
175 @end itemize
176
177
178 @unnumberedsubsubsec Running requirements
179
180 Running LilyPond requires proper installation of the following software
181
182 @itemize
183
184 @item @uref{http://www.freetype.org/,Freetype} (version 2.1.10 or newer).
185 @item @uref{http://www.freetype.org/,FontConfig} (version 2.2).
186 @item @uref{http://www.pango.org/,Pango} (version 1.12 or newer).
187 @item @uref{http://www.gnu.org/software/guile/guile.html,GUILE}
188 (version 1.8.2 or newer), or patch 1.8.1 with
189 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.8-rational.patch}.
190 @item @uref{http://www.python.org,Python} (version 2.4 or newer).
191 @item @uref{http://www.ghostscript.com,Ghostscript} (version 8.15 or
192 newer. 8.50 recommended)
193 @item Dejaview.  (This is normally installed by default)
194 @end itemize
195
196 International fonts are required to create music with international text
197 or lyrics.
198
199
200 @unnumberedsubsubsec Requirements for building documentation
201
202 You can view the documentation online at
203 @uref{http://lilypond.org/doc/}, but you can also build it locally.
204 This process requires a successful compile of LilyPond, and some
205 additional tools and packages:
206
207 @itemize
208 @item The @uref{http://netpbm.sourceforge.net/,netpbm utilities}
209 @item ImageMagick
210 @item International fonts (see input/regression/utf-8.ly for hints
211 about which font packages are necessary for your platform)
212 @item Ghostscript, 8.50 with the patch from
213 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688154}
214 and the patch from
215 @uref{http://bugs.ghostscript.com/show_bug.cgi?id=688017}, or use
216 a release of Ghostscript which includes these patches, for example
217 8.60 or newer.
218 @item @uref{http://www.nongnu.org/texi2html/,Texi2HTML} 1.79 or newer
219 is strongly recommended to build documentation in HTML; support for
220 building HTML documentation using @command{makeinfo} from GNU Texinfo
221 is deprecated.
222 @end itemize
223
224
225 @node Building LilyPond
226 @subsection Building LilyPond
227
228 @unnumberedsubsubsec Compiling
229
230 To install GNU LilyPond, type
231
232 @example
233 gunzip -c lilypond-x.y.z | tar xf -
234 cd lilypond-x.y.z
235 ./configure             # run with --help for applicable options
236 make
237 su -c 'make install'
238 @end example
239
240 @noindent
241 If you are not root, you should choose a @code{--prefix} argument that
242 points into your home directory, e.g.
243
244 @example
245 ./configure --prefix=$HOME/usr
246 @end example
247
248
249 @unnumberedsubsubsec Compiling for multiple platforms
250
251 If you want to build multiple versions of LilyPond with different
252 configuration settings, you can use the @code{--enable-config=CONF}
253 option of @command{configure}.  You should use @code{make conf=CONF}
254 to generate the output in @file{out-CONF}.  For example, suppose you
255 want to build with and without profiling, then use the following for
256 the normal build
257
258 @example
259 ./configure --prefix=$HOME/usr/ --enable-checking
260 make
261 make install
262 @end example
263
264 and for the profiling version, specify a different configuration
265
266 @example
267 ./configure --prefix=$HOME/usr/ --enable-profiling --enable-config=prof --disable-checking
268 make conf=prof
269 make conf=prof install
270 @end example
271
272
273 @unnumberedsubsubsec Compiling outside the source tree
274
275 It is possible to compile LilyPond in a build tree different from the
276 source tree, with @code{--srcdir} option of @command{configure}:
277
278 @example
279 mkdir lily-build && cd lily-build
280 @var{sourcedir}/configure --srcdir=@var{sourcedir}
281
282 @end example
283
284
285 @unnumberedsubsubsec Useful @command{make} variables
286
287 If a less verbose build output if desired, the variable
288 @code{QUIET_BUILD} may be set to @code{1} on @command{make} command
289 line, or in @file{local.make} at top of the build tree.
290
291
292 @node Building documentation
293 @subsection Building documentation
294
295 This requires a successful compile of LilyPond, or using an external
296 LilyPond binary.
297
298 @menu
299 * Commands for building documentation:: Compiling and installing the documentation.
300 * Building documentation without compiling LilyPond:: Using a LilyPond binary already installed.
301 @end menu
302
303 @node Commands for building documentation
304 @unnumberedsubsubsec Commands for building documentation
305
306 The documentation is built by issuing
307
308 @example
309 make web
310 @end example
311
312 After compilation, the HTML documentation tree is available in
313 @file{out-www/offline-root/}, and can be browsed locally.
314
315 The HTML and PDF files can be installed into the standard documentation
316 path by issuing
317
318 @example
319 make web-install
320 @end example
321
322 @noindent
323 This also installs Info documentation with images if the installation
324 prefix is properly set; otherwise, instructions for manual installation
325 of Info documentation are printed on standard output.
326
327 It is also possible to build a documentation tree in
328 @file{out-www/online-root/}, with special processing, so it can be used
329 on a website with content negotiation for automatic language selection;
330 this can be achieved by issuing
331
332 @example
333 make WEB_TARGETS=online web
334 @end example
335
336 @noindent
337 and both @q{offline} and @q{online} targets can be generated by issuing
338
339 @example
340 make WEB_TARGETS="offline online" web
341 @end example
342
343 Several targets are available to clean the documentation build and
344 help with maintaining documentation; an overview of these targets is
345 available with
346
347 @example
348 make help
349 @end example
350
351 @noindent
352 from every directory in the build tree.  Most targets for
353 documentation maintenance are available from @file{Documentation/};
354 for more information, see @file{Documentation/user/README.txt} and
355 @file{Documentation/TRANSLATION}.
356
357 The makefile variable @code{QUIET_BUILD} may be set to @code{1} for a
358 less verbose build output, just like for building the programs.
359
360 @knownissues
361
362 The most time consuming task for building the documentation is running
363 LilyPond to build images of music, and there cannot be several
364 simultaneously running @command{lilypond-book} instances, so @code{-j}
365 @command{make} option does not significantly speed up the build process.
366 To help speed it up, the makefile variable @var{CPU_COUNT} may be set
367 in @file{local.make} or on the command line to the number of
368 @code{.ly} files that LilyPond should process simultaneously, e.g. on
369 a bi-processor or dual core machine
370
371 @example
372 make -j3 CPU_COUNT=3 web
373 @end example
374
375 @noindent
376 The recommended value of @var{CPU_COUNT} is one plus the number of
377 cores or processors, but it is advisable to set it to a smaller value
378 if your system has not enough RAM to run that many simultaneous
379 LilyPond instances.
380
381 If source files have changed since last documentation build, output
382 files that need to be rebuilt are normally rebuilt, even if you do not
383 run @code{make web-clean} first.  However, building dependencies in the
384 documentation are so complex that rebuilding of some targets may not
385 be triggered as they should be; a workaround is to force rebuilding
386 by touching appropriate files, e.g.
387
388 @example
389 touch Documentation/user/*.itely
390 touch input/lsr/*.ly
391 @end example
392
393
394 @node Building documentation without compiling LilyPond
395 @unnumberedsubsubsec Building documentation without compiling LilyPond
396
397 The documentation can be built locally without compiling LilyPond
398 binary, if LilyPond is already installed on your system.
399
400 From a fresh Git checkout, do
401
402 @example
403 ./autogen.sh   # ignore any warning messages
404 cp GNUmakefile.in GNUmakefile
405 make -C python
406 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond web
407 @end example
408
409 Please note that this may break sometimes -- for example, if a new
410 feature is added with a test file in input/regression, even the latest
411 development release of LilyPond will fail to build the docs.
412
413 You may build the manual without building all the @file{input/*}
414 stuff: change directory, for example to @file{Documentation/user},
415 issue @code{make web}, which will build documentation in a
416 subdirectory @file{out-www} from the source files in current
417 directory.  In this case, if you also want to browse the documentation
418 in its post-processed form, change back to top directory and issue
419
420 @example
421 make out=www WWW-post
422 @end example
423
424 @knownissues
425
426 You may also need to create a script for @command{pngtopnm} and
427 @code{pnmtopng}.  On GNU/Linux, I use this:
428
429 @verbatim
430 export LD_LIBRARY_PATH=/usr/lib
431 exec /usr/bin/pngtopnm "$@"
432 @end verbatim
433
434 On MacOS@tie{}X, I use this:
435
436 @verbatim
437 export DYLD_LIBRARY_PATH=/sw/lib
438 exec /sw/bin/pngtopnm "$@"
439 @end verbatim
440
441
442
443 @node Testing LilyPond
444 @subsection Testing LilyPond
445
446 @html
447 <a name="testing"></a>
448 @end html
449
450 LilyPond comes with an extensive suite that exercises the entire
451 program.  This suite can be used to automatically check the impact of a
452 change.  This is done as follows
453
454 @example
455 make test-baseline
456 @emph{## apply your changes, compile}
457 make check
458 @end example
459
460 This will leave an HTML page @file{out/test-results/index.html}.  This
461 page shows all the important differences that your change introduced,
462 whether in the layout, MIDI, performance or error reporting.
463
464 To rerun tests, use
465
466 @example
467 make test-redo           @emph{## redo files differing from baseline}
468 make test-clean          @emph{## remove all test results}
469 @end example
470
471 @noindent
472 and then run @code{make check} again.
473
474 For tracking memory usage as part of this test, you will need GUILE
475 CVS; especially the following patch:
476 @uref{http://lilypond.org/vc/gub.darcs/patches/guile-1.9-gcstats.patch}.
477
478 For checking the coverage of the test suite, do the following
479
480 @example
481 ./buildscripts/build-coverage.sh
482 @emph{# uncovered files, least covered first}
483 python ./buildscripts/coverage.py  --summary out-cov/*.cc
484 @emph{# consecutive uncovered lines, longest first}
485 python ./buildscripts/coverage.py  --uncovered out-cov/*.cc
486 @end example
487
488
489 @node Problems
490 @subsection Problems
491
492 For help and questions use @email{lilypond-user@@gnu.org}.  Send bug
493 reports to @email{bug-lilypond@@gnu.org}.
494
495 Bugs that are not fault of LilyPond are documented here.
496
497 @unnumberedsubsubsec Bison 1.875
498
499 There is a bug in bison-1.875: compilation fails with "parse error
500 before `goto'" in line 4922 due to a bug in bison.  To fix, please
501 recompile bison 1.875 with the following fix
502
503 @example
504 $ cd lily; make out/parser.cc
505 $ vi +4919 out/parser.cc
506 # append a semicolon to the line containing "__attribute__ ((__unused__))
507 # save
508 $ make
509 @end example
510
511
512 @unnumberedsubsubsec Solaris
513
514 Solaris7, ./configure
515
516 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
517 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
518 is.  Run configure like
519
520 @example
521 CONFIG_SHELL=/bin/ksh ksh -c ./configure
522 @end example
523
524 @noindent
525 or
526
527 @example
528 CONFIG_SHELL=/bin/bash bash -c ./configure
529 @end example
530
531 @unnumberedsubsubsec FreeBSD
532
533 To use system fonts, dejaview must be installed.  With the default
534 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
535
536 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
537 following line just after the @code{<fontconfig>} line.  (Adjust as necessary
538 for your hierarchy.)
539
540 @example
541 <dir>/usr/X11R6/lib/X11/fonts</dir>
542 @end example
543
544
545 @unnumberedsubsubsec International fonts
546
547 On MacOS@tie{}X, all fonts are installed by default.  However, finding all
548 system fonts requires a bit of configuration; see
549 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
550 this post} on the @code{lilypond-user} mailing list.
551
552 On Linux, international fonts are installed by different means on
553 every distribution.  We cannot list the exact commands or packages
554 that are necessary, as each distribution is different, and the exact
555 package names within each distribution changes.  Here are some
556 hints, though:
557
558 @verbatim
559 Red Hat Fedora
560
561     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
562          ttfonts-zh_CN fonts-ja fonts-hebrew
563
564 Debian GNU/Linux
565
566    apt-get install emacs-intl-fonts xfonts-intl-.* \
567         ttf-kochi-gothic ttf-kochi-mincho \
568         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
569 @end verbatim
570