]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/included/compile.itexi
498bbfd33875d0984011b5ec268743491f43e7c2
[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 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.4.0 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://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
304 @end example
305
306 This will:
307
308 @enumerate
309 @item generate a number of files and directories to aid
310 configuration, such as @file{configure}, @file{README.txt}, etc.
311
312 @item automatically run the @command{./configure} command.
313 @end enumerate
314
315
316 @node Running ./configure
317 @subsection Running @command{./configure}
318
319 @menu
320 * Configuration options::
321 * Checking build dependencies::
322 * Configuring target directories::
323 * Making an out-of-tree build::
324 @end menu
325
326
327 @node Configuration options
328 @unnumberedsubsubsec Configuration options
329
330 The @command{./configure} command (generated by
331 @command{./autogen.sh}) provides many options for configuring
332 @command{make}.  To see them all, run:
333
334 @example
335 ./configure --help
336 @end example
337
338
339 @node Checking build dependencies
340 @unnumberedsubsubsec Checking build dependencies
341
342 When @command{./configure} is run without any arguments, it will
343 check to make sure your system has everything required for
344 compilation.  This is done automatically when
345 @command{./autogen.sh} is run.  If any build dependency is
346 missing, @command{./configure} will return with:
347
348 @example
349 ERROR: Please install required programs:  @var{foo}
350 @end example
351
352 The following message is issued if you are missing programs that
353 are only needed for building the documentation:
354
355 @example
356 WARNING: Please consider installing optional programs:  @var{bar}
357 @end example
358
359 If you intend to build the documentation locally, you will need to
360 install or update these programs accordingly.
361
362 @warning{@command{./configure} may fail to issue warnings for
363 certain documentation build requirements that are not met.  If you
364 experience problems when building the documentation, you may need
365 to do a manual check of @ref{Requirements for building
366 documentation}.}
367
368
369 @node Configuring target directories
370 @unnumberedsubsubsec Configuring target directories
371
372 If you intend to use your local build to install a local copy of
373 the program, you will probably want to configure the installation
374 directory.  Here are the relevant lines taken from the output of
375 @command{./configure@tie{}--help}:
376
377 @quotation
378 By default, `@command{make@tie{}install}' will install all the
379 files in @file{/usr/local/bin}, @file{/usr/local/lib} etc.  You
380 can specify an installation prefix other than @file{/usr/local}
381 using `@code{--prefix}', for instance `@code{--prefix=$HOME}'.
382 @end quotation
383
384 A typical installation prefix is @file{$HOME/usr}:
385
386 @example
387 ./configure --prefix=$HOME/usr
388 @end example
389
390 Note that if you plan to install a local build on a system where
391 you do not have root privileges, you will need to do something
392 like this anyway---@command{make@tie{}install} will only succeed
393 if the installation prefix points to a directory where you have
394 write permission (such as your home directory).  The installation
395 directory will be automatically created if necessary.
396
397 The location of the @command{lilypond} command installed by this
398 process will be @file{@var{prefix}/bin/lilypond}; you may want to
399 add @file{@var{prefix}/bin/} to your @code{$PATH} if it is not
400 already included.
401
402 It is also possible to specify separate installation directories
403 for different types of program files.  See the full output of
404 @command{./configure@tie{}--help} for more information.
405
406 If you encounter any problems, please see @ref{Problems}.
407
408
409 @node Making an out-of-tree build
410 @unnumberedsubsubsec Making an out-of-tree build
411
412 It is possible to compile LilyPond in a build tree different from
413 the source tree, using the @option{--srcdir} option of
414 @command{configure}.  Note that in some cases you may need to
415 remove the output of a previous @command{configure} command by
416 running @command{make@tie{}distclean} in the main source directory
417 before configuring the out-of-tree build:
418
419 @example
420 make distclean
421 mkdir lily-build && cd lily-build
422 @var{sourcedir}/configure --srcdir=@var{sourcedir}
423 @end example
424
425
426 @node Compiling LilyPond
427 @section Compiling LilyPond
428
429
430 @menu
431 * Using make::
432 * Saving time with the -j option::
433 * Compiling for multiple platforms::
434 * Useful make variables::
435 @end menu
436
437
438 @node Using make
439 @subsection Using @command{make}
440
441 LilyPond is compiled with the @command{make} command.  Assuming
442 @command{make} is configured properly, you can simply run:
443
444 @example
445 make
446 @end example
447
448 @samp{make} is short for @samp{make all}.  To view a list of @command{make}
449 targets, run:
450
451 @example
452 make help
453 @end example
454
455 TODO: Describe what @command{make} actually does.
456
457
458 @node Saving time with the -j option
459 @subsection Saving time with the @option{-j} option
460
461 If your system has multiple CPUs, you can speed up compilation by
462 adding @samp{-j@var{X}} to the @command{make} command, where
463 @samp{@var{X}} is one more than the number of cores you have.  For
464 example, a typical Core2Duo machine would use:
465
466 @example
467 make -j3
468 @end example
469
470 If you get errors using the @option{-j} option, and @samp{make}
471 succeeds without it, try lowering the @code{@var{X}} value.
472
473 Because multiple jobs run in parallel when @option{-j} is used, it can
474 be difficult to determine the source of an error when one occurs.  In
475 that case, running @samp{make} without the @option{-j} is advised.
476
477 @node Compiling for multiple platforms
478 @subsection Compiling for multiple platforms
479
480 If you want to build multiple versions of LilyPond with different
481 configuration settings, you can use the
482 @code{--enable-config=@var{CONF}} option of @command{configure}.
483 You should use @code{make@tie{}conf=@var{CONF}} to generate the
484 output in @file{out-@var{CONF}}.  For example, suppose you want to
485 build with and without profiling, then use the following for the
486 normal build
487
488 @example
489 ./configure --prefix=$HOME/usr/ --enable-checking
490 make
491 @end example
492
493 and for the profiling version, specify a different configuration
494
495 @example
496 ./configure --prefix=$HOME/usr/ --enable-profiling \
497   --enable-config=prof --disable-checking
498 make conf=prof
499 @end example
500
501 If you wish to install a copy of the build with profiling, don't
502 forget to use @code{conf=@var{CONF}} when issuing
503 @command{make@tie{}install}:
504
505 @example
506 make conf=prof install
507 @end example
508
509
510 @seealso
511 @ref{Installing LilyPond from a local build}
512
513
514 @node Useful make variables
515 @subsection Useful @command{make} variables
516
517 If a less verbose build output if desired, the variable
518 @code{QUIET_BUILD} may be set to @code{1} on @command{make}
519 command line, or in @file{local.make} at top of the build tree.
520
521
522 @node Post-compilation options
523 @section Post-compilation options
524
525
526 @menu
527 * Installing LilyPond from a local build::
528 * Generating documentation::
529 * Testing LilyPond binary::
530 @end menu
531
532
533 @node Installing LilyPond from a local build
534 @subsection Installing LilyPond from a local build
535
536 If you configured @command{make} to install your local build in a
537 directory where you normally have write permission (such as your
538 home directory), and you have compiled LilyPond by running
539 @command{make}, you can install the program in your target
540 directory by running:
541
542 @example
543 make install
544 @end example
545
546 If instead, your installation directory is not one that you can
547 normally write to (such as the default @file{/usr/local/}, which
548 typically is only writeable by the superuser), you will need to
549 temporarily become the superuser when running
550 @command{make@tie{}install}:
551
552 @example
553 sudo make install
554 @end example
555
556 @noindent
557 or...
558
559 @example
560 su -c 'make install'
561 @end example
562
563 If you don't have superuser privileges, then you need to configure
564 the installation directory to one that you can write to, and then
565 re-install.  See @ref{Configuring target directories}.
566
567
568 @node Generating documentation
569 @subsection Generating documentation
570
571
572 @menu
573 * Documentation editor's edit/compile cycle::
574 * Building documentation::
575 * Saving time with CPU_COUNT::
576 * AJAX search::
577 * Installing documentation::
578 * Building documentation without compiling::
579 @end menu
580
581
582 @node Documentation editor's edit/compile cycle
583 @unnumberedsubsubsec Documentation editor's edit/compile cycle
584
585 @itemize
586 @item
587 Initial documentation build:
588
589 @example
590 make [-j@var{X}]
591 make [-j@var{X} CPU_COUNT=@var{X}] doc  @emph{## can take an hour or more}
592 @end example
593
594 @item
595 Edit/compile cycle:
596
597 @example
598 @emph{## edit source files, then...}
599
600 make [-j@var{X}]                  @emph{## needed if editing outside}
601                             @emph{##   Documentation/, but useful anyway}
602                             @emph{##   for finding Texinfo errors.}
603 touch Documentation/*te??   @emph{## bug workaround}
604 make [-j@var{X} CPU_COUNT=@var{X}] doc  @emph{## usually faster than initial build.}
605 @end example
606
607 @item
608 Reset:
609
610 @example
611 make doc-clean              @emph{## use only as a last resort.}
612 @end example
613 @end itemize
614
615 @node Building documentation
616 @unnumberedsubsubsec Building documentation
617
618 After a successful compile (using @command{make}), the
619 documentation can be built by issuing:
620
621 @example
622 make doc
623 @end example
624
625 The first time you run @command{make@tie{}doc}, the process can
626 easily take an hour or more.  After that, @command{make@tie{}doc}
627 only makes changes to the pre-built documentation where needed,
628 so it may only take a minute or two to test changes if the
629 documentation is already built.
630
631 If @command{make@tie{}doc} succeeds, the HTML documentation tree
632 is available in @file{out-www/offline-root/}, and can be browsed
633 locally.  Various portions of the documentation can be found by
634 looking in @file{out/} and @file{out-www} subdirectories in other
635 places in the source tree, but these are only @emph{portions} of
636 the docs.  Please do not complain about anything which is broken
637 in those places; the only complete set of documentation is in
638 @file{out-www/offline-root/} from the top of the source tree.
639
640 Compilation of documentation in Info format with images can be
641 done separately by issuing:
642
643 @example
644 make info
645 @end example
646
647 @knownissues
648
649 If source files have changed since the last documentation build,
650 output files that need to be rebuilt are normally rebuilt, even if
651 you do not run @code{make@tie{}doc-clean} first.  However, build
652 dependencies in the documentation are so complex that some
653 newly-edited files may not be rebuilt as they should be; a
654 workaround is to @command{touch} the top source file for any
655 manual you've edited.  For example, if you make changes to a file
656 in @file{notation/}, do:
657
658 @example
659 touch Documentation/notation.tely
660 @end example
661
662 @noindent
663 The top sources possibly affected by this are:
664
665 @example
666 Documentation/extend.texi
667 Documentation/changes.tely
668 Documentation/contributor.texi
669 Documentation/essay.tely
670 Documentation/extending.tely
671 Documentation/learning.tely
672 Documentation/notation.tely
673 Documentation/snippets.tely
674 Documentation/usage.tely
675 Documentation/web.texi
676 @end example
677
678 @noindent
679 You can @command{touch} all of them at once with:
680
681 @example
682 touch Documentation/*te??
683 @end example
684
685 @noindent
686 However, this will rebuild all of the manuals
687 indiscriminately---it is more efficient to @command{touch} only
688 the affected files.
689
690
691 @node Saving time with CPU_COUNT
692 @unnumberedsubsubsec Saving time with @code{CPU_COUNT}
693
694 The most time consuming task for building the documentation is
695 running LilyPond to build images of music, and there cannot be
696 several simultaneously running @command{lilypond-book} instances,
697 so the @option{-j} @command{make} option does not significantly
698 speed up the build process.  To help speed it up, the makefile
699 variable @option{CPU_COUNT} may be set in @file{local.make} or on
700 the command line to the number of @code{.ly} files that LilyPond
701 should process simultaneously, e.g. on a bi-processor or dual core
702 machine:
703
704 @example
705 make -j3 CPU_COUNT=3 doc
706 @end example
707
708 @noindent
709 The recommended value of @option{CPU_COUNT} is one plus the number
710 of cores or processors, but it is advisable to set it to a smaller
711 value unless your system has enough RAM to run that many
712 simultaneous LilyPond instances.  Also, values for the @option{-j}
713 option that pose problems with @samp{make} are less likely to pose
714 problems with @samp{make doc} (this applies to both @option{-j}
715 and @option{CPU_COUNT}).  For example, with a quad-core processor,
716 it is possible for @samp{make -j5 CPU_COUNT=5 doc} to work
717 consistently even if @samp{make -j5} rarely succeeds.
718
719
720 @node AJAX search
721 @unnumberedsubsubsec AJAX search
722
723 To build the documentation with interactive searching, use:
724
725 @example
726 make doc AJAX_SEARCH=1
727 @end example
728
729 This requires PHP, and you must view the docs via a http
730 connection (you cannot view them on your local filesystem).
731
732 @warning{Due to potential security or load issues, this option is
733 not enabled in the official documentation builds.  Enable at your
734 own risk.}
735
736
737 @node Installing documentation
738 @unnumberedsubsubsec Installing documentation
739
740 The HTML, PDF and if available Info files can be installed into
741 the standard documentation path by issuing
742
743 @example
744 make install-doc
745 @end example
746
747 @noindent
748 This also installs Info documentation with images if the
749 installation prefix is properly set; otherwise, instructions to
750 complete proper installation of Info documentation are printed on
751 standard output.
752
753 To install the Info documentation separately, run:
754
755 @example
756 make install-info
757 @end example
758
759 @noindent
760 Note that to get the images in Info documentation, @code{install-doc}
761 target creates symbolic links to HTML and PDF installed documentation
762 tree in @file{@var{prefix}/share/info}, in order to save disk space,
763 whereas @code{install-info} copies images in
764 @file{@var{prefix}/share/info} subdirectories.
765
766 It is possible to build a documentation tree in
767 @file{out-www/online-root/}, with special processing, so it can be
768 used on a website with content negotiation for automatic language
769 selection; this can be achieved by issuing
770
771 @example
772 make WEB_TARGETS=online doc
773 @end example
774
775 @noindent
776 and both @q{offline} and @q{online} targets can be generated by issuing
777
778 @example
779 make WEB_TARGETS="offline online" doc
780 @end example
781
782 Several targets are available to clean the documentation build and
783 help with maintaining documentation; an overview of these targets is
784 available with
785
786 @example
787 make help
788 @end example
789
790 @noindent
791 from every directory in the build tree.  Most targets for
792 documentation maintenance are available from
793 @file{Documentation/}; for more information, see
794 @rcontrib{Documentation work}.
795
796 The makefile variable @code{QUIET_BUILD} may be set to @code{1}
797 for a less verbose build output, just like for building the
798 programs.
799
800
801 @node Building documentation without compiling
802 @unnumberedsubsubsec Building documentation without compiling
803
804
805 The documentation can be built locally without compiling LilyPond
806 binary, if LilyPond is already installed on your system.
807
808 From a fresh Git checkout, do
809
810 @example
811 ./autogen.sh   # ignore any warning messages
812 cp GNUmakefile.in GNUmakefile
813 make -C scripts && make -C python
814 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
815 @end example
816
817 Please note that this may break sometimes -- for example, if a new
818 feature is added with a test file in input/regression, even the latest
819 development release of LilyPond will fail to build the docs.
820
821 You may build the manual without building all the @file{input/*} stuff
822 (i.e. mostly regression tests): change directory, for example to
823 @file{Documentation/}, issue @code{make doc}, which will build
824 documentation in a subdirectory @file{out-www} from the source files in
825 current directory.  In this case, if you also want to browse the
826 documentation in its post-processed form, change back to top directory
827 and issue
828
829 @example
830 make out=www WWW-post
831 @end example
832
833 @knownissues
834
835 You may also need to create a script for @command{pngtopnm} and
836 @code{pnmtopng}.  On GNU/Linux, I use this:
837
838 @verbatim
839 export LD_LIBRARY_PATH=/usr/lib
840 exec /usr/bin/pngtopnm "$@"
841 @end verbatim
842
843 On MacOS X with fink, I use this:
844
845 @verbatim
846 export DYLD_LIBRARY_PATH=/sw/lib
847 exec /sw/bin/pngtopnm "$@"
848 @end verbatim
849
850 On MacOS X with macports, you should use this:
851
852 @verbatim
853 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
854 exec /opt/local/bin/pngtopnm "$@"
855 @end verbatim
856
857
858 @node Testing LilyPond binary
859 @subsection Testing LilyPond binary
860
861
862 LilyPond comes with an extensive suite that exercises the entire
863 program.  This suite can be used to test that the binary has
864 been built correctly.
865
866 The test suite can be executed with:
867
868 @verbatim
869 make test
870 @end verbatim
871
872 If the test suite completes successfully, the LilyPond binary
873 has been verified.
874
875 More information on the regression test suite is found at
876 @rcontrib{Regression tests}.
877
878 @node Problems
879 @section Problems
880
881 For help and questions use @email{lilypond-user@@gnu.org}.  Send
882 bug reports to @email{bug-lilypond@@gnu.org}.
883
884 Bugs that are not fault of LilyPond are documented here.
885
886 @unnumberedsubsubsec Bison 1.875
887
888 There is a bug in bison-1.875: compilation fails with "parse error
889 before `goto'" in line 4922 due to a bug in bison.  To fix, please
890 recompile bison 1.875 with the following fix
891
892 @example
893 $ cd lily; make out/parser.cc
894 $ vi +4919 out/parser.cc
895 # append a semicolon to the line containing "__attribute__ ((__unused__))
896 # save
897 $ make
898 @end example
899
900
901 @unnumberedsubsubsec Compiling on MacOS@tie{}X
902
903 Here are special instructions for compiling under MacOS@tie{}X.
904 These instructions assume that dependencies are installed using
905 @uref{http://www.macports.org/, MacPorts.} The instructions have
906 been tested using OS X 10.5 (Leopard).
907
908 First, install the relevant dependencies using MacPorts.
909
910 Next, add the following to your relevant shell initialization
911 files.  This is @code{~/.profile} by default.  You should create
912 this file if it does not exist.
913
914 @example
915 export PATH=/opt/local/bin:/opt/local/sbin:$PATH
916 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
917 @end example
918
919 Now you must edit the generated @code{config.make} file.  Change
920
921 @example
922 FLEXLEXER_FILE = /usr/include/FlexLexer.h
923 @end example
924
925 @noindent
926 to:
927
928 @example
929 FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
930 @end example
931
932 At this point, you should verify that you have the appropriate
933 fonts installed with your ghostscript installation.  Check @code{ls
934 /opt/local/share/ghostscript/fonts} for: 'c0590*' files (.pfb,
935 .pfb and .afm).  If you don't have them, run the following
936 commands to grab them from the ghostscript SVN server and install
937 them in the appropriate location:
938
939 @example
940 svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
941 sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
942 rm -rf urw-fonts-1.07pre44
943 @end example
944
945 Now run the @code{./configure} script.  To avoid complications with
946 automatic font detection, add
947
948 @example
949 --with-ncsb-dir=/opt/local/share/ghostscript/fonts
950 @end example
951
952
953 @unnumberedsubsubsec Solaris
954
955 Solaris7, ./configure
956
957 @file{./configure} needs a POSIX compliant shell.  On Solaris7,
958 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
959 is.  Run configure like
960
961 @example
962 CONFIG_SHELL=/bin/ksh ksh -c ./configure
963 @end example
964
965 @noindent
966 or
967
968 @example
969 CONFIG_SHELL=/bin/bash bash -c ./configure
970 @end example
971
972 @unnumberedsubsubsec FreeBSD
973
974 To use system fonts, dejaview must be installed.  With the default
975 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
976
977 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
978 following line just after the @code{<fontconfig>} line.  (Adjust as necessary
979 for your hierarchy.)
980
981 @example
982 <dir>/usr/X11R6/lib/X11/fonts</dir>
983 @end example
984
985
986 @unnumberedsubsubsec International fonts
987
988 On Mac OS X, all fonts are installed by default.  However, finding all
989 system fonts requires a bit of configuration; see
990 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
991 this post} on the @code{lilypond-user} mailing list.
992
993 On Linux, international fonts are installed by different means on
994 every distribution.  We cannot list the exact commands or packages
995 that are necessary, as each distribution is different, and the exact
996 package names within each distribution changes.  Here are some
997 hints, though:
998
999 @verbatim
1000 Red Hat Fedora
1001
1002     taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
1003          ttfonts-zh_CN fonts-ja fonts-hebrew
1004
1005 Debian GNU/Linux
1006
1007    apt-get install emacs-intl-fonts xfonts-intl-.* \
1008         ttf-kochi-gothic ttf-kochi-mincho \
1009         xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
1010 @end verbatim
1011
1012
1013 @unnumberedsubsubsec Using lilypond python libraries
1014
1015 If you want to use lilypond's python libraries (either running
1016 certain build scripts manually, or using them in other programs),
1017 set @code{PYTHONPATH} to @file{python/out} in your build
1018 directory, or @file{.../usr/lib/lilypond/current/python} in the
1019 installation directory structure.
1020
1021
1022
1023
1024 @node Concurrent stable and development versions
1025 @section Concurrent stable and development versions
1026
1027
1028 It can be useful to have both the stable and the development versions
1029 of Lilypond available at once.  One way to do this on GNU/Linux is to
1030 install the stable version using the precompiled binary, and run the
1031 development version from the source tree.  After running @command{make
1032 all} from the top directory of the Lilypond source files, there will
1033 be a binary called @code{lilypond} in the @code{out} directory:
1034
1035 @example
1036 <@var{path to}>/lilypond/out/bin/lilypond
1037 @end example
1038
1039 This binary can be run without actually doing the @code{make
1040 install} command.  The advantage to this is that you can have all
1041 of the latest changes available after pulling from git and running
1042 @code{make all}, without having to uninstall the old version and
1043 reinstall the new.
1044
1045 So, to use the stable version, install it as usual and use the
1046 normal commands:
1047
1048 @example
1049 lilypond foobar.ly
1050 @end example
1051
1052 To use the development version, create a link to the binary in the
1053 source tree by saving the following line in a file somewhere in your
1054 @code{$PATH}:
1055
1056 @example
1057 exec <@var{path to}>/lilypond/out/bin/lilypond "$@@"
1058 @end example
1059
1060 Save it as @code{Lilypond} (with a capital L to distinguish it
1061 from the stable @code{lilypond}), and make it executable:
1062
1063 @example
1064 chmod +x Lilypond
1065 @end example
1066
1067 Then you can invoke the development version this way:
1068
1069 @example
1070 Lilypond foobar.ly
1071 @end example
1072
1073
1074 TODO: ADD
1075
1076 - other compilation tricks for developers
1077
1078
1079 @node Using a Virtual Machine to Compile LilyPond
1080 @section Using a Virtual Machine to Compile LilyPond
1081
1082
1083 TODO: rewrite for lily-git.tcl !!!  do before GOP!  -gp
1084
1085 Since it is not possible to compile Lilypond on Windows, some
1086 developers may find it useful to install a GNU/Linux virtual
1087 machine.  A disk image with a special remix of @strong{Ubuntu}
1088 has been created for this purpose.  It has all of the Lilypond
1089 build dependencies in place, so that once installed, it is
1090 ready to compile both Lilypond and the Documentation.
1091 The @code{lilybuntu} remix is available for download here:
1092
1093 @example
1094 @uref{http://@/files.lilynet.net/@/lilybuntu.iso}
1095 @end example
1096
1097 We do not necessarily recommend any one virtualization tool,
1098 however the @code{lilybuntu} remix is known to work well on
1099 @uref{http://www.virtualbox.org/wiki/Downloads, Sun VirtualBox},
1100 which is a free download.  Consult your virtualization software's
1101 documentation for instructions on setting up the software and
1102 for general instructions on installing a virtual machine.
1103
1104 Steps to setting up @code{lilybuntu} in a virtual machine:
1105
1106 @enumerate
1107 @item Download the @code{lilybuntu} disk image.
1108
1109 @item Install @code{lilybuntu}.  You will use the @code{.iso}
1110 file as the boot disk.  It should not be necessary to burn it
1111 to a DVD, but consult the documentation for your virtualization
1112 software for specific instructions.  If possible, use at least 500
1113 MB of RAM (1GB would be better!) for the virtual machine, and use
1114 a dynamically expanding virtual hard drive.
1115 A virtual hard drive with 6 GB will be enough to compile LilyPond,
1116 but if you intend to build the docs and run the regression tests
1117 the virtual hard drive should be at least 10 GB.
1118 The Ubuntu installation should be straightforward, although in the
1119 partitioning stage do not be afraid to select @qq{use entire disk,}
1120 since this is only your @strong{virtual disk} and not your
1121 machine's actual hard drive.
1122
1123 @item After installation is complete, restart the virtual
1124 machine.  If you are using @strong{VirtualBox}, you may wish
1125 to install the @qq{Guest Additions}, which while not essential for
1126 compiling @code{Lilypond} will allow you to use the virtual machine
1127 in full screen, Seamless mode (also known as Unity mode on other
1128 virtualization platforms) and allow you to share clipboards between
1129 the physical and virtual machine.  From the @code{Devices} menu select
1130 @code{Install Guest Additions...}, the @code{VBOXADDITIONS} CDROM device
1131 will appear on the desktop.  Open a @strong{terminal} session.
1132 (@code{Applications > Accessories > Terminal}) and @code{cd} to the
1133 top level of the CDROM.  Run the @code{autorun.sh} script as superuser
1134 (@code{sudo ./autorun.sh }), a console window will open while the
1135 @qq{Guest Additions} are being installed.  Once the script has
1136 been finished, reboot your Virtual Machine to complete the installation
1137 of the @qq{Guest Additions}.
1138
1139 @item Open a @strong{terminal} session.
1140 (@code{Applications > Accessories > Terminal})
1141
1142 @item Open @strong{Firefox} (there's an icon for it on the
1143 panel at the top of the screen) and go to the online Lilypond
1144 @uref{http://lilypond.org/doc/latest/Documentation/contributor/,
1145 Contributor's Guide}.
1146
1147 @item To retrieve the Lilypond source code from @code{git},
1148 copy-and-paste each command from the CG @qq{Main source code}
1149 section into the terminal (paste into the terminal with keystroke
1150 @code{CTRL+SHIFT+V}).
1151
1152 @item Prepare to build Lilypond by running the configuration script.
1153 Type
1154
1155 @example
1156 ./autogen.sh
1157 @end example
1158
1159 When it is finished you should be presented
1160 with the three most common @code{make} options:
1161
1162 @example
1163 Type:
1164     make all       to build LilyPond
1165     make install   to install LilyPond
1166     make help      to see all possible targets
1167
1168 Edit local.make for local Makefile overrides.
1169 @end example
1170
1171 @item First type @code{make all} to build Lilypond.  This will take
1172 a while.
1173
1174 @item When Lilypond is finished building, build the documentation
1175 by typing
1176
1177 @example
1178 make doc
1179 @end example
1180
1181 Depending on your system specs it could take from 30-60 minutes
1182 to finish.
1183
1184 @end enumerate
1185
1186 At this point everything has been compiled.
1187 You may install Lilypond using @code{make install}, or you may wish
1188 to set up your system with concurrent stable and development
1189 versions as described in the previous section.
1190
1191
1192 @node Build system
1193 @section Build system
1194
1195
1196 We currently use make and stepmake, which is complicated and only
1197 used by us.  Hopefully this will change in the future.
1198
1199
1200 @subsubheading Version-specific texinfo macros
1201
1202 @itemize
1203
1204 @item
1205 made with @command{scripts/build/create-version-itexi.py} and@*
1206 @command{scripts/build/create-weblinks-itexi.py}
1207
1208 @item
1209 used extensively in the @code{WEBSITE_ONLY_BUILD} version of the
1210 website (made with website.make, used on lilypond.org)
1211
1212 @item
1213 not (?) used in the main docs?
1214
1215 @item
1216 the numbers in VERSION file: MINOR_VERSION should be 1 more than
1217 the last release, VERSION_DEVEL should be the last @strong{online}
1218 release.  Yes, VERSION_DEVEL is less than VERSION.
1219
1220 @end itemize