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
16 @advanced{experienced developers may prefer to use their own
17 development environment. It may be instructive to skim over these
18 instructions, but be aware that this chapter is intended for
19 helpful users who may have never created a patch before.}
32 * Installing lilybuntu::
33 * Configuring lilybuntu in virtualbox::
37 @node Installing lilybuntu
38 @subsection Installing lilybuntu
42 Install some virtualization software.
44 Any virtualization tool can be used, but we recommend VirtualBox:
47 @uref{http://@/www.virtualbox.org/@/wiki/@/Downloads}
50 In virtualization terminology, your main operating system is the
51 @qq{host}, while lilybuntu is the @qq{guest}.
54 Download the @file{lilybuntu2.iso} disk image: (approximately 1
58 @uref{http://files.lilynet.net/lilybuntu2.iso}
61 @advanced{There is a md5sum available:
62 @uref{http://files.lilynet.net/lilybuntu2.iso.md5}}
65 Install @file{lilybuntu2.iso} as the @qq{guest} operating system
66 on your virtualized system.
71 If possible, use at least 700 MB of RAM (1GB would be better) for
72 the virtual machine, and use @qq{dynamically expanding storage}
73 for the virtual hard drive. A complete compile of everything
74 (code, docs, regression tests) can reach 10 GB.
77 When @file{lilybuntu2.iso} boots, it shows an ISOLINUX
78 @code{boot:} prompt. Type:
85 At the @qq{Prepare disk space} stage, do not be afraid to select
86 @qq{Erase and use the entire disk}, since this refers to your
87 @emph{virtual disk}, not your machine's actual hard drive.
90 When prompted to remove the installation CD, go to
91 @clicksequence{Devices @click{} CD/DVD Devices} and de-select
92 @file{lilybuntu2.iso}.
97 The latest version of lilybuntu is based on Ubuntu 10.04.1; if you
98 encounter any difficulties installing it, search for one of the
99 many tutorials for installing that particular version of Ubuntu as
100 a guest operating system.
104 Do any extra configuration for your virtualization software.
106 We have additional instructions in
107 @ref{Configuring lilybuntu in virtualbox}.
109 If you use other virtualization software, then follow the normal
110 procedures for your virtualization software with Ubuntu as the
113 @advanced{not all hardware is supported in all virtualization
114 tools. In particular, some contributors have reported problems
115 with USB devices. If you would like to investigate further, then
116 look for help for your virtualization tool using your normal OS as
117 the @qq{host} and Ubuntu as the @qq{client}.}
122 @node Configuring lilybuntu in virtualbox
123 @subsection Configuring lilybuntu in virtualbox
125 VirtualBox has extra @qq{guest additions} which can make the
126 virtualization easier to use (full-screen, easy file sharing
127 between host and guest operating systems, shared clipboards, etc).
132 In @emph{VirtualBox}, select @clicksequence{Devices @click{}
133 Install Guest Additions...}.
136 In @emph{Ubuntu}, select @clicksequence{Places @click{}
137 VBOXADDITIONS_}. A file-system window will open.
140 Double-click on the @file{autorun.sh} file, then select @qq{Run in
141 Terminal}, and enter your password when prompted.
144 Once the script is finished, restart Ubuntu to complete the
148 Set up any additional features, such as @q{Shared Folders} between
149 your main operating system and ubuntu. Consult external
150 documentation for this step.
152 @advanced{If you do any kernel upgrades, you may need to re-run
153 these VBOXADDITIONS instructions.}
158 @node Using lilybuntu
159 @subsection Using lilybuntu
161 If you are not familiar with Linux, it may be beneficial to read a
162 couple of @qq{introduction to Ubuntu} webpages.
166 One particular change from Windows and MacOS X is that most
167 software should be installed with your @qq{package manager}; this
168 vastly simplifies the process of installing and configuring
169 software. Go to @clicksequence{System @click{} Administration
170 @click{} Synaptic Package Manager}.
173 The rest of this manual assumes that you are using the
174 command-line; go to @clicksequence{Applications @click{}
175 Accessories @click{} Terminal}.
180 @c if you change this node name, you'll need to change the @ref in
181 @c web/ and/or included/, along with all the translations.
183 @section Using lily-git
185 @command{lily-git.tcl} is a graphical tool to help you access and
186 share changes to the lilypond source code.
189 * Install and configuration of lily-git.tcl::
190 * Daily use of lily-git.tcl::
193 @node Install and configuration of lily-git.tcl
194 @unnumberedsubsec Install and configuration of @command{lily-git.tcl}
196 @warning{The rest of this manual assumes that you are using the
197 command-line; go to @clicksequence{Applications @click{}
198 Accessories @click{} Terminal}.}
202 @code{lily-git.tcl} has already been install for you. Simply type
211 Click on the @qq{Get source} button.
213 This will create a directory called @file{lilypond-git/} within
214 your home directory, and will download the source code into that
215 directory (around 55Mb). When the process is finished, the
216 @qq{Command output} window will display @qq{Done}, and the button
217 label will change to say @qq{Update source}.
220 Navigate to the @file{lilypond-git/} directory to view the source
221 files. You should now be able to modify the source files using
222 your normal text editor.
226 You should now progress to @ref{Compiling with lilybuntu}.
228 @warning{Throughout the rest of this manual, most command-line
229 input should be entered from @file{~/lilypond-git/}. This is
230 referred to as the @emph{top source directory}.}
233 @subsubheading Other operating music systems
237 If you haven't already, download and install Git.
242 Lilybuntu users: git has already been installed for you.
244 @item Windows users: download the @code{.exe} file labeled
245 @qq{Full installer for official Git} from:
248 @uref{http://code.google.com/p/msysgit/downloads/list}
251 @item Other operating systems: either install @command{git} with
252 your package manager, or download it from the @qq{Binaries}
256 @uref{http://git-scm.com/download}
263 Download the @command{lily-git.tcl} script from:
265 @c don't change the cgit link below to gitweb; gitweb uses
266 @c long filenames like "scripts_auxiliar_lily-git.tcl"
269 @uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
273 To run the program from the command line, navigate to the
274 directory containing @command{lily-git.tcl} and enter:
281 Go read the lilybuntu instructions, starting from the @qq{get
286 @advanced{the @qq{Get source} button does not fetch the entire
287 history of the git repository, so utilities like @command{gitk}
288 will only be able to display the most recent additions. As you
289 continue to work with @command{lily-git.tcl}, the @qq{Update
290 source} button will take any new additions and add it to whatever
291 is currently in your repository's history.}
294 @node Daily use of lily-git.tcl
295 @unnumberedsubsec Daily use of @command{lily-git.tcl}
297 @warning{Only work on one set of changes at once. Do not start
298 work on any new changes until your first set has been accepted.}
300 @subsubheading 1. Update source
302 At the beginning of each session of lilypond work, you should
303 click the @qq{Update source} button to get the latest changes to
306 @warning{In some rare and unfortunate circumstances, this will
307 result in a @emph{merge conflict}. If this occurs, follow the
308 instructions for @qq{Abort changes}, below. Your work will not be
312 @subsubheading 2a. New local commit
314 A single commit typically represents one logical set of related
315 changes (such as a bug-fix), and may incorporate changes to
316 multiple files at the same time.
318 When you're finished making the changes for a commit, click the
319 @qq{New local commit} button. This will open the @qq{Git Commit
320 Message} window. The message header is required, and the message
323 After entering a commit message, click @qq{OK} to finalize the
326 @advanced{for more information regarding commits and commit
327 messages, see @ref{Commits and patches}.}
330 @subsubheading 2b. Amend previous commit
332 You can go back and make changes to the most recent commit with
333 the @qq{Amend previous commit} button. This is useful if a
334 mistake is found after you have clicked the @qq{New local commit}
337 To amend the most recent commit, re-edit the source files as
338 needed and then click the @qq{Amend previous commit} button. The
339 earlier version of the commit is not saved, but is replaced by the
342 @warning{This does not update the patch @strong{files}; if you
343 have a patch file from an earlier version of the commit, you will
344 need to make another patch set when using this feature. The old
345 patch file will not be saved, but will be replaced by the new one
346 after you click on @qq{Make patch set}.}
349 @subsubheading 3. Make patch set
351 Before making a patch set from any commits, you should click the
352 @qq{Update source} button to make sure the commits are based on
353 the most recent remote snapshot.
355 When you click the @qq{Make patch set} button,
356 @command{lily-git.tcl} will produce patch files for any new
357 commits, saving them to the current directory. The command output
358 will display the name of the new patch files near the end of the
362 0001-CG-add-lily-git-instructions.patch
366 Send patch files to the appropriate place:
370 If you have a mentor, send it to them via email.
373 New contributors should send the patch attached to an email to
374 @email{frogs@@lilynet.net}. Please add @qq{[PATCH]} to the
378 Translators should send patches to
379 @email{translations@@lilynet.net}.
382 More experienced contributors should upload the patch for
383 web-based review. This requires additional software and use of
384 the command-line; see @ref{Uploading a patch for review}.
389 @subsubheading The @qq{Abort changes -- Reset to origin} button
391 @warning{Only use this if your local commit history gets
392 hopelessly confused!}
394 The button labeled @qq{Abort changes -- Reset to origin} will copy
395 all changed files to a subdirectory of @file{lilypond-git/} named
396 @file{aborted_edits/}, and will reset the repository to the
397 current state of the remote repository (at @code{git.sv.gnu.org}).