]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/included/compile.itexi
Doc:CG: fix typo on DYLD_FALLBACK_LIBRARY_PATH for OSX
[lilypond.git] / Documentation / included / compile.itexi
1 @c -*- coding: utf-8; mode: texinfo; -*-
2
3
4 @c DO NOT TRANSLATE THIS FILE
5
6 @c include any node/sections from the higher-level *texi file.
7 @c   @n ode Compiling from source
8 @c   @s ection Compiling from source
9
10
11 @menu
12 * Overview of compiling::
13 * Requirements::
14 * Getting the source code::
15 * Configuring @command{make}::
16 * Compiling LilyPond::
17 * Post-compilation options::
18 * Problems::
19 * Concurrent stable and development versions::
20 * Using a Virtual Machine to Compile LilyPond::
21 * Build system::
22 @end menu
23
24
25 @node Overview of compiling
26 @section Overview of compiling
27
28 Compiling LilyPond from source is an involved process, and is only
29 recommended for developers and packagers.  Typical program users
30 are instead encouraged to obtain the program from a package
31 manager (on Unix) or by downloading a precompiled binary
32 configured for a specific operating system.  Pre-compiled binaries
33 are available on the @rweb{Download} page.
34
35 Compiling LilyPond from source is necessary if you want to build,
36 install, or test your own version of the program.
37
38 A successful compile can also be used to generate and install the
39 documentation, incorporating any changes you may have made.
40 However, a successful compile is not a requirement for generating
41 the documentation.  The documentation can be built using a Git
42 repository in conjunction with a locally installed copy of the
43 program.  For more information, see @ref{Building documentation
44 without compiling}.
45
46 Attempts to compile LilyPond natively on Windows have been
47 unsuccessful, though a workaround is available (see @ref{Using a
48 Virtual Machine to Compile LilyPond}).
49
50
51 @node Requirements
52 @section Requirements
53
54
55 @menu
56 * Requirements for running LilyPond::
57 * Requirements for compiling LilyPond::
58 * Requirements for building documentation::
59 @end menu
60
61
62 @node Requirements for running LilyPond
63 @subsection Requirements for running LilyPond
64
65 Running LilyPond requires proper installation of the following
66 software:
67
68 @itemize
69 @item @uref{http://www.dejavu-fonts.org/, DejaVu fonts} (normally
70 installed by default)
71
72 @item @uref{http://www.fontconfig.org/, FontConfig} (2.2 or newer)
73
74 @item @uref{http://www.freetype.org/, Freetype} (2.1.10 or newer)
75
76 @item @uref{http://www.ghostscript.com, Ghostscript} (8.60 or
77 newer)
78
79 @item @uref{http://www.gnu.org/software/guile/guile.html, Guile}
80 (1.8.2 or newer)
81
82 @item @uref{http://www.pango.org/, Pango} (1.12 or newer)
83
84 @item @uref{http://www.python.org, Python} (2.4 or newer)
85 @end itemize
86
87 International fonts are required to create music with
88 international text or lyrics.
89
90
91 @node Requirements for compiling LilyPond
92 @subsection Requirements for compiling LilyPond
93
94 Below is a full list of packages needed to build LilyPond.
95 However, for most common distributions there is an easy way of
96 installing most all build dependencies in one go:
97
98 @multitable @columnfractions .5 .5
99 @headitem Distribution @tab Command
100 @item Debian, Ubuntu
101 @tab @code{sudo apt-get build-dep lilypond}
102
103 @item Fedora, RHEL
104 @tab @code{sudo yum-builddep lilypond}
105
106 @item openSUSE, SLED
107 @c sorry for the idiosyncratic command, I really asked and argued
108 @c for "zypper build-dep" :-(
109 @tab @code{sudo zypper --build-deps-only source-install lilypond}
110 @end multitable
111
112 @itemize
113 @item Everything listed in @ref{Requirements for running
114 LilyPond}
115
116 @item Development packages for the above items (which should
117 include header files and libraries).
118
119 Red Hat Fedora:
120
121 @c ghostscript-devel-[version] isn't needed
122 @example
123 guile-devel-@var{version}
124 fontconfig-devel-@var{version}
125 freetype-devel-@var{version}
126 pango-devel-@var{version}
127 python-devel-@var{version}
128 @end example
129
130 Debian GNU/Linux:
131
132 @c libgs-dev isn't needed
133 @example
134 guile-@var{version}-dev
135 libfontconfig1-dev
136 libfreetype6-dev
137 libpango1.0-dev
138 python@var{version}-dev
139 @end example
140
141 @item @uref{http://flex.sourceforge.net/, Flex}
142
143 @item @uref{http://fontforge.sf.net/, FontForge} (20060125 or
144 newer)
145
146 @item @uref{http://www.gnu.org/software/bison/, GNU Bison}
147
148 @item @uref{http://gcc.gnu.org/, GNU Compiler Collection} (3.4 or
149 newer, 4.@var{x} recommended)
150
151 @item @uref{http://www.gnu.org/software/gettext/gettext.html, GNU
152 gettext} (0.17 or newer)
153
154 @item @uref{http://www.gnu.org/software/make/, GNU Make} (3.78 or
155 newer)
156
157 @item @uref{http://metafont.tutorial.free.fr/, MetaFont}
158 (mf-nowin, mf, mfw or mfont binaries), usually packaged with
159 @uref{http://www.latex-project.org/ftp.html, @TeX{}}.
160
161 @item @uref{http://cm.bell-labs.com/who/hobby/MetaPost.html,
162 MetaPost} (mpost binary), usually packaged with
163 @uref{http://www.latex-project.org/ftp.html, @TeX{}}.
164
165 @item @uref{http://www.perl.org/, Perl}
166
167 @item @uref{http://www.gnu.org/software/texinfo/, Texinfo} (4.11
168 or newer)
169
170 @item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils, Type 1
171 utilities} (1.33 or newer recommended)
172 @end itemize
173
174
175 @node Requirements for building documentation
176 @subsection Requirements for building documentation
177
178 You can view the documentation online at
179 @uref{http://www.lilypond.org/doc/}, but you can also build it
180 locally.  This process requires some additional tools and
181 packages:
182
183 @itemize
184 @item Everything listed in @ref{Requirements for compiling
185 LilyPond}
186
187 @item @uref{http://www.imagemagick.org/, ImageMagick}
188
189 @item @uref{http://netpbm.sourceforge.net/, Netpbm}
190
191 @item @uref{http://rsync.samba.org/, rsync}
192
193 @item @uref{http://www.nongnu.org/texi2html/, Texi2HTML} (1.82)
194
195 @item International fonts
196
197 Red Hat Fedora:
198
199 @example
200 fonts-arabic
201 fonts-hebrew
202 fonts-ja
203 fonts-xorg-truetype
204 taipeifonts
205 ttfonts-ja
206 ttfonts-zh_CN
207 @end example
208
209 Debian GNU/Linux:
210
211 @example
212 emacs-intl-fonts
213 ttf-kochi-gothic
214 ttf-kochi-mincho
215 xfonts-bolkhov-75dpi
216 xfonts-cronyx-75dpi
217 xfonts-cronyx-100dpi
218 xfonts-intl-.*
219 @end example
220 @end itemize
221
222
223 @node Getting the source code
224 @section Getting the source code
225
226
227 @subheading Downloading the Git repository
228
229 In general, developers compile LilyPond from within a local Git
230 repository.  Setting up a local Git repository is explained in
231 @rcontrib{Starting with Git}.
232
233
234 @subheading Downloading a source tarball
235
236 Packagers are encouraged to use source tarballs for compiling.
237 The tarball for the latest stable release is available on the
238 @rweb{Source} page.
239
240 @noindent
241 All tagged releases (including legacy stable
242 versions and the most recent development release) are available
243 here:
244
245 @example
246 @uref{http://download.linuxaudio.org/lilypond/source/}
247 @end example
248
249 Download the tarball to your @file{~/src/} directory, or some
250 other appropriate place.
251
252 @warning{Be careful where you unpack the tarball!  Any
253 subdirectories of the current folder named @file{lilypond/} or
254 @file{lilypond-@var{x.y.z}/} (where @var{x.y.z} is the release
255 number) will be overwritten if there is a name clash with the
256 tarball.}
257
258 Unpack the tarball with this command:
259
260 @example
261 tar -xzf lilypond-@var{x.y.z}.tar.gz
262 @end example
263
264 This creates a subdirectory within the current directory called
265 @file{lilypond-@var{x.y.z}/}.  Once unpacked, the source files
266 occupy about 40 MB of disk space.
267
268
269 @node Configuring @command{make}
270 @section Configuring @command{make}
271
272
273 @menu
274 * Running @command{./autogen.sh}::
275 * Running @command{./configure}::
276 @end menu
277
278
279 @node Running @command{./autogen.sh}
280 @subsection Running @command{./autogen.sh}
281
282 After you unpack the tarball (or download the Git repository), the
283 contents of your top source directory should be similar to the
284 current source tree listed at
285 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree}.
286
287 Next, you need to create the generated files; enter the following
288 command from your top source directory:
289
290 @example
291 ./autogen.sh
292 @end example
293
294 This will:
295
296 @enumerate
297 @item generate a number of files and directories to aid
298 configuration, such as @file{configure}, @file{README.txt}, etc.
299
300 @item automatically run the @command{./configure} command.
301 @end enumerate
302
303
304 @node Running @command{./configure}
305 @subsection Running @command{./configure}
306
307 @menu
308 * Configuration options::
309 * Checking build dependencies::
310 * Configuring target directories::
311 * Making an out-of-tree build::
312 @end menu
313
314
315 @node Configuration options
316 @unnumberedsubsubsec Configuration options
317
318 The @command{./configure} command (generated by
319 @command{./autogen.sh}) provides many options for configuring
320 @command{make}.  To see them all, run:
321
322 @example
323 ./configure --help
324 @end example
325
326
327 @node Checking build dependencies
328 @unnumberedsubsubsec Checking build dependencies
329
330 When @command{./configure} is run without any arguments, it will
331 check to make sure your system has everything required for
332 compilation.  This is done automatically when
333 @command{./autogen.sh} is run.  If any build dependency is
334 missing, @command{./configure} will return with:
335
336 @example
337 ERROR: Please install required programs:  @var{foo}
338 @end example
339
340 The following message is issued if you are missing programs that
341 are only needed for building the documentation:
342
343 @example
344 WARNING: Please consider installing optional programs:  @var{bar}
345 @end example
346
347 If you intend to build the documentation locally, you will need to
348 install or update these programs accordingly.
349
350 @warning{@command{./configure} may fail to issue warnings for
351 certain documentation build requirements that are not met.  If you
352 experience problems when building the documentation, you may need
353 to do a manual check of @ref{Requirements for building
354 documentation}.}
355
356
357 @node Configuring target directories
358 @unnumberedsubsubsec Configuring target directories
359
360 If you intend to use your local build to install a local copy of
361 the program, you will probably want to configure the installation
362 directory.  Here are the relevant lines taken from the output of
363 @command{./configure@tie{}--help}:
364
365 @quotation
366 By default, `@command{make@tie{}install}' will install all the
367 files in @file{/usr/local/bin}, @file{/usr/local/lib} etc.  You
368 can specify an installation prefix other than @file{/usr/local}
369 using `@code{--prefix}', for instance `@code{--prefix=$HOME}'.
370 @end quotation
371
372 A typical installation prefix is @file{$HOME/usr}:
373
374 @example
375 ./configure --prefix=$HOME/usr
376 @end example
377
378 Note that if you plan to install a local build on a system where
379 you do not have root privileges, you will need to do something
380 like this anyway---@command{make@tie{}install} will only succeed
381 if the installation prefix points to a directory where you have
382 write permission (such as your home directory).  The installation
383 directory will be automatically created if necessary.
384
385 The location of the @command{lilypond} command installed by this
386 process will be @file{@var{prefix}/bin/lilypond}; you may want to
387 add @file{@var{prefix}/bin/} to your @code{$PATH} if it is not
388 already included.
389
390 It is also possible to specify separate installation directories
391 for different types of program files.  See the full output of
392 @command{./configure@tie{}--help} for more information.
393
394 If you encounter any problems, please see @ref{Problems}.
395
396
397 @node Making an out-of-tree build
398 @unnumberedsubsubsec Making an out-of-tree build
399
400 It is possible to compile LilyPond in a build tree different from
401 the source tree, using the @option{--srcdir} option of
402 @command{configure}.  Note that in some cases you may need to
403 remove the output of a previous @command{configure} command by
404 running @command{make@tie{}distclean} in the main source directory
405 before configuring the out-of-tree build:
406
407 @example
408 make distclean
409 mkdir lily-build && cd lily-build
410 @var{sourcedir}/configure --srcdir=@var{sourcedir}
411 @end example
412
413
414 @node Compiling LilyPond
415 @section Compiling LilyPond
416
417
418 @menu
419 * Using @command{make}::
420 * Saving time with the @option{-j} option::
421 * Compiling for multiple platforms::
422 * Useful @command{make} variables::
423 @end menu
424
425
426 @node Using @command{make}
427 @subsection Using @command{make}
428
429 LilyPond is compiled with the @command{make} command.  Assuming
430 @command{make} is configured properly, you can simply run:
431
432 @example
433 make
434 @end example
435
436 @samp{make} is short for @samp{make all}.  To view a list of @command{make}
437 targets, run:
438
439 @example
440 make help
441 @end example
442
443 TODO: Describe what @command{make} actually does.
444
445
446 @node Saving time with the @option{-j} option
447 @subsection Saving time with the @option{-j} option
448
449 If your system has multiple CPUs, you can speed up compilation by
450 adding @samp{-j@var{X}} to the @command{make} command, where
451 @samp{@var{X}} is one more than the number of cores you have.  For
452 example, a typical Core2Duo machine would use:
453
454 @example
455 make -j3
456 @end example
457
458 If you get errors using the @option{-j} option, and @samp{make}
459 succeeds without it, try lowering the @code{@var{X}} value.
460
461
462 @node Compiling for multiple platforms
463 @subsection Compiling for multiple platforms
464
465 If you want to build multiple versions of LilyPond with different
466 configuration settings, you can use the
467 @code{--enable-config=@var{CONF}} option of @command{configure}.
468 You should use @code{make@tie{}conf=@var{CONF}} to generate the
469 output in @file{out-@var{CONF}}.  For example, suppose you want to
470 build with and without profiling, then use the following for the
471 normal build
472
473 @example
474 ./configure --prefix=$HOME/usr/ --enable-checking
475 make
476 @end example
477
478 and for the profiling version, specify a different configuration
479
480 @example
481 ./configure --prefix=$HOME/usr/ --enable-profiling \
482   --enable-config=prof --disable-checking
483 make conf=prof
484 @end example
485
486 If you wish to install a copy of the build with profiling, don't
487 forget to use @code{conf=@var{CONF}} when issuing
488 @command{make@tie{}install}:
489
490 @example
491 make conf=prof install
492 @end example
493
494
495 @seealso
496 @ref{Installing LilyPond from a local build}
497
498
499 @node Useful @command{make} variables
500 @subsection Useful @command{make} variables
501
502 If a less verbose build output if desired, the variable
503 @code{QUIET_BUILD} may be set to @code{1} on @command{make}
504 command line, or in @file{local.make} at top of the build tree.
505
506
507 @node Post-compilation options
508 @section Post-compilation options
509
510
511 @menu
512 * Installing LilyPond from a local build::
513 * Generating documentation::
514 * Testing LilyPond::
515 @end menu
516
517
518 @node Installing LilyPond from a local build
519 @subsection Installing LilyPond from a local build
520
521 If you configured @command{make} to install your local build in a
522 directory where you normally have write permission (such as your
523 home directory), and you have compiled LilyPond by running
524 @command{make}, you can install the program in your target
525 directory by running:
526
527 @example
528 make install
529 @end example
530
531 If instead, your installation directory is not one that you can
532 normally write to (such as the default @file{/usr/local/}, which
533 typically is only writeable by the superuser), you will need to
534 temporarily become the superuser when running
535 @command{make@tie{}install}:
536
537 @example
538 sudo make install
539 @end example
540
541 @noindent
542 or...
543
544 @example
545 su -c 'make install'
546 @end example
547
548 If you don't have superuser privileges, then you need to configure
549 the installation directory to one that you can write to, and then
550 re-install.  See @ref{Configuring target directories}.
551
552
553 @node Generating documentation
554 @subsection Generating documentation
555
556
557 @menu
558 * Documentation editor's edit/compile cycle::
559 * Building documentation::
560 * Saving time with @code{CPU_COUNT}::
561 * Installing documentation::
562 * Building documentation without compiling::
563 @end menu
564
565
566 @node Documentation editor's edit/compile cycle
567 @unnumberedsubsubsec Documentation editor's edit/compile cycle
568
569 @itemize
570 @item
571 Initial documentation build:
572
573 @example
574 make [-j@var{X}]
575 make [-j@var{X} CPU_COUNT=@var{X}] doc  @emph{## can take an hour or more}
576 @end example
577
578 @item
579 Edit/compile cycle:
580
581 @example
582 @emph{## edit source files, then...}
583
584 make [-j@var{X}]                  @emph{## needed if editing outside}
585                             @emph{##   Documentation/, but useful anyway}
586                             @emph{##   for finding Texinfo errors.}
587 touch Documentation/*te??   @emph{## bug workaround}
588 make [-j@var{X} CPU_COUNT=@var{X}] doc  @emph{## usually faster than initial build.}
589 @end example
590
591 @item
592 Reset:
593
594 @example
595 make doc-clean              @emph{## use only as a last resort.}
596 @end example
597 @end itemize
598
599 @node Building documentation
600 @unnumberedsubsubsec Building documentation
601
602 After a successful compile (using @command{make}), the
603 documentation can be built by issuing:
604
605 @example
606 make doc
607 @end example
608
609 The first time you run @command{make@tie{}doc}, the process can
610 easily take an hour or more.  After that, @command{make@tie{}doc}
611 only makes changes to the pre-built documentation where needed,
612 so it may only take a minute or two to test changes if the
613 documentation is already built.
614
615 If @command{make@tie{}doc} succeeds, the HTML documentation tree
616 is available in @file{out-www/offline-root/}, and can be browsed
617 locally.  Various portions of the documentation can be found by
618 looking in @file{out/} and @file{out-www} subdirectories in other
619 places in the source tree, but these are only @emph{portions} of
620 the docs.  Please do not complain about anything which is broken
621 in those places; the only complete set of documentation is in
622 @file{out-www/offline-root/} from the top of the source tree.
623
624 Compilation of documentation in Info format with images can be
625 done separately by issuing:
626
627 @example
628 make info
629 @end example
630
631 @knownissues
632
633 If source files have changed since the last documentation build,
634 output files that need to be rebuilt are normally rebuilt, even if
635 you do not run @code{make@tie{}doc-clean} first.  However, build
636 dependencies in the documentation are so complex that some
637 newly-edited files may not be rebuilt as they should be; a
638 workaround is to @command{touch} the top source file for any
639 manual you've edited.  For example, if you make changes to a file
640 in @file{notation/}, do:
641
642 @example
643 touch Documentation/notation.tely
644 @end example
645
646 @noindent
647 The top sources possibly affected by this are:
648
649 @example
650 Documentation/extend.texi
651 Documentation/changes.tely
652 Documentation/contributor.texi
653 Documentation/essay.tely
654 Documentation/extending.tely
655 Documentation/learning.tely
656 Documentation/notation.tely
657 Documentation/snippets.tely
658 Documentation/usage.tely
659 Documentation/web.texi
660 @end example
661
662 @noindent
663 You can @command{touch} all of them at once with:
664
665 @example
666 touch Documentation/*te??
667 @end example
668
669 @noindent
670 However, this will rebuild all of the manuals
671 indiscriminately---it is more efficient to @command{touch} only
672 the affected files.
673
674
675 @node Saving time with @code{CPU_COUNT}
676 @unnumberedsubsubsec Saving time with @code{CPU_COUNT}
677
678 The most time consuming task for building the documentation is
679 running LilyPond to build images of music, and there cannot be
680 several simultaneously running @command{lilypond-book} instances,
681 so the @option{-j} @command{make} option does not significantly
682 speed up the build process.  To help speed it up, the makefile
683 variable @option{CPU_COUNT} may be set in @file{local.make} or on
684 the command line to the number of @code{.ly} files that LilyPond
685 should process simultaneously, e.g. on a bi-processor or dual core
686 machine:
687
688 @example
689 make -j3 CPU_COUNT=3 doc
690 @end example
691
692 @noindent
693 The recommended value of @option{CPU_COUNT} is one plus the number
694 of cores or processors, but it is advisable to set it to a smaller
695 value unless your system has enough RAM to run that many
696 simultaneous LilyPond instances.  Also, values for the @option{-j}
697 option that pose problems with @samp{make} are less likely to pose
698 problems with @samp{make doc} (this applies to both @option{-j}
699 and @option{CPU_COUNT}).  For example, with a quad-core processor,
700 it is possible for @samp{make -j5 CPU_COUNT=5 doc} to work
701 consistently even if @samp{make -j5} rarely succeeds.
702
703
704 @node Installing documentation
705 @unnumberedsubsubsec Installing documentation
706
707 The HTML, PDF and if available Info files can be installed into
708 the standard documentation path by issuing
709
710 @example
711 make install-doc
712 @end example
713
714 @noindent
715 This also installs Info documentation with images if the
716 installation prefix is properly set; otherwise, instructions to
717 complete proper installation of Info documentation are printed on
718 standard output.
719
720 To install the Info documentation separately, run:
721
722 @example
723 make install-info
724 @end example
725
726 @noindent
727 Note that to get the images in Info documentation, @code{install-doc}
728 target creates symbolic links to HTML and PDF installed documentation
729 tree in @file{@var{prefix}/share/info}, in order to save disk space,
730 whereas @code{install-info} copies images in
731 @file{@var{prefix}/share/info} subdirectories.
732
733 It is possible to build a documentation tree in
734 @file{out-www/online-root/}, with special processing, so it can be
735 used on a website with content negotiation for automatic language
736 selection; this can be achieved by issuing
737
738 @example
739 make WEB_TARGETS=online doc
740 @end example
741
742 @noindent
743 and both @q{offline} and @q{online} targets can be generated by issuing
744
745 @example
746 make WEB_TARGETS="offline online" doc
747 @end example
748
749 Several targets are available to clean the documentation build and
750 help with maintaining documentation; an overview of these targets is
751 available with
752
753 @example
754 make help
755 @end example
756
757 @noindent
758 from every directory in the build tree.  Most targets for
759 documentation maintenance are available from
760 @file{Documentation/}; for more information, see
761 @rcontrib{Documentation work}.
762
763 The makefile variable @code{QUIET_BUILD} may be set to @code{1}
764 for a less verbose build output, just like for building the
765 programs.
766
767
768 @node Building documentation without compiling
769 @unnumberedsubsubsec Building documentation without compiling
770
771
772 The documentation can be built locally without compiling LilyPond
773 binary, if LilyPond is already installed on your system.
774
775 From a fresh Git checkout, do
776
777 @example
778 ./autogen.sh   # ignore any warning messages
779 cp GNUmakefile.in GNUmakefile
780 make -C scripts && make -C python
781 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
782 @end example
783
784 Please note that this may break sometimes -- for example, if a new
785 feature is added with a test file in input/regression, even the latest
786 development release of LilyPond will fail to build the docs.
787
788 You may build the manual without building all the @file{input/*} stuff
789 (i.e. mostly regression tests): change directory, for example to
790 @file{Documentation/}, issue @code{make doc}, which will build
791 documentation in a subdirectory @file{out-www} from the source files in
792 current directory.  In this case, if you also want to browse the
793 documentation in its post-processed form, change back to top directory
794 and issue
795
796 @example
797 make out=www WWW-post
798 @end example
799
800 @knownissues
801
802 You may also need to create a script for @command{pngtopnm} and
803 @code{pnmtopng}.  On GNU/Linux, I use this:
804
805 @verbatim
806 export LD_LIBRARY_PATH=/usr/lib
807 exec /usr/bin/pngtopnm "$@"
808 @end verbatim
809
810 On MacOS X with fink, I use this:
811
812 @verbatim
813 export DYLD_LIBRARY_PATH=/sw/lib
814 exec /sw/bin/pngtopnm "$@"
815 @end verbatim
816
817 On MacOS X with macports, you should use this:
818
819 @verbatim
820 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
821 exec /opt/local/bin/pngtopnm "$@"
822 @end verbatim
823
824
825 @node Testing LilyPond
826 @subsection Testing LilyPond
827
828
829 LilyPond comes with an extensive suite that exercises the entire
830 program. This suite can be used to automatically check the impact
831 of a change.
832
833 @menu
834 * Developer's edit/compile/test cycle::
835 * Other tests::
836 @end menu
837
838 @node Developer's edit/compile/test cycle
839 @unnumberedsubsubsec Developer's edit/compile/test cycle
840
841 TODO: is @code{[-j@var{X} CPU_COUNT=@var{X}]} useful for
842 @code{test-baseline}, @code{check}, @code{clean},
843 @code{test-redo}?
844
845 @itemize
846 @item
847 Initial test:
848
849 @example
850 make [-j@var{X}]
851 make test-baseline
852 make [-j@var{X} CPU_COUNT=@var{X}] check
853 @end example
854
855 @item
856 Edit/compile/test cycle:
857
858 @example
859 @emph{## edit source files, then...}
860
861 make clean                    @emph{## only if needed (see below)}
862 make [-j@var{X}]                    @emph{## only if needed (see below)}
863 make test-redo                @emph{## redo files differing from baseline}
864 make [-j@var{X} CPU_COUNT=@var{X}] check  @emph{## CPU_COUNT here?}
865 @end example
866
867 @item
868 Reset:
869
870 @example
871 make test-clean
872 @end example
873 @end itemize
874
875 If you modify any source files that have to be compiled (such as
876 @file{.cc} or @file{.hh} files in @file{flower/} or @file{lily/}),
877 then you must run @command{make} before @command{make test-redo},
878 so @command{make} can compile the modified files and relink all
879 the object files.  If you only modify files which are interpreted,
880 like those in the @file{scm/} and @file{ly/} directories, then
881 @command{make} is not needed before @command{make test-redo}.
882
883 Also, if you modify any font definitions in the @file{mf/}
884 directory then you must run @command{make clean} and
885 @command{make} before running @command{make test-redo}.  This will
886 recompile everything, whether modified or not, and takes a lot
887 longer.
888
889 Running @command{make@tie{}check} will leave an HTML page
890 @file{out/test-results/index.html}.  This page shows all the
891 important differences that your change introduced, whether in the
892 layout, MIDI, performance or error reporting.
893
894
895 @node Other tests
896 @unnumberedsubsubsec Other tests
897
898 For tracking memory usage as part of this test, you will need
899 GUILE CVS; especially the following patch:
900 @uref{http://www.lilypond.org/vc/old/gub.darcs/patches/guile-1.9-gcstats.patch}.
901
902 For checking the coverage of the test suite, do the following
903
904 @example
905 ./scripts/auxiliar/build-coverage.sh
906 @emph{# uncovered files, least covered first}
907 ./scripts/auxiliar/coverage.py  --summary out-cov/*.cc
908 @emph{# consecutive uncovered lines, longest first}
909 ./scripts/auxiliar/coverage.py  --uncovered out-cov/*.cc
910 @end example
911
912
913 @node Problems
914 @section Problems
915
916 For help and questions use @email{lilypond-user@@gnu.org}.  Send
917 bug reports to @email{bug-lilypond@@gnu.org}.
918
919 Bugs that are not fault of LilyPond are documented here.
920
921 @unnumberedsubsubsec Bison 1.875
922
923 There is a bug in bison-1.875: compilation fails with "parse error
924 before `goto'" in line 4922 due to a bug in bison.  To fix, please
925 recompile bison 1.875 with the following fix
926
927 @example
928 $ cd lily; make out/parser.cc
929 $ vi +4919 out/parser.cc
930 # append a semicolon to the line containing "__attribute__ ((__unused__))
931 # save
932 $ make
933 @end example
934
935
936 @unnumberedsubsubsec Compiling on MacOS@tie{}X
937
938 Here are special instructions for compiling under MacOS@tie{}X.
939 These instructions assume that dependencies are installed using
940 @uref{http://www.macports.org/, MacPorts.} The instructions have
941 been tested using OS X 10.5 (Leopard).
942
943 First, install the relevant dependencies using MacPorts.
944
945 Next, add the following to your relevant shell initialization
946 files. This is @code{~/.profile} by default. You should create
947 this file if it does not exist.
948
949 @example
950 export PATH=/opt/local/bin:/opt/local/sbin:$PATH
951 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
952 @end example
953
954 Now you must edit the generated @code{config.make} file.  Change
955
956 @example
957 FLEXLEXER_FILE = /usr/include/FlexLexer.h
958 @end example
959
960 @noindent
961 to:
962
963 @example
964 FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
965 @end example
966
967 At this point, you should verify that you have the appropriate
968 fonts installed with your ghostscript installation. Check @code{ls
969 /opt/local/share/ghostscript/fonts} for: 'c0590*' files (.pfb,
970 .pfb and .afm).  If you don't have them, run the following
971 commands to grab them from the ghostscript SVN server and install
972 them in the appropriate location:
973
974 @example
975 svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
976 sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
977 rm -rf urw-fonts-1.07pre44
978 @end example
979
980 Now run the @code{./configure} script. To avoid complications with
981 automatic font detection, add
982
983 @example
984 --with-ncsb-dir=/opt/local/share/ghostscript/fonts
985 @end example
986
987
988 @unnumberedsubsubsec Solaris
989
990 Solaris7, ./configure
991
992 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
993 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
994 is.  Run configure like
995
996 @example
997 CONFIG_SHELL=/bin/ksh ksh -c ./configure
998 @end example
999
1000 @noindent
1001 or
1002
1003 @example
1004 CONFIG_SHELL=/bin/bash bash -c ./configure
1005 @end example
1006
1007 @unnumberedsubsubsec FreeBSD
1008
1009 To use system fonts, dejaview must be installed.  With the default
1010 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
1011
1012 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
1013 following line just after the @code{<fontconfig>} line.  (Adjust as necessary
1014 for your hierarchy.)
1015
1016 @example
1017 <dir>/usr/X11R6/lib/X11/fonts</dir>
1018 @end example
1019
1020
1021 @unnumberedsubsubsec International fonts
1022
1023 On Mac OS X, all fonts are installed by default.  However, finding all
1024 system fonts requires a bit of configuration; see
1025 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
1026 this post} on the @code{lilypond-user} mailing list.
1027
1028 On Linux, international fonts are installed by different means on
1029 every distribution.  We cannot list the exact commands or packages
1030 that are necessary, as each distribution is different, and the exact
1031 package names within each distribution changes.  Here are some
1032 hints, though:
1033
1034 @verbatim
1035 Red Hat Fedora
1036
1037     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
1038          ttfonts-zh_CN fonts-ja fonts-hebrew
1039
1040 Debian GNU/Linux
1041
1042    apt-get install emacs-intl-fonts xfonts-intl-.* \
1043         ttf-kochi-gothic ttf-kochi-mincho \
1044         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
1045 @end verbatim
1046
1047
1048 @unnumberedsubsubsec Using lilypond python libraries
1049
1050 If you want to use lilypond's python libraries (either running
1051 certain build scripts manually, or using them in other programs),
1052 set @code{PYTHONPATH} to @file{python/out} in your build
1053 directory, or @file{.../usr/lib/lilypond/current/python} in the
1054 installation directory structure.
1055
1056
1057
1058
1059 @node Concurrent stable and development versions
1060 @section Concurrent stable and development versions
1061
1062
1063 It can be useful to have both the stable and the development versions
1064 of Lilypond available at once. One way to do this on GNU/Linux is to
1065 install the stable version using the precompiled binary, and run the
1066 development version from the source tree. After running @command{make
1067 all} from the top directory of the Lilypond source files, there will
1068 be a binary called @code{lilypond} in the @code{out} directory:
1069
1070 @example
1071 <@var{path to}>/lilypond/out/bin/lilypond
1072 @end example
1073
1074 This binary can be run without actually doing the @code{make
1075 install} command. The advantage to this is that you can have all
1076 of the latest changes available after pulling from git and running
1077 @code{make all}, without having to uninstall the old version and
1078 reinstall the new.
1079
1080 So, to use the stable version, install it as usual and use the
1081 normal commands:
1082
1083 @example
1084 lilypond foobar.ly
1085 @end example
1086
1087 To use the development version, create a link to the binary in the
1088 source tree by saving the following line in a file somewhere in your
1089 @code{$PATH}:
1090
1091 @example
1092 exec <@var{path to}>/lilypond/out/bin/lilypond "$@@"
1093 @end example
1094
1095 Save it as @code{Lilypond} (with a capital L to distinguish it
1096 from the stable @code{lilypond}), and make it executable:
1097
1098 @example
1099 chmod +x Lilypond
1100 @end example
1101
1102 Then you can invoke the development version this way:
1103
1104 @example
1105 Lilypond foobar.ly
1106 @end example
1107
1108
1109 TODO: ADD
1110
1111 - other compilation tricks for developers
1112
1113
1114 @node Using a Virtual Machine to Compile LilyPond
1115 @section Using a Virtual Machine to Compile LilyPond
1116
1117
1118 TODO: rewrite for lily-git.tcl !!!  do before GOP!  -gp
1119
1120 Since it is not possible to compile Lilypond on Windows, some
1121 developers may find it useful to install a GNU/Linux virtual
1122 machine. A disk image with a special remix of @strong{Ubuntu}
1123 has been created for this purpose. It has all of the Lilypond
1124 build dependencies in place, so that once installed, it is
1125 ready to compile both Lilypond and the Documentation.
1126 The @code{lilybuntu} remix is available for download here:
1127
1128 @example
1129 @uref{http://@/files.lilynet.net/@/lilybuntu.iso}
1130 @end example
1131
1132 We do not necessarily recommend any one virtualization tool,
1133 however the @code{lilybuntu} remix is known to work well on
1134 @uref{http://www.virtualbox.org/wiki/Downloads, Sun VirtualBox},
1135 which is a free download. Consult your virtualization software's
1136 documentation for instructions on setting up the software and
1137 for general instructions on installing a virtual machine.
1138
1139 Steps to setting up @code{lilybuntu} in a virtual machine:
1140
1141 @enumerate
1142 @item Download the @code{lilybuntu} disk image.
1143
1144 @item Install @code{lilybuntu}. You will use the @code{.iso}
1145 file as the boot disk. It should not be necessary to burn it
1146 to a DVD, but consult the documentation for your virtualization
1147 software for specific instructions. If possible, use at least
1148 the recommended amount of RAM for the virtual machine (384 MB on
1149 VirtualBox), and use a dynamically expanding virtual hard drive.
1150 A virtual hard drive with 6 GB will be enough to compile LilyPond,
1151 but if you intend to build the docs and run the regression tests
1152 the virtual hard drive should be at least 10 GB.
1153 The Ubuntu installation should be straightforward, although in the
1154 partitioning stage do not be afraid to select @qq{use entire disk,}
1155 since this is only your @strong{virtual disk} and not your
1156 machine's actual hard drive.
1157
1158 @item After installation is complete, restart the virtual
1159 machine.  If you are using @strong{VirtualBox}, you may wish
1160 to install the @qq{Guest Additions}, which while not essential for
1161 compiling @code{Lilypond} will allow you to use the virtual machine
1162 in full screen, Seamless mode (also known as Unity mode on other
1163 virtualization platforms) and allow you to share clipboards between
1164 the physical and virtual machine.  From the @code{Devices} menu select
1165 @code{Install Guest Additions...}, the @code{VBOXADDITIONS} CDROM device
1166 will appear on the desktop.  Open a @strong{terminal} session.
1167 (@code{Applications > Accessories > Terminal}) and @code{cd} to the
1168 top level of the CDROM.  Run the @code{autorun.sh} script as superuser
1169 (@code{sudo ./autorun.sh }), a console window will open while the
1170 @qq{Guest Additions} are being installed.  Once the script has
1171 been finished, reboot your Virtual Machine to complete the installation
1172 of the @qq{Guest Additions}.
1173
1174 @item Open a @strong{terminal} session.
1175 (@code{Applications > Accessories > Terminal})
1176
1177 @item Open @strong{Firefox} (there's an icon for it on the
1178 panel at the top of the screen) and go to the online Lilypond
1179 @uref{http://lilypond.org/doc/latest/Documentation/contributor/,
1180 Contributor's Guide}.
1181
1182 @item To retrieve the Lilypond source code from @code{git},
1183 copy-and-paste each command from the CG @qq{Main source code}
1184 section into the terminal. (paste into the terminal with keystroke
1185 @code{CTRL+SHIFT+V})
1186
1187 @item Prepare to build Lilypond by running the configuration script.
1188 Type
1189
1190 @example
1191 ./autogen.sh
1192 @end example
1193
1194 When it is finished you should be presented
1195 with the three most common @code{make} options:
1196
1197 @example
1198 Type:
1199     make all       to build LilyPond
1200     make install   to install LilyPond
1201     make help      to see all possible targets
1202
1203 Edit local.make for local Makefile overrides.
1204 @end example
1205
1206 @item First type @code{make all} to build Lilypond. This will take
1207 a while.
1208
1209 @item When Lilypond is finished building, build the documentation
1210 by typing
1211
1212 @example
1213 make doc
1214 @end example
1215
1216 Depending on your system specs it could take from 30-60 minutes
1217 to finish.
1218
1219 @end enumerate
1220
1221 At this point everything has been compiled.
1222 You may install Lilypond using @code{make install}, or you may wish
1223 to set up your system with concurrent stable and development
1224 versions as described in the previous section.
1225
1226
1227 @node Build system
1228 @section Build system
1229
1230
1231 We currently use make and stepmake, which is complicated and only
1232 used by us.  Hopefully this will change in the future.
1233
1234
1235 @subsubheading Version-specific texinfo macors
1236
1237 @itemize
1238
1239 @item
1240 made with @command{scripts/build/create-version-itexi.py} and@*
1241 @command{scripts/build/create-weblinks-itexi.py}
1242
1243 @item
1244 used extensively in the @code{WEBSITE_ONLY_BUILD} version of the
1245 website (made with website.make, used on lilypond.org)
1246
1247 @item
1248 not (?) used in the main docs?
1249
1250 @item
1251 the numbers in VERSION file: MINOR_VERSION should be 1 more than
1252 the last release, VERSION_DEVEL should be the last @strong{online}
1253 release.  Yes, VERSION_DEVEL is less than VERSION.
1254
1255 @end itemize