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::
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 make
280 @section Configuring @command{make}
284 * Running ./autogen.sh::
285 * Running ./configure::
289 @node Running ./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 ./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
430 * Saving time with the -j option::
431 * Compiling for multiple platforms::
432 * Useful make variables::
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 -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.
471 Because multiple jobs run in parallel when @option{-j} is used, it can
472 be difficult to determine the source of an error when one occurs. In
473 that case, running @samp{make} without the @option{-j} is advised.
475 @node Compiling for multiple platforms
476 @subsection Compiling for multiple platforms
478 If you want to build multiple versions of LilyPond with different
479 configuration settings, you can use the
480 @code{--enable-config=@var{CONF}} option of @command{configure}.
481 You should use @code{make@tie{}conf=@var{CONF}} to generate the
482 output in @file{out-@var{CONF}}. For example, suppose you want to
483 build with and without profiling, then use the following for the
487 ./configure --prefix=$HOME/usr/ --enable-checking
491 and for the profiling version, specify a different configuration
494 ./configure --prefix=$HOME/usr/ --enable-profiling \
495 --enable-config=prof --disable-checking
499 If you wish to install a copy of the build with profiling, don't
500 forget to use @code{conf=@var{CONF}} when issuing
501 @command{make@tie{}install}:
504 make conf=prof install
509 @ref{Installing LilyPond from a local build}
512 @node Useful make variables
513 @subsection Useful @command{make} variables
515 If a less verbose build output if desired, the variable
516 @code{QUIET_BUILD} may be set to @code{1} on @command{make}
517 command line, or in @file{local.make} at top of the build tree.
520 @node Post-compilation options
521 @section Post-compilation options
525 * Installing LilyPond from a local build::
526 * Generating documentation::
527 * Testing LilyPond binary::
531 @node Installing LilyPond from a local build
532 @subsection Installing LilyPond from a local build
534 If you configured @command{make} to install your local build in a
535 directory where you normally have write permission (such as your
536 home directory), and you have compiled LilyPond by running
537 @command{make}, you can install the program in your target
538 directory by running:
544 If instead, your installation directory is not one that you can
545 normally write to (such as the default @file{/usr/local/}, which
546 typically is only writeable by the superuser), you will need to
547 temporarily become the superuser when running
548 @command{make@tie{}install}:
561 If you don't have superuser privileges, then you need to configure
562 the installation directory to one that you can write to, and then
563 re-install. See @ref{Configuring target directories}.
566 @node Generating documentation
567 @subsection Generating documentation
571 * Documentation editor's edit/compile cycle::
572 * Building documentation::
573 * Saving time with CPU_COUNT::
575 * Installing documentation::
576 * Building documentation without compiling::
580 @node Documentation editor's edit/compile cycle
581 @unnumberedsubsubsec Documentation editor's edit/compile cycle
585 Initial documentation build:
589 make [-j@var{X} CPU_COUNT=@var{X}] doc @emph{## can take an hour or more}
596 @emph{## edit source files, then...}
598 make [-j@var{X}] @emph{## needed if editing outside}
599 @emph{## Documentation/, but useful anyway}
600 @emph{## for finding Texinfo errors.}
601 touch Documentation/*te?? @emph{## bug workaround}
602 make [-j@var{X} CPU_COUNT=@var{X}] doc @emph{## usually faster than initial build.}
609 make doc-clean @emph{## use only as a last resort.}
613 @node Building documentation
614 @unnumberedsubsubsec Building documentation
616 After a successful compile (using @command{make}), the
617 documentation can be built by issuing:
623 The first time you run @command{make@tie{}doc}, the process can
624 easily take an hour or more. After that, @command{make@tie{}doc}
625 only makes changes to the pre-built documentation where needed,
626 so it may only take a minute or two to test changes if the
627 documentation is already built.
629 If @command{make@tie{}doc} succeeds, the HTML documentation tree
630 is available in @file{out-www/offline-root/}, and can be browsed
631 locally. Various portions of the documentation can be found by
632 looking in @file{out/} and @file{out-www} subdirectories in other
633 places in the source tree, but these are only @emph{portions} of
634 the docs. Please do not complain about anything which is broken
635 in those places; the only complete set of documentation is in
636 @file{out-www/offline-root/} from the top of the source tree.
638 Compilation of documentation in Info format with images can be
639 done separately by issuing:
647 If source files have changed since the last documentation build,
648 output files that need to be rebuilt are normally rebuilt, even if
649 you do not run @code{make@tie{}doc-clean} first. However, build
650 dependencies in the documentation are so complex that some
651 newly-edited files may not be rebuilt as they should be; a
652 workaround is to @command{touch} the top source file for any
653 manual you've edited. For example, if you make changes to a file
654 in @file{notation/}, do:
657 touch Documentation/notation.tely
661 The top sources possibly affected by this are:
664 Documentation/extend.texi
665 Documentation/changes.tely
666 Documentation/contributor.texi
667 Documentation/essay.tely
668 Documentation/extending.tely
669 Documentation/learning.tely
670 Documentation/notation.tely
671 Documentation/snippets.tely
672 Documentation/usage.tely
673 Documentation/web.texi
677 You can @command{touch} all of them at once with:
680 touch Documentation/*te??
684 However, this will rebuild all of the manuals
685 indiscriminately---it is more efficient to @command{touch} only
689 @node Saving time with CPU_COUNT
690 @unnumberedsubsubsec Saving time with @code{CPU_COUNT}
692 The most time consuming task for building the documentation is
693 running LilyPond to build images of music, and there cannot be
694 several simultaneously running @command{lilypond-book} instances,
695 so the @option{-j} @command{make} option does not significantly
696 speed up the build process. To help speed it up, the makefile
697 variable @option{CPU_COUNT} may be set in @file{local.make} or on
698 the command line to the number of @code{.ly} files that LilyPond
699 should process simultaneously, e.g. on a bi-processor or dual core
703 make -j3 CPU_COUNT=3 doc
707 The recommended value of @option{CPU_COUNT} is one plus the number
708 of cores or processors, but it is advisable to set it to a smaller
709 value unless your system has enough RAM to run that many
710 simultaneous LilyPond instances. Also, values for the @option{-j}
711 option that pose problems with @samp{make} are less likely to pose
712 problems with @samp{make doc} (this applies to both @option{-j}
713 and @option{CPU_COUNT}). For example, with a quad-core processor,
714 it is possible for @samp{make -j5 CPU_COUNT=5 doc} to work
715 consistently even if @samp{make -j5} rarely succeeds.
719 @unnumberedsubsubsec AJAX search
721 To build the documentation with interactive searching, use:
724 make doc AJAX_SEARCH=1
727 This requires PHP, and you must view the docs via a http
728 connection (you cannot view them on your local filesystem).
730 @warning{Due to potential security or load issues, this option is
731 not enabled in the official documentation builds. Enable at your
735 @node Installing documentation
736 @unnumberedsubsubsec Installing documentation
738 The HTML, PDF and if available Info files can be installed into
739 the standard documentation path by issuing
746 This also installs Info documentation with images if the
747 installation prefix is properly set; otherwise, instructions to
748 complete proper installation of Info documentation are printed on
751 To install the Info documentation separately, run:
758 Note that to get the images in Info documentation, @code{install-doc}
759 target creates symbolic links to HTML and PDF installed documentation
760 tree in @file{@var{prefix}/share/info}, in order to save disk space,
761 whereas @code{install-info} copies images in
762 @file{@var{prefix}/share/info} subdirectories.
764 It is possible to build a documentation tree in
765 @file{out-www/online-root/}, with special processing, so it can be
766 used on a website with content negotiation for automatic language
767 selection; this can be achieved by issuing
770 make WEB_TARGETS=online doc
774 and both @q{offline} and @q{online} targets can be generated by issuing
777 make WEB_TARGETS="offline online" doc
780 Several targets are available to clean the documentation build and
781 help with maintaining documentation; an overview of these targets is
789 from every directory in the build tree. Most targets for
790 documentation maintenance are available from
791 @file{Documentation/}; for more information, see
792 @rcontrib{Documentation work}.
794 The makefile variable @code{QUIET_BUILD} may be set to @code{1}
795 for a less verbose build output, just like for building the
799 @node Building documentation without compiling
800 @unnumberedsubsubsec Building documentation without compiling
803 The documentation can be built locally without compiling LilyPond
804 binary, if LilyPond is already installed on your system.
806 From a fresh Git checkout, do
809 ./autogen.sh # ignore any warning messages
810 cp GNUmakefile.in GNUmakefile
811 make -C scripts && make -C python
812 nice make LILYPOND_EXTERNAL_BINARY=/path/to/bin/lilypond doc
815 Please note that this may break sometimes -- for example, if a new
816 feature is added with a test file in input/regression, even the latest
817 development release of LilyPond will fail to build the docs.
819 You may build the manual without building all the @file{input/*} stuff
820 (i.e. mostly regression tests): change directory, for example to
821 @file{Documentation/}, issue @code{make doc}, which will build
822 documentation in a subdirectory @file{out-www} from the source files in
823 current directory. In this case, if you also want to browse the
824 documentation in its post-processed form, change back to top directory
828 make out=www WWW-post
833 You may also need to create a script for @command{pngtopnm} and
834 @code{pnmtopng}. On GNU/Linux, I use this:
837 export LD_LIBRARY_PATH=/usr/lib
838 exec /usr/bin/pngtopnm "$@"
841 On MacOS X with fink, I use this:
844 export DYLD_LIBRARY_PATH=/sw/lib
845 exec /sw/bin/pngtopnm "$@"
848 On MacOS X with macports, you should use this:
851 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib
852 exec /opt/local/bin/pngtopnm "$@"
856 @node Testing LilyPond binary
857 @subsection Testing LilyPond binary
860 LilyPond comes with an extensive suite that exercises the entire
861 program. This suite can be used to test that the binary has
862 been built correctly.
864 The test suite can be executed with:
870 If the test suite completes successfully, the LilyPond binary
873 More information on the regression test suite is found at
874 @rcontrib{Regression tests}.
879 For help and questions use @email{lilypond-user@@gnu.org}. Send
880 bug reports to @email{bug-lilypond@@gnu.org}.
882 Bugs that are not fault of LilyPond are documented here.
884 @unnumberedsubsubsec Bison 1.875
886 There is a bug in bison-1.875: compilation fails with "parse error
887 before `goto'" in line 4922 due to a bug in bison. To fix, please
888 recompile bison 1.875 with the following fix
891 $ cd lily; make out/parser.cc
892 $ vi +4919 out/parser.cc
893 # append a semicolon to the line containing "__attribute__ ((__unused__))
899 @unnumberedsubsubsec Compiling on MacOS@tie{}X
901 Here are special instructions for compiling under MacOS@tie{}X.
902 These instructions assume that dependencies are installed using
903 @uref{http://www.macports.org/, MacPorts.} The instructions have
904 been tested using OS X 10.5 (Leopard).
906 First, install the relevant dependencies using MacPorts.
908 Next, add the following to your relevant shell initialization
909 files. This is @code{~/.profile} by default. You should create
910 this file if it does not exist.
913 export PATH=/opt/local/bin:/opt/local/sbin:$PATH
914 export DYLD_FALLBACK_LIBRARY_PATH=/opt/local/lib:$DYLD_FALLBACK_LIBRARY_PATH
917 Now you must edit the generated @code{config.make} file. Change
920 FLEXLEXER_FILE = /usr/include/FlexLexer.h
927 FLEXLEXER_FILE = /opt/local/include/FlexLexer.h
930 At this point, you should verify that you have the appropriate
931 fonts installed with your ghostscript installation. Check @code{ls
932 /opt/local/share/ghostscript/fonts} for: 'c0590*' files (.pfb,
933 .pfb and .afm). If you don't have them, run the following
934 commands to grab them from the ghostscript SVN server and install
935 them in the appropriate location:
938 svn export http://svn.ghostscript.com/ghostscript/tags/urw-fonts-1.0.7pre44/
939 sudo mv urw-fonts-1.0.7pre44/* /opt/local/share/ghostscript/fonts/
940 rm -rf urw-fonts-1.07pre44
943 Now run the @code{./configure} script. To avoid complications with
944 automatic font detection, add
947 --with-ncsb-dir=/opt/local/share/ghostscript/fonts
951 @unnumberedsubsubsec Solaris
953 Solaris7, ./configure
955 @file{./configure} needs a POSIX compliant shell. On Solaris7,
956 @file{/bin/sh} is not yet POSIX compliant, but @file{/bin/ksh} or bash
957 is. Run configure like
960 CONFIG_SHELL=/bin/ksh ksh -c ./configure
967 CONFIG_SHELL=/bin/bash bash -c ./configure
970 @unnumberedsubsubsec FreeBSD
972 To use system fonts, dejaview must be installed. With the default
973 port, the fonts are installed in @file{usr/X11R6/lib/X11/fonts/dejavu}.
975 Open the file @file{$LILYPONDBASE/usr/etc/fonts/local.conf} and add the
976 following line just after the @code{<fontconfig>} line. (Adjust as necessary
980 <dir>/usr/X11R6/lib/X11/fonts</dir>
984 @unnumberedsubsubsec International fonts
986 On Mac OS X, all fonts are installed by default. However, finding all
987 system fonts requires a bit of configuration; see
988 @uref{http://lists.gnu.org/archive/html/lilypond-user/2007-03/msg00472.html,
989 this post} on the @code{lilypond-user} mailing list.
991 On Linux, international fonts are installed by different means on
992 every distribution. We cannot list the exact commands or packages
993 that are necessary, as each distribution is different, and the exact
994 package names within each distribution changes. Here are some
1000 taipeifonts fonts-xorg-truetype ttfonts-ja fonts-arabic \
1001 ttfonts-zh_CN fonts-ja fonts-hebrew
1005 apt-get install emacs-intl-fonts xfonts-intl-.* \
1006 ttf-kochi-gothic ttf-kochi-mincho \
1007 xfonts-bolkhov-75dpi xfonts-cronyx-100dpi xfonts-cronyx-75dpi
1011 @unnumberedsubsubsec Using lilypond python libraries
1013 If you want to use lilypond's python libraries (either running
1014 certain build scripts manually, or using them in other programs),
1015 set @code{PYTHONPATH} to @file{python/out} in your build
1016 directory, or @file{.../usr/lib/lilypond/current/python} in the
1017 installation directory structure.
1022 @node Concurrent stable and development versions
1023 @section Concurrent stable and development versions
1026 It can be useful to have both the stable and the development versions
1027 of Lilypond available at once. One way to do this on GNU/Linux is to
1028 install the stable version using the precompiled binary, and run the
1029 development version from the source tree. After running @command{make
1030 all} from the top directory of the Lilypond source files, there will
1031 be a binary called @code{lilypond} in the @code{out} directory:
1034 <@var{path to}>/lilypond/out/bin/lilypond
1037 This binary can be run without actually doing the @code{make
1038 install} command. The advantage to this is that you can have all
1039 of the latest changes available after pulling from git and running
1040 @code{make all}, without having to uninstall the old version and
1043 So, to use the stable version, install it as usual and use the
1050 To use the development version, create a link to the binary in the
1051 source tree by saving the following line in a file somewhere in your
1055 exec <@var{path to}>/lilypond/out/bin/lilypond "$@@"
1058 Save it as @code{Lilypond} (with a capital L to distinguish it
1059 from the stable @code{lilypond}), and make it executable:
1065 Then you can invoke the development version this way:
1074 - other compilation tricks for developers
1077 @node Using a Virtual Machine to Compile LilyPond
1078 @section Using a Virtual Machine to Compile LilyPond
1081 TODO: rewrite for lily-git.tcl !!! do before GOP! -gp
1083 Since it is not possible to compile Lilypond on Windows, some
1084 developers may find it useful to install a GNU/Linux virtual
1085 machine. A disk image with a special remix of @strong{Ubuntu}
1086 has been created for this purpose. It has all of the Lilypond
1087 build dependencies in place, so that once installed, it is
1088 ready to compile both Lilypond and the Documentation.
1089 The @code{lilybuntu} remix is available for download here:
1092 @uref{http://@/files.lilynet.net/@/lilybuntu.iso}
1095 We do not necessarily recommend any one virtualization tool,
1096 however the @code{lilybuntu} remix is known to work well on
1097 @uref{http://www.virtualbox.org/wiki/Downloads, Sun VirtualBox},
1098 which is a free download. Consult your virtualization software's
1099 documentation for instructions on setting up the software and
1100 for general instructions on installing a virtual machine.
1102 Steps to setting up @code{lilybuntu} in a virtual machine:
1105 @item Download the @code{lilybuntu} disk image.
1107 @item Install @code{lilybuntu}. You will use the @code{.iso}
1108 file as the boot disk. It should not be necessary to burn it
1109 to a DVD, but consult the documentation for your virtualization
1110 software for specific instructions. If possible, use at least
1111 the recommended amount of RAM for the virtual machine (384 MB on
1112 VirtualBox), and use a dynamically expanding virtual hard drive.
1113 A virtual hard drive with 6 GB will be enough to compile LilyPond,
1114 but if you intend to build the docs and run the regression tests
1115 the virtual hard drive should be at least 10 GB.
1116 The Ubuntu installation should be straightforward, although in the
1117 partitioning stage do not be afraid to select @qq{use entire disk,}
1118 since this is only your @strong{virtual disk} and not your
1119 machine's actual hard drive.
1121 @item After installation is complete, restart the virtual
1122 machine. If you are using @strong{VirtualBox}, you may wish
1123 to install the @qq{Guest Additions}, which while not essential for
1124 compiling @code{Lilypond} will allow you to use the virtual machine
1125 in full screen, Seamless mode (also known as Unity mode on other
1126 virtualization platforms) and allow you to share clipboards between
1127 the physical and virtual machine. From the @code{Devices} menu select
1128 @code{Install Guest Additions...}, the @code{VBOXADDITIONS} CDROM device
1129 will appear on the desktop. Open a @strong{terminal} session.
1130 (@code{Applications > Accessories > Terminal}) and @code{cd} to the
1131 top level of the CDROM. Run the @code{autorun.sh} script as superuser
1132 (@code{sudo ./autorun.sh }), a console window will open while the
1133 @qq{Guest Additions} are being installed. Once the script has
1134 been finished, reboot your Virtual Machine to complete the installation
1135 of the @qq{Guest Additions}.
1137 @item Open a @strong{terminal} session.
1138 (@code{Applications > Accessories > Terminal})
1140 @item Open @strong{Firefox} (there's an icon for it on the
1141 panel at the top of the screen) and go to the online Lilypond
1142 @uref{http://lilypond.org/doc/latest/Documentation/contributor/,
1143 Contributor's Guide}.
1145 @item To retrieve the Lilypond source code from @code{git},
1146 copy-and-paste each command from the CG @qq{Main source code}
1147 section into the terminal. (paste into the terminal with keystroke
1148 @code{CTRL+SHIFT+V})
1150 @item Prepare to build Lilypond by running the configuration script.
1157 When it is finished you should be presented
1158 with the three most common @code{make} options:
1162 make all to build LilyPond
1163 make install to install LilyPond
1164 make help to see all possible targets
1166 Edit local.make for local Makefile overrides.
1169 @item First type @code{make all} to build Lilypond. This will take
1172 @item When Lilypond is finished building, build the documentation
1179 Depending on your system specs it could take from 30-60 minutes
1184 At this point everything has been compiled.
1185 You may install Lilypond using @code{make install}, or you may wish
1186 to set up your system with concurrent stable and development
1187 versions as described in the previous section.
1191 @section Build system
1194 We currently use make and stepmake, which is complicated and only
1195 used by us. Hopefully this will change in the future.
1198 @subsubheading Version-specific texinfo macros
1203 made with @command{scripts/build/create-version-itexi.py} and@*
1204 @command{scripts/build/create-weblinks-itexi.py}
1207 used extensively in the @code{WEBSITE_ONLY_BUILD} version of the
1208 website (made with website.make, used on lilypond.org)
1211 not (?) used in the main docs?
1214 the numbers in VERSION file: MINOR_VERSION should be 1 more than
1215 the last release, VERSION_DEVEL should be the last @strong{online}
1216 release. Yes, VERSION_DEVEL is less than VERSION.