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::
32 This section discusses how to install and use the Ubuntu LilyPond
36 * Installing lilydev::
37 * Configuring lilydev in virtualbox::
41 @node Installing lilydev
42 @subsection Installing lilydev
46 Install some virtualization software.
48 Any virtualization tool can be used, but we recommend VirtualBox:
51 @uref{http://@/www.virtualbox.org/@/wiki/@/Downloads}
54 In virtualization terminology, your main operating system is the
55 @strong{host}, while lilydev is the @strong{guest}.
58 Download the Ubuntu LilyPond Developer Remix disk image (approximately
62 @uref{http://www.philholmes.net/lilypond/lilydev/ubuntu-lilydev-remix-2.6.iso}
66 Create a new @qq{virtual machine} inside your virtualization
69 If possible, use at least 700 MB of RAM (1GB would be better) for
70 the virtual machine, and use @qq{dynamically expanding storage}
71 for the virtual hard drive. A complete compile of everything
72 (code, docs, regression tests) can reach 10 GB.
75 Install @file{ubuntu-lilydev-remix-2.6.iso} as the @strong{guest}
76 operating system on your virtualized system.
81 When @file{ubuntu-lilydev-remix-2.6.iso} boots, it shows an
82 ISOLINUX @code{boot:} prompt. Type:
89 At the @qq{Prepare disk space} stage, do not be afraid to select
90 @qq{Erase and use the entire disk}, since this refers to your
91 @strong{@emph{virtual disk}}, not your machine's actual hard
95 When prompted to remove the installation CD, go to
96 @clicksequence{Devices @click{} CD/DVD Devices} and de-select
97 @file{ubuntu-lilydev-remix-2.6.iso}.
102 The latest version of lilydev is based on Ubuntu 10.04.1; if you
103 encounter any difficulties installing it, search for one of the
104 many tutorials for installing that particular version of Ubuntu as
105 a guest operating system.
109 Do any extra configuration for your virtualization software.
111 There are additional instructions for VirtualBox in
112 @ref{Configuring lilydev in virtualbox}.
114 If you use other virtualization software, then follow the normal
115 procedures for your virtualization software with Ubuntu as the
122 Not all hardware is supported in all virtualization tools. In
123 particular, some contributors have reported problems with USB
124 devices, for example USB network adapters. If you have problems
125 with network connection (for example internet connection in the
126 host system is lost when you launch virtual system), try installing
127 and running Lilydev with your computer's built-in network adapter
128 used to connect to the network.
129 If you would like to investigate further, then look for
130 help for your virtualization tool using your normal OS as the
131 @qq{host} and Ubuntu as the @qq{client}.
134 @node Configuring lilydev in virtualbox
135 @subsection Configuring lilydev in virtualbox
137 VirtualBox has extra @qq{guest additions} which can make the
138 virtualization easier to use (full-screen, easy file sharing
139 between host and guest operating systems, shared clipboards, etc).
144 In @emph{VirtualBox}, select @clicksequence{Devices @click{}
145 Install Guest Additions...}.
148 In @emph{Ubuntu}, select @clicksequence{Places @click{}
149 VBOXADDITIONS_}. A file-system window will open.
152 Double-click on the @file{autorun.sh} file, then select @qq{Run in
153 Terminal}, and enter your password when prompted.
156 Once the script is finished, @qq{eject} the virtual CD, and then
157 go to @clicksequence{Devices @click{} CD/DVD Devices} and
158 de-select @file{VBoxGuestAdditions.iso}.
161 Restart Ubuntu to complete the installation.
163 @advanced{If you do any kernel upgrades, you may need to re-run
164 these VBOXADDITIONS instructions.}
167 Some other steps may be helpful:
171 In the settings for the virtual machine, set the network to
172 Bridged mode to allow you to access shared folders on your Windows
176 Set up any additional features, such as @q{Shared Folders} between
177 your main operating system and ubuntu. This is distinct from the
178 networked share folders in Windows. Consult external
179 documentation for this step.
181 Some longtime contributors have reported that @q{shared folders}
182 are rarely useful and not worth the fuss, particularly since files
183 can be shared over a network instead.
189 @subsection Using lilydev
191 If you are not familiar with Linux, it may be beneficial to read a
192 couple of @qq{introduction to Ubuntu} webpages.
196 One particular change from Windows and MacOS X is that most
197 software should be installed with your @qq{package manager}; this
198 vastly simplifies the process of installing and configuring
199 software. Go to @clicksequence{Applications @click{} Ubuntu
203 The rest of this manual assumes that you are using the
204 command-line; double-click on the @q{Terminal} icon on the
208 Pasting into a terminal is done with @code{Ctrl+Shift+v}.
211 The @qq{Places} top-menu has shortcuts to a graphical
212 @qq{navigator} like Windows Explorer or the MacOS X Finder.
215 Right-click allows you to edit a file with gedit. We recommend
219 Some contributors have recommended a free pdf:
222 @uref{http://www.ubuntupocketguide.com/}
229 @section Using lily-git
231 @command{lily-git.tcl} is a graphical tool to help you access and
232 share changes to the lilypond source code.
235 * Install and configuration of lily-git.tcl::
236 * Daily use of lily-git.tcl::
239 @node Install and configuration of lily-git.tcl
240 @unnumberedsubsec Install and configuration of @command{lily-git.tcl}
242 @warning{The rest of this manual assumes that you are using the
243 command-line; double-click on the @q{Terminal} icon on the
248 Type (or copy&paste) into the Terminal:
255 Click on the @qq{Get source} button.
257 This will create a directory called @file{lilypond-git/} within
258 your home directory, and will download the source code into that
259 directory (around 150@tie{}Mb). When the process is finished, the
260 @qq{Command output} window will display @qq{Done}, and the button
261 label will change to say @qq{Update source}.
263 @warning{Some contributors have reported that nothing happens at
264 this step. If this occurs, then try again in a few minutes -- we
265 suspect that this is an intermittant network problem. If the
266 problem persists, please ask for help.}
269 Navigate to the @file{lilypond-git/} directory to view the source
274 You should now progress to @ref{Compiling with lilydev}.
276 @warning{Throughout the rest of this manual, most command-line
277 input should be entered from @file{~/lilypond-git/}. This is
278 referred to as the @emph{top source directory}.}
281 @node Daily use of lily-git.tcl
282 @unnumberedsubsec Daily use of @command{lily-git.tcl}
284 @warning{Only work on one set of changes at once. Do not start
285 work on any new changes until your first set has been accepted.}
287 @subsubheading 1. Update source
289 At the beginning of each session of lilypond work, you should
290 click the @qq{Update source} button to get the latest changes to
293 @warning{In some rare and unfortunate circumstances, this will
294 result in a @emph{merge conflict}. If this occurs, follow the
295 instructions for @qq{Abort changes}, below. Your work will not be
299 @subsubheading 2a. New local commit
301 A single commit typically represents one logical set of related
302 changes (such as a bug-fix), and may incorporate changes to
303 multiple files at the same time.
305 When you're finished making the changes for a commit, click the
306 @qq{New local commit} button. This will open the @qq{Git Commit
307 Message} window. The message header is required, and the message
310 After entering a commit message, click @qq{OK} to finalize the
313 @advanced{for more information regarding commits and commit
314 messages, see @ref{Commits and patches}.}
317 @subsubheading 2b. Amend previous commit
319 You can go back and make changes to the most recent commit with
320 the @qq{Amend previous commit} button. This is useful if a
321 mistake is found after you have clicked the @qq{New local commit}
324 To amend the most recent commit, re-edit the source files as
325 needed and then click the @qq{Amend previous commit} button. The
326 earlier version of the commit is not saved, but is replaced by the
329 @warning{This does not update the patch @strong{files}; if you
330 have a patch file from an earlier version of the commit, you will
331 need to make another patch set when using this feature. The old
332 patch file will not be saved, but will be replaced by the new one
333 after you click on @qq{Make patch set}.}
336 @subsubheading 3. Make patch set
338 Before making a patch set from any commits, you should click the
339 @qq{Update source} button to make sure the commits are based on
340 the most recent remote snapshot.
342 When you click the @qq{Make patch set} button,
343 @command{lily-git.tcl} will produce patch files for any new
344 commits, saving them to the current directory. The command output
345 will display the name of the new patch files near the end of the
349 0001-CG-add-lily-git-instructions.patch
353 Send patch files to the appropriate place:
357 If you have a mentor, send it to them via email.
360 New contributors should send the patch attached to an email to
361 @email{frogs@@lilynet.net}. Please add @qq{[PATCH]} to the
365 Translators should send patches to
366 @email{translations@@lilynet.net}.
369 More experienced contributors should upload the patch for
370 web-based review. This requires additional software and use of
371 the command-line; see @ref{Uploading a patch for review}.
376 @subsubheading The @qq{Abort changes -- Reset to origin} button
378 @warning{Only use this if your local commit history gets
379 hopelessly confused!}
381 The button labeled @qq{Abort changes -- Reset to origin} will copy
382 all changed files to a subdirectory of @file{lilypond-git/} named
383 @file{aborted_edits/}, and will reset the repository to the
384 current state of the remote repository (at @code{git.sv.gnu.org}).
388 @node Compiling with lilydev
389 @section Compiling with lilydev
391 Lilydev is our @q{remix} of Ubuntu which contains all the
392 necessary dependencies to do lilypond development; for more
393 information, see @rcontrib{Lilydev}.
395 @subsubheading Preparing the build
397 To prepare the build directory, enter (or copy&paste) the below
398 text. This should take less than a minute.
400 @c we heavily recommend the out-of-tree build; do not change this!
404 sh autogen.sh --noconfigure
410 @subsubheading Building @code{lilypond}
412 Compiling lilypond will likely take between 5 and 60 minutes,
413 depending on your computer's speed and available RAM. We
414 recommend that you minimize the terminal window while it is
415 building; this can have a non-negligible effect on compilation
419 cd ~/lilypond-git/build/
423 You may run the compiled @code{lilypond} with:
426 cd ~/lilypond-git/build/
427 out/bin/lilypond my-file.ly
430 @subsubheading Building the documentation
432 Compiling the documentation is a much more involved process, and
433 will likely take 2 to 10 hours.
436 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 Installing
451 Don't. There is no reason to install lilypond within lilydev.
452 All development work can (and should) stay within the
453 @file{$HOME/lilypond-git/} directory, and any personal composition
454 or typesetting work should be done with an official GUB release.
457 @subsubheading Problems and other options
459 To select different build options, or isolate certain parts of the
460 build, or to use multiple CPUs while building, read
463 In particular, contributors working on the documentation should be
464 aware of some bugs in the build system, and should read the
465 workarounds in @ref{Generating documentation}.
468 @node Now start work!
469 @section Now start work!
471 Lilydev users may now skip to the chapter which is aimed at
472 their intended contributions:
475 @item @ref{Documentation work}
476 @item @ref{Translating the documentation}
477 @item @ref{Website work}
478 @item @ref{Regression tests}
479 @item @ref{Programming work}
482 These chapters are mainly intended for people not using LilyDev,
483 but they contain extra information about the
484 @qq{behind-the-scenes} activities. We recommend that you read
485 these at your leisure, a few weeks after beginning work with
489 @item @ref{Working with source code}
490 @item @ref{Compiling}