Documentation/contributor/compiling.itexi

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