1 @c -*- coding: utf-8; mode: texinfo; -*-
4 @c DO NOT TRANSLATE THIS FILE
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
12 * Overview of compiling::
14 * Getting the source code::
15 * Configuring @command{make}::
16 * Compiling LilyPond::
17 * Post-compilation options::
19 * Concurrent stable and development versions::
20 * Using a Virtual Machine to Compile LilyPond::
25 @node Overview of compiling
26 @section Overview of compiling
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.
35 Compiling LilyPond from source is necessary if you want to build,
36 install, or test your own version of the program.
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
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}).
56 * Requirements for running LilyPond::
57 * Requirements for compiling LilyPond::
58 * Requirements for building documentation::
62 @node Requirements for running LilyPond
63 @subsection Requirements for running LilyPond
65 Running LilyPond requires proper installation of the following
69 @item @uref{http://www.dejavu-fonts.org/, DejaVu fonts} (normally
72 @item @uref{http://www.fontconfig.org/, FontConfig} (2.4.0 or newer)
74 @item @uref{http://www.freetype.org/, Freetype} (2.1.10 or newer)
76 @item @uref{http://www.ghostscript.com, Ghostscript} (8.60 or
79 @item @uref{http://www.gnu.org/software/guile/guile.html, Guile}
82 @item @uref{http://www.pango.org/, Pango} (1.12 or newer)
84 @item @uref{http://www.python.org, Python} (2.4 or newer)
87 International fonts are required to create music with
88 international text or lyrics.
91 @node Requirements for compiling LilyPond
92 @subsection Requirements for compiling LilyPond
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:
98 @multitable @columnfractions .5 .5
99 @headitem Distribution @tab Command
101 @tab @code{sudo apt-get build-dep lilypond}
104 @tab @code{sudo yum-builddep lilypond}
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}
113 @item Everything listed in @ref{Requirements for running
116 @item Development packages for the above items (which should
117 include header files and libraries).
121 @c ghostscript-devel-[version] isn't needed
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}
132 @c libgs-dev isn't needed
134 guile-@var{version}-dev
138 python@var{version}-dev
141 @item @uref{http://flex.sourceforge.net/, Flex}
143 @item @uref{http://fontforge.sf.net/, FontForge} (20060125 or
146 @item @uref{http://www.gnu.org/software/bison/, GNU Bison}
148 @item @uref{http://gcc.gnu.org/, GNU Compiler Collection} (3.4 or
149 newer, 4.@var{x} recommended)
151 @item @uref{http://www.gnu.org/software/gettext/gettext.html, GNU
152 gettext} (0.17 or newer)
154 @item @uref{http://www.gnu.org/software/make/, GNU Make} (3.78 or
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{}}.
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{}}.
165 @item @uref{http://www.perl.org/, Perl}
167 @item @uref{http://www.gnu.org/software/texinfo/, Texinfo} (4.11
170 @item @uref{http://www.lcdf.org/~eddietwo/type/#t1utils, Type 1
171 utilities} (1.33 or newer recommended)
175 @node Requirements for building documentation
176 @subsection Requirements for building documentation
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
184 @item Everything listed in @ref{Requirements for compiling
187 @item @uref{http://www.imagemagick.org/, ImageMagick}
189 @item @uref{http://netpbm.sourceforge.net/, Netpbm}
191 @item @uref{http://rsync.samba.org/, rsync}
193 @item @uref{http://www.nongnu.org/texi2html/, Texi2HTML} (1.82)
195 @item International fonts
223 @node Getting the source code
224 @section Getting the source code
227 @subheading Downloading the Git repository
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}.
234 @subheading Downloading a source tarball
236 Packagers are encouraged to use source tarballs for compiling.
238 The tarball for the latest stable release is available on the
243 @uref{http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=snapshot, source code snapshot}
244 is also available as a tarball from the GNU Savannah Git server.
247 All tagged releases (including legacy stable
248 versions and the most recent development release) are available
252 @uref{http://download.linuxaudio.org/lilypond/source/}
255 Download the tarball to your @file{~/src/} directory, or some
256 other appropriate place.
258 @warning{Be careful where you unpack the tarball! Any
259 subdirectories of the current folder named @file{lilypond/} or
260 @file{lilypond-@var{x.y.z}/} (where @var{x.y.z} is the release
261 number) will be overwritten if there is a name clash with the
264 Unpack the tarball with this command:
267 tar -xzf lilypond-@var{x.y.z}.tar.gz
270 This creates a subdirectory within the current directory called
271 @file{lilypond-@var{x.y.z}/}. Once unpacked, the source files
272 occupy about 40 MB of disk space.
274 Windows users wanting to look at the source code may have to
275 download and install the free-software
276 @uref{http://www.7-zip.org, 7zip archiver} to extract the tarball.
279 @node Configuring @command{make}
280 @section Configuring @command{make}
284 * Running @command{./autogen.sh}::
285 * Running @command{./configure}::
289 @node Running @command{./autogen.sh}
290 @subsection Running @command{./autogen.sh}
292 After you unpack the tarball (or download the Git repository), the
293 contents of your top source directory should be similar to the
294 current source tree listed at
295 @uref{http://git.sv.gnu.org/gitweb/?p=lilypond.git;a=tree}.
297 Next, you need to create the generated files; enter the following
298 command from your top source directory:
307 @item generate a number of files and directories to aid
308 configuration, such as @file{configure}, @file{README.txt}, etc.
310 @item automatically run the @command{./configure} command.
314 @node Running @command{./configure}
315 @subsection Running @command{./configure}
318 * Configuration options::
319 * Checking build dependencies::
320 * Configuring target directories::
321 * Making an out-of-tree build::
325 @node Configuration options
326 @unnumberedsubsubsec Configuration options
328 The @command{./configure} command (generated by
329 @command{./autogen.sh}) provides many options for configuring
330 @command{make}. To see them all, run:
337 @node Checking build dependencies
338 @unnumberedsubsubsec Checking build dependencies
340 When @command{./configure} is run without any arguments, it will
341 check to make sure your system has everything required for
342 compilation. This is done automatically when
343 @command{./autogen.sh} is run. If any build dependency is
344 missing, @command{./configure} will return with:
347 ERROR: Please install required programs: @var{foo}
350 The following message is issued if you are missing programs that
351 are only needed for building the documentation:
354 WARNING: Please consider installing optional programs: @var{bar}
357 If you intend to build the documentation locally, you will need to
358 install or update these programs accordingly.
360 @warning{@command{./configure} may fail to issue warnings for
361 certain documentation build requirements that are not met. If you
362 experience problems when building the documentation, you may need
363 to do a manual check of @ref{Requirements for building
367 @node Configuring target directories
368 @unnumberedsubsubsec Configuring target directories
370 If you intend to use your local build to install a local copy of
371 the program, you will probably want to configure the installation
372 directory. Here are the relevant lines taken from the output of
373 @command{./configure@tie{}--help}:
376 By default, `@command{make@tie{}install}' will install all the
377 files in @file{/usr/local/bin}, @file{/usr/local/lib} etc. You
378 can specify an installation prefix other than @file{/usr/local}
379 using `@code{--prefix}', for instance `@code{--prefix=$HOME}'.
382 A typical installation prefix is @file{$HOME/usr}:
385 ./configure --prefix=$HOME/usr
388 Note that if you plan to install a local build on a system where
389 you do not have root privileges, you will need to do something
390 like this anyway---@command{make@tie{}install} will only succeed
391 if the installation prefix points to a directory where you have
392 write permission (such as your home directory). The installation
393 directory will be automatically created if necessary.
395 The location of the @command{lilypond} command installed by this
396 process will be @file{@var{prefix}/bin/lilypond}; you may want to
397 add @file{@var{prefix}/bin/} to your @code{$PATH} if it is not
400 It is also possible to specify separate installation directories
401 for different types of program files. See the full output of
402 @command{./configure@tie{}--help} for more information.
404 If you encounter any problems, please see @ref{Problems}.
407 @node Making an out-of-tree build
408 @unnumberedsubsubsec Making an out-of-tree build
410 It is possible to compile LilyPond in a build tree different from
411 the source tree, using the @option{--srcdir} option of
412 @command{configure}. Note that in some cases you may need to
413 remove the output of a previous @command{configure} command by
414 running @command{make@tie{}distclean} in the main source directory
415 before configuring the out-of-tree build:
419 mkdir lily-build && cd lily-build
420 @var{sourcedir}/configure --srcdir=@var{sourcedir}
424 @node Compiling LilyPond
425 @section Compiling LilyPond
429 * Using @command{make}::
430 * Saving time with the @option{-j} option::
431 * Compiling for multiple platforms::
432 * Useful @command{make} variables::
436 @node Using @command{make}
437 @subsection Using @command{make}
439 LilyPond is compiled with the @command{make} command. Assuming
440 @command{make} is configured properly, you can simply run:
446 @samp{make} is short for @samp{make all}. To view a list of @command{make}
453 TODO: Describe what @command{make} actually does.
456 @node Saving time with the @option{-j} option
457 @subsection Saving time with the @option{-j} option
459 If your system has multiple CPUs, you can speed up compilation by
460 adding @samp{-j@var{X}} to the @command{make} command, where
461 @samp{@var{X}} is one more than the number of cores you have. For
462 example, a typical Core2Duo machine would use:
468 If you get errors using the @option{-j} option, and @samp{make}
469 succeeds without it, try lowering the @code{@var{X}} value.
472 @node Compiling for multiple platforms
473 @subsection Compiling for multiple platforms
475 If you want to build multiple versions of LilyPond with different
476 configuration settings, you can use the
477 @code{--enable-config=@var{CONF}} option of @command{configure}.
478 You should use @code{make@tie{}conf=@var{CONF}} to generate the
479 output in @file{out-@var{CONF}}. For example, suppose you want to
480 build with and without profiling, then use the following for the
484 ./configure --prefix=$HOME/usr/ --enable-checking
488 and for the profiling version, specify a different configuration
491 ./configure --prefix=$HOME/usr/ --enable-profiling \
492 --enable-config=prof --disable-checking
496 If you wish to install a copy of the build with profiling, don't
497 forget to use @code{conf=@var{CONF}} when issuing
498 @command{make@tie{}install}:
501 make conf=prof install
506 @ref{Installing LilyPond from a local build}
509 @node Useful @command{make} variables
510 @subsection Useful @command{make} variables
512 If a less verbose build output if desired, the variable
513 @code{QUIET_BUILD} may be set to @code{1} on @command{make}
514 command line, or in @file{local.make} at top of the build tree.
517 @node Post-compilation options
518 @section Post-compilation options
522 * Installing LilyPond from a local build::
523 * Generating documentation::
528 @node Installing LilyPond from a local build
529 @subsection Installing LilyPond from a local build
531 If you configured @command{make} to install your local build in a
532 directory where you normally have write permission (such as your
533 home directory), and you have compiled LilyPond by running
534 @command{make}, you can install the program in your target
535 directory by running:
541 If instead, your installation directory is not one that you can
542 normally write to (such as the default @file{/usr/local/}, which
543 typically is only writeable by the superuser), you will need to
544 temporarily become the superuser when running
545 @command{make@tie{}install}:
558 If you don't have superuser privileges, then you need to configure
559 the installation directory to one that you can write to, and then
560 re-install. See @ref{Configuring target directories}.
563 @node Generating documentation
564 @subsection Generating documentation
568 * Documentation editor's edit/compile cycle::
569 * Building documentation::
570 * Saving time with @code{CPU_COUNT}::
571 * Installing documentation::
572 * Building documentation without compiling::
576 @node Documentation editor's edit/compile cycle
577 @unnumberedsubsubsec Documentation editor's edit/compile cycle
581 Initial documentation build:
585 make [-j@var{X} CPU_COUNT=@var{X}] doc @emph{## can take an hour or more}
592 @emph{## edit source files, then...}
594 make [-j@var{X}] @emph{## needed if editing outside}
595 @emph{## Documentation/, but useful anyway}
596 @emph{## for finding Texinfo errors.}
597 touch Documentation/*te?? @emph{## bug workaround}
598 make [-j@var{X} CPU_COUNT=@var{X}] doc @emph{## usually faster than initial build.}
605 make doc-clean @emph{## use only as a last resort.}
609 @node Building documentation
610 @unnumberedsubsubsec Building documentation
612 After a successful compile (using @command{make}), the
613 documentation can be built by issuing:
619 The first time you run @command{make@tie{}doc}, the process can
620 easily take an hour or more. After that, @command{make@tie{}doc}
621 only makes changes to the pre-built documentation where needed,
622 so it may only take a minute or two to test changes if the
623 documentation is already built.
625 If @command{make@tie{}doc} succeeds, the HTML documentation tree
626 is available in @file{out-www/offline-root/}, and can be browsed
627 locally. Various portions of the documentation can be found by
628 looking in @file{out/} and @file{out-www} subdirectories in other
629 places in the source tree, but these are only @emph{portions} of
630 the docs. Please do not complain about anything which is broken
631 in those places; the only complete set of documentation is in
632 @file{out-www/offline-root/} from the top of the source tree.
634 Compilation of documentation in Info format with images can be
635 done separately by issuing:
643 If source files have changed since the last documentation build,
644 output files that need to be rebuilt are normally rebuilt, even if
645 you do not run @code{make@tie{}doc-clean} first. However, build
646 dependencies in the documentation are so complex that some
647 newly-edited files may not be rebuilt as they should be; a
648 workaround is to @command{touch} the top source file for any
649 manual you've edited. For example, if you make changes to a file
650 in @file{notation/}, do:
653 touch Documentation/notation.tely
657 The top sources possibly affected by this are:
660 Documentation/extend.texi
661 Documentation/changes.tely
662 Documentation/contributor.texi
663 Documentation/essay.tely
664 Documentation/extending.tely
665 Documentation/learning.tely
666 Documentation/notation.tely
667 Documentation/snippets.tely
668 Documentation/usage.tely
669 Documentation/web.texi
673 You can @command{touch} all of them at once with:
676 touch Documentation/*te??
680 However, this will rebuild all of the manuals
681 indiscriminately---it is more efficient to @command{touch} only
685 @node Saving time with @code{CPU_COUNT}
686 @unnumberedsubsubsec Saving time with @code{CPU_COUNT}
688 The most time consuming task for building the documentation is
689 running LilyPond to build images of music, and there cannot be
690 several simultaneously running @command{lilypond-book} instances,
691 so the @option{-j} @command{make} option does not significantly
692 speed up the build process. To help speed it up, the makefile
693 variable @option{CPU_COUNT} may be set in @file{local.make} or on
694 the command line to the number of @code{.ly} files that LilyPond
695 should process simultaneously, e.g. on a bi-processor or dual core
699 make -j3 CPU_COUNT=3 doc
703 The recommended value of @option{CPU_COUNT} is one plus the number
704 of cores or processors, but it is advisable to set it to a smaller
705 value unless your system has enough RAM to run that many
706 simultaneous LilyPond instances. Also, values for the @option{-j}
707 option that pose problems with @samp{make} are less likely to pose
708 problems with @samp{make doc} (this applies to both @option{-j}
709 and @option{CPU_COUNT}). For example, with a quad-core processor,
710 it is possible for @samp{make -j5 CPU_COUNT=5 doc} to work
711 consistently even if @samp{make -j5} rarely succeeds.
714 @node Installing documentation
715 @unnumberedsubsubsec Installing documentation
717 The HTML, PDF and if available Info files can be installed into
718 the standard documentation path by issuing
725 This also installs Info documentation with images if the
726 installation prefix is properly set; otherwise, instructions to
727 complete proper installation of Info documentation are printed on
730 To install the Info documentation separately, run:
737 Note that to get the images in Info documentation, @code{install-doc}
738 target creates symbolic links to HTML and PDF installed documentation
739 tree in @file{@var{prefix}/share/info}, in order to save disk space,
740 whereas @code{install-info} copies images in
741 @file{@var{prefix}/share/info} subdirectories.
743 It is possible to build a documentation tree in
744 @file{out-www/online-root/}, with special processing, so it can be
745 used on a website with content negotiation for automatic language
746 selection; this can be achieved by issuing
749 make WEB_TARGETS=online doc
753 and both @q{offline} and @q{online} targets can be generated by issuing
756 make WEB_TARGETS="offline online" doc
759 Several targets are available to clean the documentation build and
760 help with maintaining documentation; an overview of these targets is
768 from every directory in the build tree. Most targets for
769 documentation maintenance are available from
770 @file{Documentation/}; for more information, see
771 @rcontrib{Documentation work}.
773 The makefile variable @code{QUIET_BUILD} may be set to @code{1}
774 for a less verbose build output, just like for building the
778 @node Building documentation without compiling
779 @unnumberedsubsubsec Building documentation without compiling
782 The documentation can be built locally without compiling LilyPond
783 binary, if LilyPond is already installed on your system.
785 From a fresh Git checkout, do
788 ./autogen.sh # ignore any warning messages
789 cp GNUmakefile.in GNUmakefile
790 make -C scripts && make -C python
791 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
794 Please note that this may break sometimes -- for example, if a new
795 feature is added with a test file in input/regression, even the latest
796 development release of LilyPond will fail to build the docs.
798 You may build the manual without building all the @file{input/*} stuff
799 (i.e. mostly regression tests): change directory, for example to
800 @file{Documentation/}, issue @code{make doc}, which will build
801 documentation in a subdirectory @file{out-www} from the source files in
802 current directory. In this case, if you also want to browse the
803 documentation in its post-processed form, change back to top directory
807 make out=www WWW-post
812 You may also need to create a script for @command{pngtopnm} and
813 @code{pnmtopng}. On GNU/Linux, I use this:
816 export LD_LIBRARY_PATH=/usr/lib
817 exec /usr/bin/pngtopnm "$@"
820 On MacOS X with fink, I use this:
823 export DYLD_LIBRARY_PATH=/sw/lib
824 exec /sw/bin/pngtopnm "$@"
827 On MacOS X with macports, you should use this:
830 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
831 exec /opt/local/bin/pngtopnm "$@"
835 @node Testing LilyPond
836 @subsection Testing LilyPond
839 LilyPond comes with an extensive suite that exercises the entire
840 program. This suite can be used to automatically check the impact
844 * Developer's edit/compile/test cycle::
848 @node Developer's edit/compile/test cycle
849 @unnumberedsubsubsec Developer's edit/compile/test cycle
851 TODO: is @code{[-j@var{X} CPU_COUNT=@var{X}]} useful for
852 @code{test-baseline}, @code{check}, @code{clean},
862 make [-j@var{X} CPU_COUNT=@var{X}] check
866 Edit/compile/test cycle:
869 @emph{## edit source files, then...}
871 make clean @emph{## only if needed (see below)}
872 make [-j@var{X}] @emph{## only if needed (see below)}
873 make test-redo @emph{## redo files differing from baseline}
874 make [-j@var{X} CPU_COUNT=@var{X}] check @emph{## CPU_COUNT here?}
885 If you modify any source files that have to be compiled (such as
886 @file{.cc} or @file{.hh} files in @file{flower/} or @file{lily/}),
887 then you must run @command{make} before @command{make test-redo},
888 so @command{make} can compile the modified files and relink all
889 the object files. If you only modify files which are interpreted,
890 like those in the @file{scm/} and @file{ly/} directories, then
891 @command{make} is not needed before @command{make test-redo}.
893 Also, if you modify any font definitions in the @file{mf/}
894 directory then you must run @command{make clean} and
895 @command{make} before running @command{make test-redo}. This will
896 recompile everything, whether modified or not, and takes a lot
899 Running @command{make@tie{}check} will leave an HTML page
900 @file{out/test-results/index.html}. This page shows all the
901 important differences that your change introduced, whether in the
902 layout, MIDI, performance or error reporting.
906 @unnumberedsubsubsec Other tests
908 For tracking memory usage as part of this test, you will need
909 GUILE CVS; especially the following patch:
910 @uref{http://www.lilypond.org/vc/old/gub.darcs/patches/guile-1.9-gcstats.patch}.
912 For checking the coverage of the test suite, do the following
915 ./scripts/auxiliar/build-coverage.sh
916 @emph{# uncovered files, least covered first}
917 ./scripts/auxiliar/coverage.py --summary out-cov/*.cc
918 @emph{# consecutive uncovered lines, longest first}
919 ./scripts/auxiliar/coverage.py --uncovered out-cov/*.cc
926 For help and questions use @email{lilypond-user@@gnu.org}. Send
927 bug reports to @email{bug-lilypond@@gnu.org}.
929 Bugs that are not fault of LilyPond are documented here.
931 @unnumberedsubsubsec Bison 1.875
933 There is a bug in bison-1.875: compilation fails with "parse error
934 before `goto'" in line 4922 due to a bug in bison. To fix, please
935 recompile bison 1.875 with the following fix
938 $ cd lily; make out/parser.cc
939 $ vi +4919 out/parser.cc
940 # append a semicolon to the line containing "__attribute__ ((__unused__))
946 @unnumberedsubsubsec Compiling on MacOS@tie{}X
948 Here are special instructions for compiling under MacOS@tie{}X.
949 These instructions assume that dependencies are installed using
950 @uref{http://www.macports.org/, MacPorts.} The instructions have
951 been tested using OS X 10.5 (Leopard).
953 First, install the relevant dependencies using MacPorts.
955 Next, add the following to your relevant shell initialization
956 files. This is @code{~/.profile} by default. You should create
957 this file if it does not exist.
960 export PATH=/opt/local/bin:/opt/local/sbin:$PATH
961 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
964 Now you must edit the generated @code{config.make} file. Change
967 FLEXLEXER_FILE = /usr/include/FlexLexer.h
974 FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
977 At this point, you should verify that you have the appropriate
978 fonts installed with your ghostscript installation. Check @code{ls
979 /opt/local/share/ghostscript/fonts} for: 'c0590*' files (.pfb,
980 .pfb and .afm). If you don't have them, run the following
981 commands to grab them from the ghostscript SVN server and install
982 them in the appropriate location:
985 svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
986 sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
987 rm -rf urw-fonts-1.07pre44
990 Now run the @code{./configure} script. To avoid complications with
991 automatic font detection, add
994 --with-ncsb-dir=/opt/local/share/ghostscript/fonts
998 @unnumberedsubsubsec Solaris
1000 Solaris7, ./configure
1002 @file{./configure} needs a POSIX compliant shell. On Solaris7,
1003 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
1004 is. Run configure like
1007 CONFIG_SHELL=/bin/ksh ksh -c ./configure
1014 CONFIG_SHELL=/bin/bash bash -c ./configure
1017 @unnumberedsubsubsec FreeBSD
1019 To use system fonts, dejaview must be installed. With the default
1020 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
1022 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
1023 following line just after the @code{<fontconfig>} line. (Adjust as necessary
1024 for your hierarchy.)
1027 <dir>/usr/X11R6/lib/X11/fonts</dir>
1031 @unnumberedsubsubsec International fonts
1033 On Mac OS X, all fonts are installed by default. However, finding all
1034 system fonts requires a bit of configuration; see
1035 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
1036 this post} on the @code{lilypond-user} mailing list.
1038 On Linux, international fonts are installed by different means on
1039 every distribution. We cannot list the exact commands or packages
1040 that are necessary, as each distribution is different, and the exact
1041 package names within each distribution changes. Here are some
1047 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
1048 ttfonts-zh_CN fonts-ja fonts-hebrew
1052 apt-get install emacs-intl-fonts xfonts-intl-.* \
1053 ttf-kochi-gothic ttf-kochi-mincho \
1054 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
1058 @unnumberedsubsubsec Using lilypond python libraries
1060 If you want to use lilypond's python libraries (either running
1061 certain build scripts manually, or using them in other programs),
1062 set @code{PYTHONPATH} to @file{python/out} in your build
1063 directory, or @file{.../usr/lib/lilypond/current/python} in the
1064 installation directory structure.
1069 @node Concurrent stable and development versions
1070 @section Concurrent stable and development versions
1073 It can be useful to have both the stable and the development versions
1074 of Lilypond available at once. One way to do this on GNU/Linux is to
1075 install the stable version using the precompiled binary, and run the
1076 development version from the source tree. After running @command{make
1077 all} from the top directory of the Lilypond source files, there will
1078 be a binary called @code{lilypond} in the @code{out} directory:
1081 <@var{path to}>/lilypond/out/bin/lilypond
1084 This binary can be run without actually doing the @code{make
1085 install} command. The advantage to this is that you can have all
1086 of the latest changes available after pulling from git and running
1087 @code{make all}, without having to uninstall the old version and
1090 So, to use the stable version, install it as usual and use the
1097 To use the development version, create a link to the binary in the
1098 source tree by saving the following line in a file somewhere in your
1102 exec <@var{path to}>/lilypond/out/bin/lilypond "$@@"
1105 Save it as @code{Lilypond} (with a capital L to distinguish it
1106 from the stable @code{lilypond}), and make it executable:
1112 Then you can invoke the development version this way:
1121 - other compilation tricks for developers
1124 @node Using a Virtual Machine to Compile LilyPond
1125 @section Using a Virtual Machine to Compile LilyPond
1128 TODO: rewrite for lily-git.tcl !!! do before GOP! -gp
1130 Since it is not possible to compile Lilypond on Windows, some
1131 developers may find it useful to install a GNU/Linux virtual
1132 machine. A disk image with a special remix of @strong{Ubuntu}
1133 has been created for this purpose. It has all of the Lilypond
1134 build dependencies in place, so that once installed, it is
1135 ready to compile both Lilypond and the Documentation.
1136 The @code{lilybuntu} remix is available for download here:
1139 @uref{http://@/files.lilynet.net/@/lilybuntu.iso}
1142 We do not necessarily recommend any one virtualization tool,
1143 however the @code{lilybuntu} remix is known to work well on
1144 @uref{http://www.virtualbox.org/wiki/Downloads, Sun VirtualBox},
1145 which is a free download. Consult your virtualization software's
1146 documentation for instructions on setting up the software and
1147 for general instructions on installing a virtual machine.
1149 Steps to setting up @code{lilybuntu} in a virtual machine:
1152 @item Download the @code{lilybuntu} disk image.
1154 @item Install @code{lilybuntu}. You will use the @code{.iso}
1155 file as the boot disk. It should not be necessary to burn it
1156 to a DVD, but consult the documentation for your virtualization
1157 software for specific instructions. If possible, use at least
1158 the recommended amount of RAM for the virtual machine (384 MB on
1159 VirtualBox), and use a dynamically expanding virtual hard drive.
1160 A virtual hard drive with 6 GB will be enough to compile LilyPond,
1161 but if you intend to build the docs and run the regression tests
1162 the virtual hard drive should be at least 10 GB.
1163 The Ubuntu installation should be straightforward, although in the
1164 partitioning stage do not be afraid to select @qq{use entire disk,}
1165 since this is only your @strong{virtual disk} and not your
1166 machine's actual hard drive.
1168 @item After installation is complete, restart the virtual
1169 machine. If you are using @strong{VirtualBox}, you may wish
1170 to install the @qq{Guest Additions}, which while not essential for
1171 compiling @code{Lilypond} will allow you to use the virtual machine
1172 in full screen, Seamless mode (also known as Unity mode on other
1173 virtualization platforms) and allow you to share clipboards between
1174 the physical and virtual machine. From the @code{Devices} menu select
1175 @code{Install Guest Additions...}, the @code{VBOXADDITIONS} CDROM device
1176 will appear on the desktop. Open a @strong{terminal} session.
1177 (@code{Applications > Accessories > Terminal}) and @code{cd} to the
1178 top level of the CDROM. Run the @code{autorun.sh} script as superuser
1179 (@code{sudo ./autorun.sh }), a console window will open while the
1180 @qq{Guest Additions} are being installed. Once the script has
1181 been finished, reboot your Virtual Machine to complete the installation
1182 of the @qq{Guest Additions}.
1184 @item Open a @strong{terminal} session.
1185 (@code{Applications > Accessories > Terminal})
1187 @item Open @strong{Firefox} (there's an icon for it on the
1188 panel at the top of the screen) and go to the online Lilypond
1189 @uref{http://lilypond.org/doc/latest/Documentation/contributor/,
1190 Contributor's Guide}.
1192 @item To retrieve the Lilypond source code from @code{git},
1193 copy-and-paste each command from the CG @qq{Main source code}
1194 section into the terminal. (paste into the terminal with keystroke
1195 @code{CTRL+SHIFT+V})
1197 @item Prepare to build Lilypond by running the configuration script.
1204 When it is finished you should be presented
1205 with the three most common @code{make} options:
1209 make all to build LilyPond
1210 make install to install LilyPond
1211 make help to see all possible targets
1213 Edit local.make for local Makefile overrides.
1216 @item First type @code{make all} to build Lilypond. This will take
1219 @item When Lilypond is finished building, build the documentation
1226 Depending on your system specs it could take from 30-60 minutes
1231 At this point everything has been compiled.
1232 You may install Lilypond using @code{make install}, or you may wish
1233 to set up your system with concurrent stable and development
1234 versions as described in the previous section.
1238 @section Build system
1241 We currently use make and stepmake, which is complicated and only
1242 used by us. Hopefully this will change in the future.
1245 @subsubheading Version-specific texinfo macors
1250 made with @command{scripts/build/create-version-itexi.py} and@*
1251 @command{scripts/build/create-weblinks-itexi.py}
1254 used extensively in the @code{WEBSITE_ONLY_BUILD} version of the
1255 website (made with website.make, used on lilypond.org)
1258 not (?) used in the main docs?
1261 the numbers in VERSION file: MINOR_VERSION should be 1 more than
1262 the last release, VERSION_DEVEL should be the last @strong{online}
1263 release. Yes, VERSION_DEVEL is less than VERSION.