1 @c -*- coding: utf-8; mode: texinfo; -*-
6 Want to submit a patch for LilyPond? Great! This chapter is
7 designed to let you do this as quickly and easily as possible.
9 It is not possible to compile LilyPond on Windows, and extremely
10 difficulty to compile it on MacOS X. We have therefore made a
11 @q{remix} of Ubuntu which includes all necessary dependencies to
12 compile both LilyPond and the documentation. This can be run
13 inside a virtual machine without disturbing your main operating
14 system. The full name is @qq{Ubuntu LilyPond Developer Remix},
15 but we refer to it as @qq{lilydev} for short.
17 @advanced{experienced developers may prefer to use their own
18 development environment. It may be instructive to skim over these
19 instructions, but be aware that this chapter is intended for
20 helpful users who may have never created a patch before.}
25 * Compiling with lilydev::
35 * Installing lilydev::
36 * Configuring lilydev in virtualbox::
40 @node Installing lilydev
41 @subsection Installing lilydev
45 Install some virtualization software.
47 Any virtualization tool can be used, but we recommend VirtualBox:
50 @uref{http://@/www.virtualbox.org/@/wiki/@/Downloads}
53 In virtualization terminology, your main operating system is the
54 @qq{host}, while lilydev is the @qq{guest}.
57 Download the Ubuntu LilyPond Developer Remix disk image:
61 @uref{http://files.lilynet.net/ubuntu-lilydev-remix-1.0.iso}
64 @advanced{Some users might want these files, but if you don't
65 recognize what they are, then you don't want them:
66 @uref{http://files.lilynet.net/ubuntu-lilydev-remix-1.0.iso.md5}
67 @uref{http://files.lilynet.net/ubuntu-lilydev-remix-1.0.iso.torrent}
71 Create a new @qq{virtual machine} inside your virtualization
74 If possible, use at least 700 MB of RAM (1GB would be better) for
75 the virtual machine, and use @qq{dynamically expanding storage}
76 for the virtual hard drive. A complete compile of everything
77 (code, docs, regression tests) can reach 10 GB.
80 Install @file{lilydev2.iso} as the @qq{guest} operating system
81 on your virtualized system.
86 When @file{lilydev2.iso} boots, it shows an ISOLINUX
87 @code{boot:} prompt. Type:
94 At the @qq{Prepare disk space} stage, do not be afraid to select
95 @qq{Erase and use the entire disk}, since this refers to your
96 @emph{virtual disk}, not your machine's actual hard drive.
99 When prompted to remove the installation CD, go to
100 @clicksequence{Devices @click{} CD/DVD Devices} and de-select
106 The latest version of lilydev is based on Ubuntu 10.04.1; if you
107 encounter any difficulties installing it, search for one of the
108 many tutorials for installing that particular version of Ubuntu as
109 a guest operating system.
113 Do any extra configuration for your virtualization software.
115 There are additional instructions for VirtualBox in
116 @ref{Configuring lilydev in virtualbox}.
118 If you use other virtualization software, then follow the normal
119 procedures for your virtualization software with Ubuntu as the
126 Not all hardware is supported in all virtualization tools. In
127 particular, some contributors have reported problems with USB
128 devices. If you would like to investigate further, then look for
129 help for your virtualization tool using your normal OS as the
130 @qq{host} and Ubuntu as the @qq{client}.
133 @node Configuring lilydev in virtualbox
134 @subsection Configuring lilydev in virtualbox
136 VirtualBox has extra @qq{guest additions} which can make the
137 virtualization easier to use (full-screen, easy file sharing
138 between host and guest operating systems, shared clipboards, etc).
143 In @emph{VirtualBox}, select @clicksequence{Devices @click{}
144 Install Guest Additions...}.
147 In @emph{Ubuntu}, select @clicksequence{Places @click{}
148 VBOXADDITIONS_}. A file-system window will open.
151 Double-click on the @file{autorun.sh} file, then select @qq{Run in
152 Terminal}, and enter your password when prompted.
155 Once the script is finished, @qq{eject} the virtual CD, and then
156 go to @clicksequence{Devices @click{} CD/DVD Devices} and
157 de-select @file{VBoxGuestAdditions.iso}.
160 Restart Ubuntu to complete the installation.
162 @advanced{If you do any kernel upgrades, you may need to re-run
163 these VBOXADDITIONS instructions.}
166 Some other steps may be helpful:
170 In the settings for the virtual machine, set the network to
171 Bridged mode to allow you to access shared folders on your Windows
175 Set up any additional features, such as @q{Shared Folders} between
176 your main operating system and ubuntu. This is distinct from the
177 networked share folders in Windows. Consult external
178 documentation for this step.
180 Some longtime contributors have reported that @q{shared folders}
181 are rarely useful and not worth the fuss, particularly since files
182 can be shared over a network instead.
188 @subsection Using lilydev
190 If you are not familiar with Linux, it may be beneficial to read a
191 couple of @qq{introduction to Ubuntu} webpages.
195 One particular change from Windows and MacOS X is that most
196 software should be installed with your @qq{package manager}; this
197 vastly simplifies the process of installing and configuring
198 software. Go to @clicksequence{Applications @click{} Ubuntu
202 The rest of this manual assumes that you are using the
203 command-line; double-click on the @q{Terminal} icon on the
207 Pasting into a terminal is done with @code{Ctrl+Shift+v}.
210 The @qq{Places} top-menu has shortcuts to a graphical
211 @qq{navigator} like Windows Explorer or the MacOS X Finder.
214 Right-click allows you to edit a file with gedit. We recommend
218 Some contributors have recommended: (pdf available for free)
221 @uref{http://www.ubuntupocketguide.com/}
228 @section Using lily-git
230 @command{lily-git.tcl} is a graphical tool to help you access and
231 share changes to the lilypond source code.
234 * Install and configuration of lily-git.tcl::
235 * Daily use of lily-git.tcl::
238 @node Install and configuration of lily-git.tcl
239 @unnumberedsubsec Install and configuration of @command{lily-git.tcl}
241 @warning{The rest of this manual assumes that you are using the
242 command-line; double-click on the @q{Terminal} icon on the
247 Type (or copy&paste) into the Terminal:
254 Click on the @qq{Get source} button.
256 This will create a directory called @file{lilypond-git/} within
257 your home directory, and will download the source code into that
258 directory (around 55Mb). When the process is finished, the
259 @qq{Command output} window will display @qq{Done}, and the button
260 label will change to say @qq{Update source}.
263 Navigate to the @file{lilypond-git/} directory to view the source
268 You should now progress to @ref{Compiling with lilydev}.
270 @warning{Throughout the rest of this manual, most command-line
271 input should be entered from @file{~/lilypond-git/}. This is
272 referred to as the @emph{top source directory}.}
274 @advanced{the @qq{Get source} button does not fetch the entire
275 history of the git repository, so utilities like @command{gitk}
276 will only be able to display the most recent additions. As you
277 continue to work with @command{lily-git.tcl}, the @qq{Update
278 source} button will take any new additions and add it to whatever
279 is currently in your repository's history.}
282 @node Daily use of lily-git.tcl
283 @unnumberedsubsec Daily use of @command{lily-git.tcl}
285 @warning{Only work on one set of changes at once. Do not start
286 work on any new changes until your first set has been accepted.}
288 @subsubheading 1. Update source
290 At the beginning of each session of lilypond work, you should
291 click the @qq{Update source} button to get the latest changes to
294 @warning{In some rare and unfortunate circumstances, this will
295 result in a @emph{merge conflict}. If this occurs, follow the
296 instructions for @qq{Abort changes}, below. Your work will not be
300 @subsubheading 2a. New local commit
302 A single commit typically represents one logical set of related
303 changes (such as a bug-fix), and may incorporate changes to
304 multiple files at the same time.
306 When you're finished making the changes for a commit, click the
307 @qq{New local commit} button. This will open the @qq{Git Commit
308 Message} window. The message header is required, and the message
311 After entering a commit message, click @qq{OK} to finalize the
314 @advanced{for more information regarding commits and commit
315 messages, see @ref{Commits and patches}.}
318 @subsubheading 2b. Amend previous commit
320 You can go back and make changes to the most recent commit with
321 the @qq{Amend previous commit} button. This is useful if a
322 mistake is found after you have clicked the @qq{New local commit}
325 To amend the most recent commit, re-edit the source files as
326 needed and then click the @qq{Amend previous commit} button. The
327 earlier version of the commit is not saved, but is replaced by the
330 @warning{This does not update the patch @strong{files}; if you
331 have a patch file from an earlier version of the commit, you will
332 need to make another patch set when using this feature. The old
333 patch file will not be saved, but will be replaced by the new one
334 after you click on @qq{Make patch set}.}
337 @subsubheading 3. Make patch set
339 Before making a patch set from any commits, you should click the
340 @qq{Update source} button to make sure the commits are based on
341 the most recent remote snapshot.
343 When you click the @qq{Make patch set} button,
344 @command{lily-git.tcl} will produce patch files for any new
345 commits, saving them to the current directory. The command output
346 will display the name of the new patch files near the end of the
350 0001-CG-add-lily-git-instructions.patch
354 Send patch files to the appropriate place:
358 If you have a mentor, send it to them via email.
361 New contributors should send the patch attached to an email to
362 @email{frogs@@lilynet.net}. Please add @qq{[PATCH]} to the
366 Translators should send patches to
367 @email{translations@@lilynet.net}.
370 More experienced contributors should upload the patch for
371 web-based review. This requires additional software and use of
372 the command-line; see @ref{Uploading a patch for review}.
377 @subsubheading The @qq{Abort changes -- Reset to origin} button
379 @warning{Only use this if your local commit history gets
380 hopelessly confused!}
382 The button labeled @qq{Abort changes -- Reset to origin} will copy
383 all changed files to a subdirectory of @file{lilypond-git/} named
384 @file{aborted_edits/}, and will reset the repository to the
385 current state of the remote repository (at @code{git.sv.gnu.org}).
389 @node Compiling with lilydev
390 @section Compiling with lilydev
392 Lilydev is our @q{remix} of Ubuntu which contains all the
393 necessary dependencies to do lilypond development; for more
394 information, see @rcontrib{Lilydev}.
396 @subsubheading Preparing the build
398 To prepare the build directory, enter (or copy&paste) the below
399 text. This should take less than a minute.
401 @c we heavily recommend the out-of-tree build; do not change this!
405 sh autogen.sh --noconfigure
411 @subsubheading Building @code{lilypond}
413 Compiling lilypond will likely take between 5 and 60 minutes,
414 depending on your computer's speed and available RAM. We
415 recommend that you minimize the terminal window while it is
416 building; this can have a non-negligible effect on compilation
420 cd ~/lilypond-git/build/
424 You may run the compiled @code{lilypond} with:
427 cd ~/lilypond-git/build/
428 out/bin/lilypond my-file.ly
431 @subsubheading Building the documentation
433 Compiling the documentation is a much more involved process, and
434 will likely take 2 to 10 hours.
437 cd ~/lilypond-git/build/
441 The documentation is put in @file{out-www/offline-root/}. You may
442 view the html files by entering the below text; we recommend that
443 you bookmark the resulting page:
446 firefox ~/lilypond-git/build/out-www/offline-root/index.html
449 @subsubheading Other options
451 To select different build options, or isolate certain parts of the
452 build, or to use multiple CPUs while building, read the rest of
455 @subsubheading Installing LilyPond with lilydev
457 Don't. There is no reason to install lilypond within lilydev.
458 All development work can (and should) stay within the
459 @file{$HOME/lilypond-git/} directory, and any personal composition
460 or typesetting work should be done with an official GUB release.
463 @node Now start work!
464 @section Now start work!
466 Lilydev users may now skip to the chapter which is aimed at
467 their intended contributions:
470 @item @rcontrib{Documentation work}
471 @item @rcontrib{Translate the documentation}
472 @item @rcontrib{Website work}
473 @item @rcontrib{Regression tests}
474 @item @rcontrib{Programming work}