Documentation/contributor/compiling.itexi

   1 @c -*- coding: us-ascii; mode: texinfo; -*-
   2
   3 @node Compiling LilyPond
   4 @chapter Compiling LilyPond
   5
   6 @menu
   7 * Compiling from source::
   8 * Concurrent Stable and Development Versions::
   9 * Using a Virtual Machine to Compile Lilypond::
  10 @end menu
  11
  12 @node Compiling from source
  13 @section Compiling from source
  14
  15 TODO  (see AU 1 for now)
  16 @c currently broken; will fix after 2.14
  17 @c @include compile.itely
  18
  19
  20 @node Concurrent Stable and Development Versions
  21 @section Concurrent Stable and Development Versions
  22
  23 It can be useful to have both the stable and the development versions
  24 of Lilypond available at once. One way to do this on GNU/Linux is to
  25 install the stable version using the precompiled binary, and run the
  26 development version from the source tree. After running @command{make
  27 all} from the top directory of the Lilypond source files, there will
  28 be a binary called @code{lilypond} in the @code{out} directory:
  29
  30 @example
  31 <@var{path to}>/lilypond/out/bin/lilypond
  32 @end example
  33
  34 This binary can be run without actually doing the @code{make
  35 install} command. The advantage to this is that you can have all
  36 of the latest changes available after pulling from git and running
  37 @code{make all}, without having to uninstall the old version and
  38 reinstall the new.
  39
  40 So, to use the stable version, install it as usual and use the
  41 normal commands:
  42
  43 @example
  44 lilypond foobar.ly
  45 @end example
  46
  47 To use the development version, create a link to the binary in the
  48 source tree by saving the following line in a file somewhere in your
  49 @code{$PATH}:
  50
  51 @example
  52 exec <@var{path to}>/lilypond/out/bin/lilypond "$@@"
  53 @end example
  54
  55 Save it as @code{Lilypond} (with a capital L to distinguish it
  56 from the stable @code{lilypond}), and make it executable:
  57
  58 @example
  59 chmod +x Lilypond
  60 @end example
  61
  62 Then you can invoke the development version this way:
  63
  64 @example
  65 Lilypond foobar.ly
  66 @end example
  67
  68
  69 TODO: ADD
  70
  71 - other compilation tricks for developers
  72
  73
  74 @node Using a Virtual Machine to Compile Lilypond
  75 @section Using a Virtual Machine to Compile Lilypond
  76
  77 Since it is not possible to compile Lilypond on Windows, some
  78 developers may find it useful to install a GNU/Linux virtual
  79 machine. A disk image with a special remix of @strong{Ubuntu}
  80 has been created for this purpose. It has all of the Lilypond
  81 build dependencies in place, so that once installed, it is
  82 ready to compile both Lilypond and the Documentation.
  83 The @code{lilybuntu} remix is available for download here:
  84
  85 @example
  86 @uref{http://@/prodet.hu/@/bert/@/lilydev/@/lilybuntu.iso}
  87 @end example
  88
  89 We do not necessarily recommend any one virtualization tool,
  90 however the @code{lilybuntu} remix is known to work well on
  91 @uref{http://www.virtualbox.org/wiki/Downloads, Sun VirtualBox},
  92 which is a free download. Consult your virtualization software's
  93 documentation for instructions on setting up the software and
  94 for general instructions on installing a virtual machine.
  95
  96 Steps to setting up @code{lilybuntu} in a virtual machine:
  97
  98 @enumerate
  99 @item Download the @code{lilybuntu} disk image.
 100
 101 @item Install @code{lilybuntu}. You will use the @code{.iso}
 102 file as the boot disk. It should not be necessary to burn it
 103 to a DVD, but consult the documentation for your virtualization
 104 software for specific instructions. If possible, use at least
 105 the recommended amount of RAM for the virtual machine (384 MB on
 106 VirtualBox), and use a dynamically expanding virtual hard drive
 107 starting with at least 5-6 GB of space, more if you can spare it.
 108 The Ubuntu installer should be straightforward, although in the
 109 partitioning stage do not be afraid to select @qq{use entire disk,}
 110 since this is only your @strong{virtual disk} and not your
 111 machine's actual hard drive.
 112
 113 @item After installation is complete, restart the virtual
 114 machine. (If you are using @strong{VirtualBox}, you may wish
 115 to install the @qq{Guest Additions,} which will allow you to
 116 use the virtual machine in full screen.)
 117
 118 @item Open a @strong{terminal}.
 119 (@code{Applications > Accessories > Terminal})
 120
 121 @item Open @strong{Firefox} (there's an icon for it on the
 122 panel at the top of the screen) and go to the online Lilypond
 123 @uref{http://lilypond.org/doc/v2.13/Documentation/devel/contrib-guide, Contributor's Guide}.
 124
 125 @item To retrieve the Lilypond source code from @code{git},
 126 copy-and-paste each command from the CG @qq{Main source code}
 127 section into the terminal. (paste into the terminal with keystroke
 128 @code{CTRL+SHIFT+V})
 129
 130 @item Prepare to build Lilypond by running the configuration script.
 131 Type
 132
 133 @example
 134 ./autogen.sh
 135 @end example
 136
 137 When it is finished you should be presented
 138 with the three most common @code{make} options:
 139
 140 @example
 141 Type:
 142     make all       to build LilyPond
 143     make install   to install LilyPond
 144     make help      to see all possible targets
 145
 146 Edit local.make for local Makefile overrides.
 147 @end example
 148
 149 @item First type @code{make all} to build Lilypond. This will take
 150 a while.
 151
 152 @item When Lilypond is finished building, build the documentation
 153 by typing
 154
 155 @example
 156 make doc
 157 @end example
 158
 159 Depending on your system specs it could take from 30-60 minutes
 160 to finish.
 161
 162 @end enumerate
 163
 164 At this point everything has been compiled.
 165 You may install Lilypond using @code{make install}, or you may wish
 166 to set up your system with concurrent stable and development
 167 versions as described in the previous section.