]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/included/compile.itexi
933f5c9829e3789f9df86369d1de9844d66df2a2
[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 @menu
11 * Overview of compiling::
12 * Requirements::
13 * Getting the source code::
14 * Configuring make::
15 * Compiling LilyPond::
16 * Post-compilation options::
17 * Problems::
18 * Concurrent stable and development versions::
19 * Build system::
20 @end menu
21
22
23 @node Overview of compiling
24 @section Overview of compiling
25
26 Compiling LilyPond from source is an involved process, and is only
27 recommended for developers and packagers.  Typical program users
28 are instead encouraged to obtain the program from a package
29 manager (on Unix) or by downloading a precompiled binary
30 configured for a specific operating system.  Pre-compiled binaries
31 are available on the @rweb{Download} page.
32
33 Compiling LilyPond from source is necessary if you want to build,
34 install, or test your own version of the program.
35
36 A successful compile can also be used to generate and install the
37 documentation, incorporating any changes you may have made.
38 However, a successful compile is not a requirement for generating
39 the documentation.  The documentation can be built using a Git
40 repository in conjunction with a locally installed copy of the
41 program.  For more information, see @ref{Building documentation
42 without compiling}.
43
44 Attempts to compile LilyPond natively on Windows have been
45 unsuccessful, though a workaround is available (see
46 @rcontrib{Lilydev}).
47
48
49 @node Requirements
50 @section Requirements
51
52
53 @menu
54 * Requirements for running LilyPond::
55 * Requirements for compiling LilyPond::
56 * Requirements for building documentation::
57 @end menu
58
59
60 @node Requirements for running LilyPond
61 @subsection Requirements for running LilyPond
62
63 Running LilyPond requires proper installation of the following
64 software:
65
66 @itemize
67 @item @uref{http://www.dejavu-fonts.org/, DejaVu fonts} (normally
68 installed by default)
69
70 @item @uref{http://www.fontconfig.org/, FontConfig} (2.4.0 or newer)
71
72 @item @uref{http://www.freetype.org/, Freetype} (2.1.10 or newer)
73
74 @item @uref{http://www.ghostscript.com, Ghostscript} (8.60 or
75 newer)
76
77 @item @uref{http://www.gnu.org/software/guile/guile.html, Guile}
78 (1.8.2 or newer)
79
80 @item @uref{http://www.pango.org/, Pango} (1.12 or newer)
81
82 @item @uref{http://www.python.org, Python} (2.4 or newer)
83 @end itemize
84
85 International fonts are required to create music with
86 international text or lyrics.
87
88
89 @node Requirements for compiling LilyPond
90 @subsection Requirements for compiling LilyPond
91
92 Below is a full list of packages needed to build LilyPond.
93 However, for most common distributions there is an easy way of
94 installing most all build dependencies in one go:
95
96 @multitable @columnfractions .5 .5
97 @headitem Distribution @tab Command
98 @item Debian, Ubuntu
99 @tab @code{sudo apt-get build-dep lilypond}
100
101 @item Fedora, RHEL
102 @tab @code{sudo yum-builddep lilypond}
103
104 @item openSUSE, SLED
105 @c sorry for the idiosyncratic command, I really asked and argued
106 @c for "zypper build-dep" :-(
107 @tab @code{sudo zypper --build-deps-only source-install lilypond}
108 @end multitable
109
110 @itemize
111 @item Everything listed in @ref{Requirements for running
112 LilyPond}
113
114 @item Development packages for the above items (which should
115 include header files and libraries).
116
117 Red Hat Fedora:
118
119 @c ghostscript-devel-[version] isn't needed
120 @example
121 guile-devel-@var{version}
122 fontconfig-devel-@var{version}
123 freetype-devel-@var{version}
124 pango-devel-@var{version}
125 python-devel-@var{version}
126 @end example
127
128 Debian GNU/Linux:
129
130 @c libgs-dev isn't needed
131 @example
132 guile-@var{version}-dev
133 libfontconfig1-dev
134 libfreetype6-dev
135 libpango1.0-dev
136 python@var{version}-dev
137 @end example
138
139 @item @uref{http://flex.sourceforge.net/, Flex}
140
141 @item @uref{http://fontforge.sf.net/, FontForge} (20060125 or
142 newer; 20100501 or newer is recommended; must be compiled
143 with @option{--enable-double}.  Failure to do so can lead to
144 poor intersection calculations and poorly-rendered glyphs.)
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://gzip.org/, gzip}
192
193 @item @uref{http://rsync.samba.org/, rsync}
194
195 @item @uref{http://www.nongnu.org/texi2html/, Texi2HTML} (1.82)
196
197 @item International fonts
198
199 Red Hat Fedora:
200
201 @example
202 fonts-arabic
203 fonts-hebrew
204 fonts-ja
205 fonts-xorg-truetype
206 taipeifonts
207 ttfonts-ja
208 ttfonts-zh_CN
209 @end example
210
211 Debian GNU/Linux:
212
213 @example
214 emacs-intl-fonts
215 ttf-kochi-gothic
216 ttf-kochi-mincho
217 xfonts-bolkhov-75dpi
218 xfonts-cronyx-75dpi
219 xfonts-cronyx-100dpi
220 xfonts-intl-.*
221 @end example
222 @end itemize
223
224
225 @node Getting the source code
226 @section Getting the source code
227
228
229 @subheading Downloading the Git repository
230
231 In general, developers compile LilyPond from within a local Git
232 repository.  Setting up a local Git repository is explained in
233 @rcontrib{Starting with Git}.
234
235
236 @subheading Downloading a source tarball
237
238 Packagers are encouraged to use source tarballs for compiling.
239
240 The tarball for the latest stable release is available on the
241 @rweb{Source} page.
242
243 @noindent
244 The latest
245 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot, source code snapshot}
246 is also available as a tarball from the GNU Savannah Git server.
247
248 @noindent
249 All tagged releases (including legacy stable
250 versions and the most recent development release) are available
251 here:
252
253 @example
254 @uref{http://download.linuxaudio.org/lilypond/source/}
255 @end example
256
257 Download the tarball to your @file{~/src/} directory, or some
258 other appropriate place.
259
260 @warning{Be careful where you unpack the tarball!  Any
261 subdirectories of the current folder named @file{lilypond/} or
262 @file{lilypond-@var{x.y.z}/} (where @var{x.y.z} is the release
263 number) will be overwritten if there is a name clash with the
264 tarball.}
265
266 Unpack the tarball with this command:
267
268 @example
269 tar -xzf lilypond-@var{x.y.z}.tar.gz
270 @end example
271
272 This creates a subdirectory within the current directory called
273 @file{lilypond-@var{x.y.z}/}.  Once unpacked, the source files
274 occupy about 40 MB of disk space.
275
276 Windows users wanting to look at the source code may have to
277 download and install the free-software
278 @uref{http://www.7-zip.org, 7zip archiver} to extract the tarball.
279
280
281 @node Configuring make
282 @section Configuring @command{make}
283
284
285 @menu
286 * Running ./autogen.sh::
287 * Running ../configure::
288 @end menu
289
290
291 @node Running ./autogen.sh
292 @subsection Running @command{./autogen.sh}
293
294 After you unpack the tarball (or download the Git repository), the
295 contents of your top source directory should be similar to the
296 current source tree listed at
297 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree}.
298
299 Next, you need to create the generated files; enter the following
300 command from your top source directory:
301
302 @example
303 ./autogen.sh --noconfigure
304 @end example
305
306 This will generate a number of files and directories to aid
307 configuration, such as @file{configure}, @file{README.txt}, etc.
308
309 Next, create the build directory with:
310
311 @example
312 mkdir build/
313 cd build/
314 @end example
315
316 We heavily recommend building lilypond inside a separate directory
317 with this method.
318
319
320 @node Running ../configure
321 @subsection Running @command{../configure}
322
323
324 @menu
325 * Configuration options::
326 * Checking build dependencies::
327 * Configuring target directories::
328 @end menu
329
330
331 @node Configuration options
332 @unnumberedsubsubsec Configuration options
333
334 @warning{make sure that you are in the @file{build/} subdirectory
335 of your source tree.}
336
337 The @command{../configure} command (generated by
338 @command{./autogen.sh}) provides many options for configuring
339 @command{make}.  To see them all, run:
340
341 @example
342 ../configure --help
343 @end example
344
345
346 @node Checking build dependencies
347 @unnumberedsubsubsec Checking build dependencies
348
349 @warning{make sure that you are in the @file{build/} subdirectory
350 of your source tree.}
351
352 When @command{../configure} is run without any arguments, it will
353 check to make sure your system has everything required for
354 compilation:
355
356 @example
357 ../configure
358 @end example
359
360 If any build dependency is missing, @command{../configure} will
361 return with:
362
363 @example
364 ERROR: Please install required programs:  @var{foo}
365 @end example
366
367 The following message is issued if you are missing programs that
368 are only needed for building the documentation:
369
370 @example
371 WARNING: Please consider installing optional programs:  @var{bar}
372 @end example
373
374 If you intend to build the documentation locally, you will need to
375 install or update these programs accordingly.
376
377 @warning{@command{../configure} may fail to issue warnings for
378 certain documentation build requirements that are not met.  If you
379 experience problems when building the documentation, you may need
380 to do a manual check of @ref{Requirements for building
381 documentation}.}
382
383
384 @node Configuring target directories
385 @unnumberedsubsubsec Configuring target directories
386
387 @warning{make sure that you are in the @file{build/} subdirectory
388 of your source tree.}
389
390 If you intend to use your local build to install a local copy of
391 the program, you will probably want to configure the installation
392 directory.  Here are the relevant lines taken from the output of
393 @command{../configure@tie{}--help}:
394
395 @quotation
396 By default, `@command{make@tie{}install}' will install all the
397 files in @file{/usr/local/bin}, @file{/usr/local/lib} etc.  You
398 can specify an installation prefix other than @file{/usr/local}
399 using `@option{--prefix}', for instance `@option{--prefix=$HOME}'.
400 @end quotation
401
402 A typical installation prefix is @file{$HOME/usr}:
403
404 @example
405 ../configure --prefix=$HOME/usr
406 @end example
407
408 Note that if you plan to install a local build on a system where
409 you do not have root privileges, you will need to do something
410 like this anyway---@command{make@tie{}install} will only succeed
411 if the installation prefix points to a directory where you have
412 write permission (such as your home directory).  The installation
413 directory will be automatically created if necessary.
414
415 The location of the @command{lilypond} command installed by this
416 process will be @file{@var{prefix}/bin/lilypond}; you may want to
417 add @file{@var{prefix}/bin/} to your @code{$PATH} if it is not
418 already included.
419
420 It is also possible to specify separate installation directories
421 for different types of program files.  See the full output of
422 @command{../configure@tie{}--help} for more information.
423
424 If you encounter any problems, please see @ref{Problems}.
425
426
427 @node Compiling LilyPond
428 @section Compiling LilyPond
429
430
431 @menu
432 * Using make::
433 * Saving time with the -j option::
434 * Compiling for multiple platforms::
435 * Useful make variables::
436 @end menu
437
438
439 @node Using make
440 @subsection Using @command{make}
441
442 @warning{make sure that you are in the @file{build/} subdirectory
443 of your source tree.}
444
445 LilyPond is compiled with the @command{make} command.  Assuming
446 @command{make} is configured properly, you can simply run:
447
448 @example
449 make
450 @end example
451
452 @samp{make} is short for @samp{make all}.  To view a list of @command{make}
453 targets, run:
454
455 @example
456 make help
457 @end example
458
459 TODO: Describe what @command{make} actually does.
460
461
462 @node Saving time with the -j option
463 @subsection Saving time with the @option{-j} option
464
465 If your system has multiple CPUs, you can speed up compilation by
466 adding @samp{-j@var{X}} to the @command{make} command, where
467 @samp{@var{X}} is one more than the number of cores you have.  For
468 example, a typical Core2Duo machine would use:
469
470 @example
471 make -j3
472 @end example
473
474 If you get errors using the @option{-j} option, and @samp{make}
475 succeeds without it, try lowering the @code{@var{X}} value.
476
477 Because multiple jobs run in parallel when @option{-j} is used, it can
478 be difficult to determine the source of an error when one occurs.  In
479 that case, running @samp{make} without the @option{-j} is advised.
480
481 @node Compiling for multiple platforms
482 @subsection Compiling for multiple platforms
483
484 If you want to build multiple versions of LilyPond with different
485 configuration settings, you can use the
486 @option{--enable-config=@var{conf}} option of @command{configure}.
487 You should use @code{make@tie{}conf=@var{conf}} to generate the
488 output in @file{out-@var{conf}}.  For example, suppose you want to
489 build with and without profiling, then use the following for the
490 normal build
491
492 @example
493 ./configure --prefix=$HOME/usr/ --enable-checking
494 make
495 @end example
496
497 and for the profiling version, specify a different configuration
498
499 @example
500 ./configure --prefix=$HOME/usr/ --enable-profiling \
501   --enable-config=prof --disable-checking
502 make conf=prof
503 @end example
504
505 If you wish to install a copy of the build with profiling, don't
506 forget to use @code{conf=@var{CONF}} when issuing
507 @command{make@tie{}install}:
508
509 @example
510 make conf=prof install
511 @end example
512
513
514 @seealso
515 @ref{Installing LilyPond from a local build}
516
517
518 @node Useful make variables
519 @subsection Useful @command{make} variables
520
521 If a less verbose build output if desired, the variable
522 @code{QUIET_BUILD} may be set to @code{1} on @command{make}
523 command line, or in @file{local.make} at top of the build tree.
524
525
526 @node Post-compilation options
527 @section Post-compilation options
528
529
530 @menu
531 * Installing LilyPond from a local build::
532 * Generating documentation::
533 * Testing LilyPond binary::
534 @end menu
535
536
537 @node Installing LilyPond from a local build
538 @subsection Installing LilyPond from a local build
539
540 If you configured @command{make} to install your local build in a
541 directory where you normally have write permission (such as your
542 home directory), and you have compiled LilyPond by running
543 @command{make}, you can install the program in your target
544 directory by running:
545
546 @example
547 make install
548 @end example
549
550 If instead, your installation directory is not one that you can
551 normally write to (such as the default @file{/usr/local/}, which
552 typically is only writeable by the superuser), you will need to
553 temporarily become the superuser when running
554 @command{make@tie{}install}:
555
556 @example
557 sudo make install
558 @end example
559
560 @noindent
561 or...
562
563 @example
564 su -c 'make install'
565 @end example
566
567 If you don't have superuser privileges, then you need to configure
568 the installation directory to one that you can write to, and then
569 re-install.  See @ref{Configuring target directories}.
570
571
572 @node Generating documentation
573 @subsection Generating documentation
574
575
576 @menu
577 * Documentation editor's edit/compile cycle::
578 * Building documentation::
579 * Building a single document::
580 * Saving time with CPU_COUNT::
581 * AJAX search::
582 * Installing documentation::
583 * Building documentation without compiling::
584 @end menu
585
586
587 @node Documentation editor's edit/compile cycle
588 @unnumberedsubsubsec Documentation editor's edit/compile cycle
589
590 @itemize
591 @item
592 Initial documentation build:
593
594 @example
595 make [-j@var{X}]
596 make [-j@var{X} CPU_COUNT=@var{X}] doc  @emph{## can take an hour or more}
597 @end example
598
599 @item
600 Edit/compile cycle:
601
602 @example
603 @emph{## edit source files, then...}
604
605 make [-j@var{X}]                  @emph{## needed if editing outside}
606                             @emph{##   Documentation/, but useful anyway}
607                             @emph{##   for finding Texinfo errors.}
608 make [-j@var{X} CPU_COUNT=@var{X}] doc  @emph{## usually faster than initial build.}
609 @end example
610
611 @item
612 Reset:
613
614 In some cases, it is possible to clean the compiled documentation
615 with @samp{make@tie{}doc-clean}, but this method is not guaranteed
616 to fix everything.  Instead, we recommend that you delete your
617 @file{build/} directory, and begin compiling from scratch.  Since
618 the documentation compile takes much longer than the
619 non-documentation compile, this does not increase the overall time
620 by a great deal.
621
622 @end itemize
623
624 @node Building documentation
625 @unnumberedsubsubsec Building documentation
626
627 After a successful compile (using @command{make}), the
628 documentation can be built by issuing:
629
630 @example
631 make doc
632 @end example
633
634 The first time you run @command{make@tie{}doc}, the process can
635 easily take an hour or more.  After that, @command{make@tie{}doc}
636 only makes changes to the pre-built documentation where needed,
637 so it may only take a minute or two to test changes if the
638 documentation is already built.
639
640 If @command{make@tie{}doc} succeeds, the HTML documentation tree
641 is available in @file{out-www/offline-root/}, and can be browsed
642 locally.  Various portions of the documentation can be found by
643 looking in @file{out/} and @file{out-www} subdirectories in other
644 places in the source tree, but these are only @emph{portions} of
645 the docs.  Please do not complain about anything which is broken
646 in those places; the only complete set of documentation is in
647 @file{out-www/offline-root/} from the top of the source tree.
648
649 @code{make doc} compiles the documents for all languages.  To save
650 some compile time, the English language documents can be compiled
651 on their own with:
652
653 @example
654 make LANGS='' doc
655 @end example
656
657 @noindent Similarly, it is possible to compile a subset of the
658 translated documentation by specifying their language codes on the
659 command line.  For example, the French and German translations are
660 compiled with:
661
662 @example
663 make LANGS='de fr' doc
664 @end example
665
666 @noindent Note that this will also compile the English version.
667
668 Compilation of documentation in Info format with images can be
669 done separately by issuing:
670
671 @example
672 make info
673 @end example
674
675 @noindent
676 An issue when switching branches between master and lilypond/translation
677 is the appearance/disappearance of translated versions of some manuals.
678 If you see such a warning from make:
679
680 @example
681 No rule to make target `X', needed by `Y'
682 @end example
683
684 @noindent
685 Your best bet is to delete the file Y.dep and to try again.
686
687 @node Building a single document
688 @unnumberedsubsubsec Building a single document
689 It's possible to build a single document.  For example, to rebuild
690 only @file{contributor.pdf}, do the following:
691
692 @example
693 cd build/
694 cd Documentation/
695 touch ../../Documentation/contributor.texi
696 make out=www out-www/contributor.pdf
697 @end example
698
699 If you are only working on a single document, test-building it in
700 this way can give substantial time savings - recreating
701 @file{contributor.pdf}, for example, takes a matter of seconds.
702
703 @node Saving time with CPU_COUNT
704 @unnumberedsubsubsec Saving time with @code{CPU_COUNT}
705
706 The most time consuming task for building the documentation is
707 running LilyPond to build images of music, and there cannot be
708 several simultaneously running @command{lilypond-book} instances,
709 so the @option{-j} @command{make} option does not significantly
710 speed up the build process.  To help speed it up, the makefile
711 variable @option{CPU_COUNT} may be set in @file{local.make} or on
712 the command line to the number of @code{.ly} files that LilyPond
713 should process simultaneously, e.g. on a bi-processor or dual core
714 machine:
715
716 @example
717 make -j3 CPU_COUNT=3 doc
718 @end example
719
720 @noindent
721 The recommended value of @option{CPU_COUNT} is one plus the number
722 of cores or processors, but it is advisable to set it to a smaller
723 value unless your system has enough RAM to run that many
724 simultaneous LilyPond instances.  Also, values for the @option{-j}
725 option that pose problems with @samp{make} are less likely to pose
726 problems with @samp{make doc} (this applies to both @option{-j}
727 and @option{CPU_COUNT}).  For example, with a quad-core processor,
728 it is possible for @samp{make -j5 CPU_COUNT=5 doc} to work
729 consistently even if @samp{make -j5} rarely succeeds.
730
731
732 @node AJAX search
733 @unnumberedsubsubsec AJAX search
734
735 To build the documentation with interactive searching, use:
736
737 @example
738 make doc AJAX_SEARCH=1
739 @end example
740
741 This requires PHP, and you must view the docs via a http
742 connection (you cannot view them on your local filesystem).
743
744 @warning{Due to potential security or load issues, this option is
745 not enabled in the official documentation builds.  Enable at your
746 own risk.}
747
748
749 @node Installing documentation
750 @unnumberedsubsubsec Installing documentation
751
752 The HTML, PDF and if available Info files can be installed into
753 the standard documentation path by issuing
754
755 @example
756 make install-doc
757 @end example
758
759 @noindent
760 This also installs Info documentation with images if the
761 installation prefix is properly set; otherwise, instructions to
762 complete proper installation of Info documentation are printed on
763 standard output.
764
765 To install the Info documentation separately, run:
766
767 @example
768 make install-info
769 @end example
770
771 @noindent
772 Note that to get the images in Info documentation, @code{install-doc}
773 target creates symbolic links to HTML and PDF installed documentation
774 tree in @file{@var{prefix}/share/info}, in order to save disk space,
775 whereas @code{install-info} copies images in
776 @file{@var{prefix}/share/info} subdirectories.
777
778 It is possible to build a documentation tree in
779 @file{out-www/online-root/}, with special processing, so it can be
780 used on a website with content negotiation for automatic language
781 selection; this can be achieved by issuing
782
783 @example
784 make WEB_TARGETS=online doc
785 @end example
786
787 @noindent
788 and both @q{offline} and @q{online} targets can be generated by issuing
789
790 @example
791 make WEB_TARGETS="offline online" doc
792 @end example
793
794 Several targets are available to clean the documentation build and
795 help with maintaining documentation; an overview of these targets is
796 available with
797
798 @example
799 make help
800 @end example
801
802 @noindent
803 from every directory in the build tree.  Most targets for
804 documentation maintenance are available from
805 @file{Documentation/}; for more information, see
806 @rcontrib{Documentation work}.
807
808 The makefile variable @code{QUIET_BUILD} may be set to @code{1}
809 for a less verbose build output, just like for building the
810 programs.
811
812
813 @node Building documentation without compiling
814 @unnumberedsubsubsec Building documentation without compiling
815
816
817 The documentation can be built locally without compiling LilyPond
818 binary, if LilyPond is already installed on your system.
819
820 From a fresh Git checkout, do
821
822 @example
823 ./autogen.sh   # ignore any warning messages
824 cp GNUmakefile.in GNUmakefile
825 make -C scripts && make -C python
826 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
827 @end example
828
829 Please note that this may break sometimes -- for example, if a new
830 feature is added with a test file in input/regression, even the latest
831 development release of LilyPond will fail to build the docs.
832
833 You may build the manual without building all the @file{input/*} stuff
834 (i.e. mostly regression tests): change directory, for example to
835 @file{Documentation/}, issue @code{make doc}, which will build
836 documentation in a subdirectory @file{out-www} from the source files in
837 current directory.  In this case, if you also want to browse the
838 documentation in its post-processed form, change back to top directory
839 and issue
840
841 @example
842 make out=www WWW-post
843 @end example
844
845 @knownissues
846
847 You may also need to create a script for @command{pngtopnm} and
848 @code{pnmtopng}.  On GNU/Linux, I use this:
849
850 @verbatim
851 export LD_LIBRARY_PATH=/usr/lib
852 exec /usr/bin/pngtopnm "$@"
853 @end verbatim
854
855 On MacOS X with fink, I use this:
856
857 @verbatim
858 export DYLD_LIBRARY_PATH=/sw/lib
859 exec /sw/bin/pngtopnm "$@"
860 @end verbatim
861
862 On MacOS X with macports, you should use this:
863
864 @verbatim
865 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
866 exec /opt/local/bin/pngtopnm "$@"
867 @end verbatim
868
869
870 @node Testing LilyPond binary
871 @subsection Testing LilyPond binary
872
873
874 LilyPond comes with an extensive suite that exercises the entire
875 program.  This suite can be used to test that the binary has
876 been built correctly.
877
878 The test suite can be executed with:
879
880 @verbatim
881 make test
882 @end verbatim
883
884 If the test suite completes successfully, the LilyPond binary
885 has been verified.
886
887 More information on the regression test suite is found at
888 @rcontrib{Regression tests}.
889
890 @node Problems
891 @section Problems
892
893 For help and questions use @email{lilypond-user@@gnu.org}.  Send
894 bug reports to @email{bug-lilypond@@gnu.org}.
895
896 Bugs that are not fault of LilyPond are documented here.
897
898 @unnumberedsubsubsec Bison 1.875
899
900 There is a bug in bison-1.875: compilation fails with "parse error
901 before `goto'" in line 4922 due to a bug in bison.  To fix, please
902 recompile bison 1.875 with the following fix
903
904 @example
905 $ cd lily; make out/parser.cc
906 $ vi +4919 out/parser.cc
907 # append a semicolon to the line containing "__attribute__ ((__unused__))
908 # save
909 $ make
910 @end example
911
912
913 @unnumberedsubsubsec Compiling on MacOS@tie{}X
914
915 Here are special instructions for compiling under MacOS@tie{}X.
916 These instructions assume that dependencies are installed using
917 @uref{http://www.macports.org/, MacPorts.} The instructions have
918 been tested using OS X 10.5 (Leopard).
919
920 First, install the relevant dependencies using MacPorts.
921
922 Next, add the following to your relevant shell initialization
923 files.  This is @code{~/.profile} by default.  You should create
924 this file if it does not exist.
925
926 @example
927 export PATH=/opt/local/bin:/opt/local/sbin:$PATH
928 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
929 @end example
930
931 Now you must edit the generated @file{config.make} file.  Change
932
933 @example
934 FLEXLEXER_FILE = /usr/include/FlexLexer.h
935 @end example
936
937 @noindent
938 to:
939
940 @example
941 FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
942 @end example
943
944 At this point, you should verify that you have the appropriate
945 fonts installed with your ghostscript installation.  Check @code{ls
946 /opt/local/share/ghostscript/fonts} for: 'c0590*' files (.pfb,
947 .pfb and .afm).  If you don't have them, run the following
948 commands to grab them from the ghostscript SVN server and install
949 them in the appropriate location:
950
951 @example
952 svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
953 sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
954 rm -rf urw-fonts-1.07pre44
955 @end example
956
957 Now run the @code{./configure} script.  To avoid complications with
958 automatic font detection, add
959
960 @example
961 --with-ncsb-dir=/opt/local/share/ghostscript/fonts
962 @end example
963
964
965 @unnumberedsubsubsec Solaris
966
967 Solaris7, ./configure
968
969 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
970 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
971 is.  Run configure like
972
973 @example
974 CONFIG_SHELL=/bin/ksh ksh -c ./configure
975 @end example
976
977 @noindent
978 or
979
980 @example
981 CONFIG_SHELL=/bin/bash bash -c ./configure
982 @end example
983
984 @unnumberedsubsubsec FreeBSD
985
986 To use system fonts, dejaview must be installed.  With the default
987 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
988
989 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
990 following line just after the @code{<fontconfig>} line.  (Adjust as necessary
991 for your hierarchy.)
992
993 @example
994 <dir>/usr/X11R6/lib/X11/fonts</dir>
995 @end example
996
997
998 @unnumberedsubsubsec International fonts
999
1000 On Mac OS X, all fonts are installed by default.  However, finding all
1001 system fonts requires a bit of configuration; see
1002 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
1003 this post} on the @code{lilypond-user} mailing list.
1004
1005 On Linux, international fonts are installed by different means on
1006 every distribution.  We cannot list the exact commands or packages
1007 that are necessary, as each distribution is different, and the exact
1008 package names within each distribution changes.  Here are some
1009 hints, though:
1010
1011 @verbatim
1012 Red Hat Fedora
1013
1014     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
1015          ttfonts-zh_CN fonts-ja fonts-hebrew
1016
1017 Debian GNU/Linux
1018
1019    apt-get install emacs-intl-fonts xfonts-intl-.* \
1020         ttf-kochi-gothic ttf-kochi-mincho \
1021         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
1022 @end verbatim
1023
1024
1025 @unnumberedsubsubsec Using lilypond python libraries
1026
1027 If you want to use lilypond's python libraries (either running
1028 certain build scripts manually, or using them in other programs),
1029 set @code{PYTHONPATH} to @file{python/out} in your build
1030 directory, or @file{.../usr/lib/lilypond/current/python} in the
1031 installation directory structure.
1032
1033
1034
1035
1036 @node Concurrent stable and development versions
1037 @section Concurrent stable and development versions
1038
1039
1040 It can be useful to have both the stable and the development versions
1041 of Lilypond available at once.  One way to do this on GNU/Linux is to
1042 install the stable version using the precompiled binary, and run the
1043 development version from the source tree.  After running @command{make
1044 all} from the top directory of the Lilypond source files, there will
1045 be a binary called @code{lilypond} in the @code{out} directory:
1046
1047 @example
1048 <@var{path to}>/lilypond/out/bin/lilypond
1049 @end example
1050
1051 This binary can be run without actually doing the @code{make
1052 install} command.  The advantage to this is that you can have all
1053 of the latest changes available after pulling from git and running
1054 @code{make all}, without having to uninstall the old version and
1055 reinstall the new.
1056
1057 So, to use the stable version, install it as usual and use the
1058 normal commands:
1059
1060 @example
1061 lilypond foobar.ly
1062 @end example
1063
1064 To use the development version, create a link to the binary in the
1065 source tree by saving the following line in a file somewhere in your
1066 @code{$PATH}:
1067
1068 @example
1069 exec <@var{path to}>/lilypond/out/bin/lilypond "$@@"
1070 @end example
1071
1072 Save it as @code{Lilypond} (with a capital L to distinguish it
1073 from the stable @code{lilypond}), and make it executable:
1074
1075 @example
1076 chmod +x Lilypond
1077 @end example
1078
1079 Then you can invoke the development version this way:
1080
1081 @example
1082 Lilypond foobar.ly
1083 @end example
1084
1085
1086 TODO: ADD
1087
1088 - other compilation tricks for developers
1089
1090
1091 @node Build system
1092 @section Build system
1093
1094
1095 We currently use make and stepmake, which is complicated and only
1096 used by us.  Hopefully this will change in the future.
1097
1098
1099 @subsubheading Version-specific texinfo macros
1100
1101 @itemize
1102
1103 @item
1104 made with @command{scripts/build/create-version-itexi.py} and@*
1105 @command{scripts/build/create-weblinks-itexi.py}
1106
1107 @item
1108 used extensively in the @code{WEBSITE_ONLY_BUILD} version of the
1109 website (made with @file{website.make}, used on lilypond.org)
1110
1111 @item
1112 not (?) used in the main docs?
1113
1114 @item
1115 the numbers in VERSION file: MINOR_VERSION should be 1 more than
1116 the last release, VERSION_DEVEL should be the last @strong{online}
1117 release.  Yes, VERSION_DEVEL is less than VERSION.
1118
1119 @end itemize