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