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 There is a disk image of a @q{remix} of Ubuntu GNU/Linux available for
21 download which includes all the necessary software and tools to compile
22 both LilyPond and the documentation. Called the
23 @qq{Ubuntu LilyPond Developer Remix}, but known simply as @qq{LilyDev}
24 for short. Although it is not possible to compile LilyPond on Windows
25 and extremely difficult on MacOS, LilyDev can be installed and run
26 inside a @q{virtual machine} on any of these operating systems without
27 disturbing your main operating system. The LilyDev disk image can also
28 be burnt to a DVD and installed like any other Ubuntu GNU/Linux
31 Most virtualization software can be used but we recommend VirtualBox as
32 it is available for all major operating systems and is easy to install
35 If you are not familiar with GNU/Linux, it may be beneficial to read a
36 couple of @qq{introduction to Ubuntu} web pages.
38 For those interested, the LilyDev remix is currently based on a 32bit
39 version of 10.04 LTS Ubuntu (Lucid Lynx).
41 @warning{Apart from installing and configuring LilyDev in VirtualBox,
42 the rest of the chapter assumes that you are comfortable using the
43 command-line. While this chapter is intended for users who may have
44 never created a patch or compiled software before, experienced
45 developers (who prefer to use their own development environment) may
46 still find it instructive to skim over this section.}
49 * Where to get LilyDev::
50 * Installing LilyDev in VirtualBox::
51 * Configuring LilyDev in VirtualBox::
55 @node Where to get LilyDev
56 @unnumberedsubsec Where to get LilyDev
58 Download the Ubuntu LilyPond Developer Remix CD image file
59 (approximately 1 GB) from here:
62 @uref{http://www.philholmes.net/lilypond/LilyDev/ubuntu-LilyDev-remix-2.6.iso}
65 Some advanced users might want this file too:
67 @uref{http://www.philholmes.net/lilypond/LilyDev/ubuntu-LilyDev-remix-2.6.iso.md5}
69 (If you don't recognize what this file is, then you don't need it.)
72 @node Installing LilyDev in VirtualBox
73 @unnumberedsubsec Installing LilyDev in VirtualBox
75 This section discusses how to install and use LilyDev with VirtualBox.
77 @warning{If you already know how to install a virtual machine using a
78 disc image inside VirtualBox (or your own virtualization software) then
79 you can skip this section and go straight to @ref{lily-git}.}
83 Download Virtualbox from here:
86 @uref{http://@/www.virtualbox.org/@/wiki/@/Downloads}
89 @warning{In virtualization terminology, the operating system where
90 Virtualbox is installed is known as the @strong{host}. LilyDev
91 will be installed @q{inside} Virtualbox as a @strong{guest}.}
94 Start the VirtualBox software and click @q{New} to create a new
97 The @q{New Virtual Machine Wizard} will walk you through setting up your
98 guest virtual machine. Choose an appropriate name for your LilyDev
99 installation and select the @q{Linux} operating system. When selecting
100 the @q{version} use @q{Ubuntu} if available (but not the @q{64 bit}
101 option). If you do not have that specific option choose @q{Linux 2.6}
102 (again do not choose any option that has 64 bit next to it).
105 Select the amount of RAM you will allow the LilyDev guest to use from
106 your host operating system when it is running. If possible, use at
107 least 700 MB of RAM; the more RAM you can spare from your host the
108 better, although LilyDev will currently use no more than 4 GB (4096 MB)
109 even if you are able to assign more.
112 For your @q{Virtual Hard Disk}, leave the @q{Create new hard disk}
113 option checked, use the default @q{VDI} and
114 @qq{Dynamically allocated} options for the virtual hard drive. A
115 complete compile of everything (code, docs, regression tests) can reach
116 10 GB so size your virtual disk and its location accordingly.
119 Verify the summary details and click @q{Create}, when you are satisfied.
120 Your new guest will be displayed in the Virtualbox window. Click the
121 @q{Start} button and the @q{First Run Wizard} will prompt you for
122 the installation media. Click the browse icon and locate the LilyDev
123 disk image and click through the wizard to start the installation
127 When the LilyDev disk image boots, it shows a prompt:
130 ISOLINUX @code{boot:}
133 Hit the Return key (or wait 30 seconds) and then when the installer
134 screen loads, using the arrow keys select
135 @q{Install - start the installer directly} to begin the install process
136 of LilyDev on your virtual hard disk. The Ubuntu software will walk you
137 through the complete installation process.
140 At the @qq{Prepare disk space} stage, do not be afraid to select
141 @qq{Erase and use the entire disk}, since this refers to your
142 @strong{@emph{virtual disk}}, not your machine's actual hard
146 Click through the rest of the wizard, filling in any appropriate details
147 when asked and wait for the install to complete.
149 @warning{This will take anywhere from 10 minutes to up to an hour
150 depending on the speed of your computer and if Ubuntu detects you are
151 connected to the internet and needs to download any additional
152 security updates or patches, although these updates are not required to
153 compile LilyPond and it is possible to skip the additional downloads to
154 speed up the install process.}
157 When prompted by the Ubuntu installer wizard, restart the virtual
158 machine and then when prompted to @q{eject the CD} by virtual box, just
159 click inside the virtual machine window and hit the return key to
160 reboot the virtual machine. It will not try to restart the installer
161 but start the virtual machine proper. LilyDev is now installed and
167 Not all hardware is supported in all virtualization tools. In
168 particular, some contributors have reported problems with USB network
169 adapters. If you have problems with network connection (for example
170 Internet connection in the host system is lost when you launch virtual
171 system), try installing and running LilyDev with your computer's
172 built-in network adapter used to connect to the network. Refer to the
173 help documentation that comes with your virtualization software.
176 @node Configuring LilyDev in VirtualBox
177 @unnumberedsubsec Configuring LilyDev in VirtualBox
179 VirtualBox has extra @q{guest additions} which although are not
180 necessary to use LilyDev or compile Lilypond, do provide some additional
181 features to your Virtual Machine to make it easier to work with. Such
182 as being able to dynamically resize the LilyDev window, allow seamless
183 interaction with your mouse pointer on both the host and guest and let
184 you copy/paste between your host and guest if needed.
189 Select the @q{Devices} menu from the virtual machine window and choose
190 @q{Install Guest Additions...}. This will automount a CD which will
191 prompt you to autorun it. Click OK and follow the instructions. It is
192 recommended to reboot the guest when the installation is complete.
194 Other virtualization software will also have their own @q{guest}
195 additions, follow the normal procedures for your virtualization software
196 with Ubuntu as the client.
199 Restart Ubuntu to complete the installation of the guest additions.
201 @advanced{If you do any kernel upgrades, you may need to reinstall
202 the additional software. Just follow the step above again and reboot
203 when the reinstallation is complete.}
208 Other items that may be helpful:
213 In the settings for the virtual machine, set the network to
214 Bridged mode to allow you to access shared folders when using Windows
218 Set up any additional features, such as @q{Shared Folders} between
219 your main operating system and Ubuntu. This is distinct from the
220 networked share folders in Windows. Consult the external
221 documentation for this.
223 Some longtime contributors have reported that @q{shared folders}
224 are rarely useful and not worth the fuss, particularly since files
225 can be shared over a network instead.
228 Pasting into a terminal is done with @code{Ctrl+Shift+v}.
231 The @qq{Places} top-menu has shortcuts to a graphical
232 @qq{navigator} like Windows Explorer or the MacOS X Finder.
235 Right-click allows you to edit a file with gedit. We recommend
239 One particular change from Windows and MacOS X is that most
240 software should be installed with your @qq{package manager}; this
241 vastly simplifies the process of installing and configuring
242 software. Go to @clicksequence{Applications @click{} Ubuntu
251 The @q{LilyPond Contributor's Git Interface} (otherwise known as
252 @command{lily-git.tcl}) is a simple-to-use GUI to help you download and
253 update the LilyPond source code as well as an aid to making software
257 * Where to get lily-git::
258 * Configuring lily-git and downloading the source code::
259 * How to use lily-git::
262 @node Where to get lily-git
263 @unnumberedsubsec Where to get lily-git
265 Depending on your development environment, lily-git may already be
266 installed on your computer.
270 If you are using LilyDev (see @ref{LilyDev}) then lily-git is already
271 installed and ready to run.
274 For those not using LilyDev then lily-git can be obtained by downloading
275 the software directly. See @ref{Manually installing lily-git.tcl}.
278 Finally, lily-git is always part of the LilyPond source code and is
279 located in @file{$LILYPOND_GIT/scripts/auxillar/lily-git.tcl}.
284 @node Configuring lily-git and downloading the source code
285 @unnumberedsubsec Configuring lily-git and downloading the source code
287 @warning{The rest of this manual assumes that you are using the
288 command-line within a terminal.}
292 Type (or copy&paste) into the Terminal:
299 You will be prompted to enter your name and your email address. This
300 information is used only to identify and label any patches you create.
301 This information can be edited if required later. See
302 @ref{Configuring Git}. Click on the @emph{Submit} button to update
303 lily-git with this information.
306 Click on the @qq{Get source} button.
308 A directory called @file{$LILYPOND_GIT} is now created within
309 your home directory and the complete source code will start to be
312 @warning{Be patient! The complete source is around 150@tie{}Mb.}
315 When the source code has been downloaded, the @qq{Command output} window
316 in lily-git will update and display @qq{Done} on the very last line.
317 The button label will change to say @qq{Update source}.
319 @warning{Some contributors have reported that occasionally nothing
320 happens at this step at all. If this occurs, then try again in a few
321 minutes -- it could be an intermittant network problem. If the
322 problem persists, please ask for help.}
325 Close the lily-git GUI and navigate to the @file{$LILYPOND_GIT}
326 directory to view and edit the source files.
331 If this is the first time you have compiled LilyPond then please go
332 to @ref{Compiling with LilyDev} before reading on.
335 @node How to use lily-git
336 @unnumberedsubsec How to use lily-git
338 @warning{Throughout the rest of this manual, most command-line
339 input should be entered from @file{~/lilypond-git/}. This is
340 known as the @emph{top source directory} and is often referred to as
341 @var{$LILYPOND_GIT}.}
343 @warning{Only work on one set of changes at once. Do not start
344 work on any new changes until your first set has been accepted.}
346 @subsubheading 1. Update source
348 At the beginning of each session of lilypond work, you should
349 click the @qq{Update source} button to get the latest changes to
352 @warning{In some rare and unfortunate circumstances, this will
353 result in a @emph{merge conflict}. If this occurs, follow the
354 instructions for @qq{Abort changes}, below. Your work will not be
358 @subsubheading 2a. New local commit
360 A single commit typically represents one logical set of related
361 changes (such as a bug-fix), and may incorporate changes to
362 multiple files at the same time.
364 When you're finished making the changes for a commit, click the
365 @qq{New local commit} button. This will open the @qq{Git Commit
366 Message} window. The message header is required, and the message
369 After entering a commit message, click @qq{OK} to finalize the
372 @advanced{for more information regarding commits and commit
373 messages, see @ref{Commits and patches}.}
376 @subsubheading 2b. Amend previous commit
378 You can go back and make changes to the most recent commit with
379 the @qq{Amend previous commit} button. This is useful if a
380 mistake is found after you have clicked the @qq{New local commit}
383 To amend the most recent commit, re-edit the source files as
384 needed and then click the @qq{Amend previous commit} button. The
385 earlier version of the commit is not saved, but is replaced by the
388 @warning{This does not update the patch @strong{files}; if you
389 have a patch file from an earlier version of the commit, you will
390 need to make another patch set when using this feature. The old
391 patch file will not be saved, but will be replaced by the new one
392 after you click on @qq{Make patch set}.}
395 @subsubheading 3. Make patch set
397 Before making a patch set from any commits, you should click the
398 @qq{Update source} button to make sure the commits are based on
399 the most recent remote snapshot.
401 When you click the @qq{Make patch set} button,
402 @command{lily-git.tcl} will produce patch files for any new
403 commits, saving them to the current directory. The command output
404 will display the name of the new patch files near the end of the
408 0001-CG-add-lily-git-instructions.patch
412 Send patch files to the appropriate place:
416 If you have a mentor, send it to them via email.
419 Translators should send patches to
420 @email{translations@@lilynet.net}.
423 More experienced contributors should upload the patch for
424 web-based review. This requires additional software and use of
425 the command-line; see @ref{Uploading a patch for review}.
428 If you have trouble uploading the patch for review,
429 ask for help on @email{lilypond-devel@@gnu.org}.
434 @subsubheading The @qq{Abort changes -- Reset to origin} button
436 @warning{Only use this if your local commit history gets
437 hopelessly confused!}
439 The button labeled @qq{Abort changes -- Reset to origin} will copy
440 all changed files to a subdirectory of @file{$LILYPOND_GIT} named
441 @file{aborted_edits/}, and will reset the repository to the
442 current state of the remote repository (at @code{git.sv.gnu.org}).
446 @node Compiling with LilyDev
447 @section Compiling with LilyDev
449 LilyDev is our @q{remix} of Ubuntu which contains all the
450 necessary dependencies to do lilypond development; for more
451 information, see @rcontrib{LilyDev}.
453 @subsubheading Preparing the build
455 To prepare the build directory, enter (or copy&paste) the below
456 text. This should take less than a minute.
458 @c we heavily recommend the out-of-tree build; do not change this!
462 sh autogen.sh --noconfigure
468 @subsubheading Building @code{lilypond}
470 Compiling lilypond will likely take between 5 and 60 minutes,
471 depending on your computer's speed and available RAM. We
472 recommend that you minimize the terminal window while it is
473 building; this can have a non-negligible effect on compilation
477 cd $LILYPOND_GIT/build/
481 You may run the compiled @code{lilypond} with:
484 cd $LILYPOND_GIT/build/
485 out/bin/lilypond my-file.ly
488 @subsubheading Building the documentation
490 Compiling the documentation is a much more involved process, and
491 will likely take 2 to 10 hours.
494 cd $LILYPOND_GIT/build/
499 The documentation is put in @file{out-www/offline-root/}. You may
500 view the html files by entering the below text; we recommend that
501 you bookmark the resulting page:
504 firefox $LILYPOND_GIT/build/out-www/offline-root/index.html
507 @subsubheading Installing
509 Don't. There is no reason to install lilypond within LilyDev.
510 All development work can (and should) stay within the
511 @file{$LILYPOND_GIT} directory, and any personal composition
512 or typesetting work should be done with an official GUB release.
515 @subsubheading Problems and other options
517 To select different build options, or isolate certain parts of the
518 build, or to use multiple CPUs while building, read
521 In particular, contributors working on the documentation should be
522 aware of some bugs in the build system, and should read the
523 workarounds in @ref{Generating documentation}.
526 @node Now start work!
527 @section Now start work!
529 LilyDev users may now skip to the chapter which is aimed at
530 their intended contributions:
533 @item @ref{Documentation work}
534 @item @ref{Translating the documentation}
535 @item @ref{Website work}
536 @item @ref{Regression tests}
537 @item @ref{Programming work}
540 These chapters are mainly intended for people not using LilyDev,
541 but they contain extra information about the
542 @qq{behind-the-scenes} activities. We recommend that you read
543 these at your leisure, a few weeks after beginning work with
547 @item @ref{Working with source code}
548 @item @ref{Compiling}