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 while not essential for
 117 compiling @code{Lilypond} will allow you to use the virtual machine
 118 in full screen, Seamless mode (also known as Unity mode on other
 119 virtualization platforms) and allow you to share clipboards between
 120 the physical and virtual machine.  From the @code{Devices} menu select
 121 @code{Install Guest Additions...}, the @code{VBOXADDITIONS} CDROM device
 122 will appear on the desktop.  Open a @strong{terminal} session.
 123 (@code{Applications > Accessories > Terminal}) and @code{cd} to the
 124 top level of the CDROM.  Run the @code{autorun.sh} script as superuser
 125 (@code{sudo ./autorun.sh }), a console window will open while the
 126 @qq{Guest Additions} are being installed.  Once the script has
 127 been finished, reboot your Virtual Machine to complete the installation
 128 of the @qq{Guest Additions}.
 129
 130 @item Open a @strong{terminal} session.
 131 (@code{Applications > Accessories > Terminal})
 132
 133 @c FIXME: make sure the url link below doesn't get broken -vv
 134
 135 @item Open @strong{Firefox} (there's an icon for it on the
 136 panel at the top of the screen) and go to the online Lilypond
 137 @uref{http://lilypond.org/doc/latest/Documentation/contributor/,
 138 Contributor's Guide}.
 139
 140 @item To retrieve the Lilypond source code from @code{git},
 141 copy-and-paste each command from the CG @qq{Main source code}
 142 section into the terminal. (paste into the terminal with keystroke
 143 @code{CTRL+SHIFT+V})
 144
 145 @item Prepare to build Lilypond by running the configuration script.
 146 Type
 147
 148 @example
 149 ./autogen.sh
 150 @end example
 151
 152 When it is finished you should be presented
 153 with the three most common @code{make} options:
 154
 155 @example
 156 Type:
 157     make all       to build LilyPond
 158     make install   to install LilyPond
 159     make help      to see all possible targets
 160
 161 Edit local.make for local Makefile overrides.
 162 @end example
 163
 164 @item First type @code{make all} to build Lilypond. This will take
 165 a while.
 166
 167 @item When Lilypond is finished building, build the documentation
 168 by typing
 169
 170 @example
 171 make doc
 172 @end example
 173
 174 Depending on your system specs it could take from 30-60 minutes
 175 to finish.
 176
 177 @end enumerate
 178
 179 At this point everything has been compiled.
 180 You may install Lilypond using @code{make install}, or you may wish
 181 to set up your system with concurrent stable and development
 182 versions as described in the previous section.
 183
 184
 185 @node Build system
 186 @section Build system
 187
 188 We currently use make and stepmake, which is complicated and only
 189 used by us.  Hopefully this will change in the future.
 190
 191
 192 @subsubheading Version-specific texinfo macors
 193
 194 @itemize
 195
 196 @item
 197 made with @command{scripts/build/create-version-itexi.py} and
 198 @command{scripts/build/create-weblinks-itexi.py}
 199
 200 @item
 201 used extensively in the @code{WEBSITE_ONLY_BUILD} version of the
 202 website (made with website.make, used on lilypond.org)
 203
 204 @item
 205 not (?) used in the main docs?
 206
 207 @item
 208 the numbers in VERSION file: MINOR_VERSION should be 1 more than
 209 the last release, VERSION_DEVEL should be the last @strong{online}
 210 release.  Yes, VERSION_DEVEL is less than VERSION.
 211
 212 @end itemize
 213
 214
 215