1 @c -*- coding: utf-8; mode: texinfo; -*-
6 Want to submit a patch for LilyPond? Great! Never created a patch
7 before? Never compiled software before? No problem! This chapter is
8 for you and will help you do this as quickly and easily as possible.
13 * Compiling with LilyDev::
20 @c This text was written based on LilyDev 4.0 - JL
22 There is a @q{remix} of Debian GNU/Linux -- known as @qq{LilyDev} for
23 short -- which includes all the necessary software and tools to compile
24 LilyPond, the documentation and the website (also see
27 @warning{LilyDev does not include the software for the Grand Unified
28 Builder -- also see @ref{Grand Unified Builder (GUB)}.}
30 While compiling LilyPond on MacOs and Windows is possible, both
31 environments are complex to set up. LilyDev can be easily installed
32 and run inside a @q{virtual machine} on either of these operating
33 systems relatively easily using readily available virtualization
34 software. We recommend using VirtualBox as it is available for all
35 major operating systems and is very easy to install & configure.
37 The LilyDev disk image can also be written to a USB device or @q{burnt}
38 to a DVD -- it is approximately 900 GB in size -- and installed just
39 like any standard GNU/Linux distribution.
41 The current image is based on a 32bit version of Debian 8 (@q{Jessie})
42 and the Disk image was generated using Debian
43 @uref{http://live.debian.net/, live-build 4}.
46 Download the LilyDev disk image file from here:
49 @uref{https://github.com/fedelibre/LilyDev/releases/latest}
52 @warning{Apart from installing and configuring LilyDev in VirtualBox,
53 the rest of the chapter assumes that you are comfortable using the
54 command-line and is intended for users who may have never created a
55 patch or compiled software before. More experienced developers (who
56 prefer to use their own development environment) may still find it
57 instructive to skim over the following information.}
59 If you are not familiar with GNU/Linux, it may be beneficial to read a
60 a few @qq{introduction to Linux} type web pages.
63 * Installing LilyDev in VirtualBox::
64 * Configuring LilyDev in VirtualBox::
68 @node Installing LilyDev in VirtualBox
69 @unnumberedsubsec Installing LilyDev in VirtualBox
71 This section discusses how to install and use LilyDev with VirtualBox.
73 @warning{If you already know how to install a virtual machine using a
74 disc image inside VirtualBox (or your own virtualization software) then
75 you can skip this section and go straight to @ref{lily-git}.}
79 Download Virtualbox from here:
82 @uref{http://www.virtualbox.org/wiki/Downloads}
85 @warning{In virtualization terminology, the operating system where
86 Virtualbox is installed is known as the @strong{host}. LilyDev
87 will be installed @q{inside} Virtualbox as a @strong{guest}.}
90 Start the VirtualBox software and click @q{New} to create a new
93 The @q{New Virtual Machine Wizard} will walk you through setting up your
94 guest virtual machine. Choose an appropriate name for your LilyDev
95 installation and select the @q{Linux} operating system. When selecting
96 the @q{version} choose @q{Debian (32 bit)} (don't use the @q{64 bit}
97 option). If you do not have that specific option choose @q{Linux 2.6}
98 (again do not choose any option that has 64 bit next to it).
101 Select the amount of RAM you will allow the LilyDev guest to use from
102 your host operating system when it is running. If possible, use at
103 least 700 MB of RAM; the more RAM you can spare from your host the
104 better, although LilyDev will currently use no more than 4 GB (4096 MB)
105 even if you are able to assign more.
108 For your @q{Virtual Hard Disk}, leave the @q{Create new hard disk}
109 option checked, use the default @q{VDI} and @qq{Dynamically allocated}
110 options for the virtual hard drive. A complete compile of everything
111 (code, docs, regression tests) can reach 10 GB so size your virtual disk
112 and its location accordingly.
115 Verify the summary details and click @q{Create}, when you are satisfied.
116 Your new guest will be displayed in the Virtualbox window.
118 @warning{The image contains a @q{686-pae} kernel, so you must enable
119 @code{PAE} within the virtual machine's settings -- click on
120 @clicksequence{System @click{} Processor} and select
121 @q{Extended features: Enable PAE/NX}.}
124 Click the @q{Start} button and the @q{First Run Wizard} will prompt you
125 for the installation media. Click the browse icon, locate the LilyDev
126 disk image and click through the wizard to begin the installation
130 When the LilyDev disk image boots for the first time, choose either the
131 @q{Install} or the @q{Graphical install} menu item. The installer will
132 then walk you through the complete installation process.
135 At the @qq{Partition disks} stage, do not be afraid to select
136 @qq{Guided - use entire disk}, since this refers to your
137 @strong{@emph{virtual disk}}, not your computer's own hard disk.
140 Continue to click through the rest of the wizard, filling in any
141 appropriate details when asked, and wait for the install to complete.
142 This will take about 10 minutes or so on a reasonably modern computer.
145 When the installation is completed, just click on @q{Continue} (you
146 do not have to remove any media since you installed LilyDev from a Disk
147 image, which is just a file on your computer). The installer will
148 reboot the virtual machine.
153 LilyDev should now be installed and running!
156 @node Configuring LilyDev in VirtualBox
157 @unnumberedsubsec Configuring LilyDev in VirtualBox
159 VirtualBox has extra @q{guest additions} which although are not
160 necessary to use LilyDev or compile Lilypond, do provide some additional
161 features to your Virtual Machine to make it easier to work with. Such
162 as being able to dynamically resize the LilyDev window, allow seamless
163 interaction with your mouse pointer on both the host and guest and let
164 you copy/paste between your host and guest if needed.
169 Select the @q{Devices} menu from the virtual machine window and choose
170 @q{Install Guest Additions...}. This will automount a CD which will
171 prompt you to autorun it. Click OK and follow the instructions. It is
172 recommended to reboot the guest when the installation is complete.
174 Other virtualization software will also have their own @q{guest}
175 additions, follow the normal procedures for your virtualization software
176 with LilyDev as the client.
179 Restart LilyDev to complete the installation of the guest additions.
181 @advanced{If you do any kernel upgrades, you may need to reinstall the
182 additional software. Just follow the step above again and reboot when
183 the reinstallation is complete.}
188 Other items that may be helpful:
193 In the settings for the virtual machine, set the network to
194 Bridged mode to allow you to access shared folders when using Windows
198 Set up any additional features, such as @q{Shared Folders} between
199 your main operating system and LilyDev. This is distinct from the
200 networked share folders in Windows. Consult the external documentation
203 Some longtime contributors have reported that @q{shared folders}
204 are rarely useful and not worth the fuss, particularly since files
205 can be shared over a network instead.
208 Pasting into a terminal is done with @code{Ctrl+Shift+v}.
211 Right-click allows you to edit a file with the text editor (default
217 Not all hardware is supported in all virtualization tools. In
218 particular, some contributors have reported problems with USB network
219 adapters. If you have problems with network connection (for example
220 Internet connection in the host system is lost when you launch virtual
221 system), try installing and running LilyDev with your computer's
222 built-in network adapter used to connect to the network. Refer to the
223 help documentation that comes with your virtualization software.
229 The @q{LilyPond Contributor's Git Interface} (otherwise known as
230 @command{lily-git.tcl}) is a simple-to-use GUI to help you download and
231 update the LilyPond source code as well as an aid to making software
235 * Where to get lily-git::
236 * Using lily-git to download the source code::
237 * How to use lily-git::
240 @node Where to get lily-git
241 @unnumberedsubsec Where to get lily-git
243 Depending on your development environment, lily-git may already be
244 installed on your computer.
248 If you are using LilyDev (see @ref{LilyDev}) then lily-git should
249 already be installed and ready to run. If this is not the case you can
250 easily turn it on by adding the following line in @code{~/.bashrc}:
253 # add lily-git to the PATH
254 PATH=$LILYPOND_GIT/scripts/auxiliar:"$@{PATH@}"
258 For those not using LilyDev, lily-git can be obtained by downloading
259 the software directly. See @ref{Manually installing lily-git.tcl}.
262 lily-git is part of the LilyPond source code and is located in
263 @file{$LILYPOND_GIT/scripts/auxillar/lily-git.tcl}.
268 @node Using lily-git to download the source code
269 @unnumberedsubsec Using lily-git to download the source code
273 Type the following command into a Terminal:
280 You will be prompted to enter a name and email address into the lily-git
281 UI. This information is used to label any patches you create (using the
282 lily-git UI or git via the command line) and can be changed later if
283 required. See @ref{Configuring Git}.
286 Click on the @emph{Submit} button to update lily-git with the
290 Click on the @qq{Get source} button.
292 A directory called @file{lilypond-git} is created within your home
293 directory and the entire source code will start to be downloaded into
296 @warning{Be patient! There is no progress bar in the lily-git UI but the
297 complete source is around 180@tie{}Mb.}
300 When the source code has been downloaded, the @qq{command output} window
301 in the lily-git UI will update and display @qq{Done} on the very last
302 line and the button label will change to say @qq{Update source}.
304 @warning{Some contributors have reported that occasionally nothing
305 happens at this step at all. If this occurs, then try again in a few
306 minutes -- it could be an intermittant network problem. If the
307 problem persists, please ask for help.}
310 Close the lily-git GUI and navigate to the @file{lilypond-git}
311 directory to view and edit the source files.
316 If this is the first time you will be attempting to compile LilyPond,
317 please see the section @ref{Compiling with LilyDev} before continuing.
320 @node How to use lily-git
321 @unnumberedsubsec How to use lily-git
323 Here is a brief description of what each button does in the lily-git UI.
325 @advanced{Throughout the rest of this manual, most command-line
326 input should be entered from within the top level of the
327 @file{~/lilypond-git/} directory. This is known as the
328 @emph{top of the source directory} and is also referred to as
329 @var{$LILYPOND_GIT} as a convention for those users who may have
330 configured their own locations of the LilyPond source code.}
332 @warning{For those less experienced contributors using lily-git, we
333 recommend that you only work on one set of changes at a time and not
334 start on any new changes until your first set has been accepted.}
336 @subsubheading 1. Update source
338 Click the @qq{Update source} button to get any recent changes to the
339 source code that have been added by other contributors since your last
342 @warning{If another contributor has updated files in the source code
343 that you had been working on then updating your own copy of the source
344 code may result in what is known as a @emph{merge conflict}. If this
345 occurs, follow the instructions to @qq{Abort changes}, below. Note that
346 your work will not be lost.}
349 @subsubheading 2a. New local commit
351 A single commit typically represents one logical set of related
352 changes (such as a bug-fix), and may incorporate changes to
353 multiple files at the same time.
355 When you're finished making the changes for a commit, click the
356 @qq{New local commit} button. This will open the @qq{Git Commit
357 Message} window. The message header is required, and the message
360 After entering a commit message, click @qq{OK} to finalize the
363 @advanced{for more information regarding commits and commit
364 messages, see @ref{Commits and patches}.}
367 @subsubheading 2b. Amend previous commit
369 You can go back and make changes to the most recent commit with
370 the @qq{Amend previous commit} button. This is useful if a
371 mistake is found after you have clicked the @qq{New local commit}
374 To amend the most recent commit, re-edit the source files as
375 needed and then click the @qq{Amend previous commit} button. The
376 earlier version of the commit is not saved, but is replaced by the
379 @warning{This does not update the patch @strong{files}; if you
380 have a patch file from an earlier version of the commit, you will
381 need to make another patch set when using this feature. The old
382 patch file will not be saved, but will be replaced by the new one
383 after you click on @qq{Make patch set}.}
386 @subsubheading 3. Make patch set
388 Before making a patch set from any commits, you should click the
389 @qq{Update source} button to make sure the commits are based on
390 the most recent remote snapshot.
392 When you click the @qq{Make patch set} button,
393 @command{lily-git.tcl} will produce patch files for any new
394 commits, saving them to the current directory. The command output
395 will display the name of the new patch files near the end of the
399 0001-CG-add-lily-git-instructions.patch
403 Send patch files to the appropriate place:
407 If you have a mentor, send it to them via email.
410 Translators should send patches to
411 @email{translations@@lilynet.net}.
414 More experienced contributors should upload the patch for
415 web-based review. This requires additional software and use of
416 the command-line; see @ref{Uploading a patch for review}.
419 If you have trouble uploading the patch for review,
420 ask for help on @email{lilypond-devel@@gnu.org}.
425 @subsubheading The @qq{Abort changes -- Reset to origin} button
427 @warning{Only use this if your local commit history gets
428 hopelessly confused!}
430 The button labeled @qq{Abort changes -- Reset to origin} will copy
431 all changed files to a subdirectory of @file{$LILYPOND_GIT} named
432 @file{aborted_edits/}, and will reset the repository to the
433 current state of the remote repository (at @code{git.sv.gnu.org}).
437 @node Compiling with LilyDev
438 @section Compiling with LilyDev
440 LilyDev is our @q{remix} of Debian which contains all the
441 necessary dependencies to do lilypond development; for more
442 information, see @ref{LilyDev}.
444 @subsubheading Preparing the build
446 To prepare the build directory, enter (or copy&paste) the below
447 text. This should take less than a minute.
449 @c we heavily recommend the out-of-tree build; do not change this!
453 sh autogen.sh --noconfigure
459 @subsubheading Building @code{lilypond}
461 Compiling lilypond will likely take between 5 and 60 minutes,
462 depending on your computer's speed and available RAM. We
463 recommend that you minimize the terminal window while it is
464 building; this can have a non-negligible effect on compilation
468 cd $LILYPOND_GIT/build/
472 You may run the compiled @code{lilypond} with:
475 cd $LILYPOND_GIT/build/
476 out/bin/lilypond my-file.ly
479 @subsubheading Building the documentation
481 Compiling the documentation is a much more involved process, and
482 will likely take 2 to 10 hours.
485 cd $LILYPOND_GIT/build/
490 The documentation is put in @file{out-www/offline-root/}. You may
491 view the html files by entering the below text; we recommend that
492 you bookmark the resulting page:
495 firefox $LILYPOND_GIT/build/out-www/offline-root/index.html
498 @subsubheading Installing
500 Don't. There is no reason to install lilypond within LilyDev.
501 All development work can (and should) stay within the
502 @file{$LILYPOND_GIT} directory, and any personal composition
503 or typesetting work should be done with an official GUB release.
506 @subsubheading Problems and other options
508 To select different build options, or isolate certain parts of the
509 build, or to use multiple CPUs while building, read
512 In particular, contributors working on the documentation should be
513 aware of some bugs in the build system, and should read the
514 workarounds in @ref{Generating documentation}.
517 @node Now start work!
518 @section Now start work!
520 LilyDev users may now skip to the chapter which is aimed at
521 their intended contributions:
524 @item @ref{Documentation work}
525 @item @ref{Translating the documentation}
526 @item @ref{Website work}
527 @item @ref{Regression tests}
528 @item @ref{Programming work}
531 These chapters are mainly intended for people not using LilyDev,
532 but they contain extra information about the
533 @qq{behind-the-scenes} activities. We recommend that you read
534 these at your leisure, a few weeks after beginning work with
538 @item @ref{Working with source code}
539 @item @ref{Compiling}