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.)
71 An alternate site for obtaining these files is available:
73 @uref{http://www.et.byu.edu/~sorensen/ubuntu-LilyDev-remix-2.6.iso}
74 @uref{http://www.et.byu.edu/~sorensen/ubuntu-LilyDev-remix-2.6.iso.md5}
78 @node Installing LilyDev in VirtualBox
79 @unnumberedsubsec Installing LilyDev in VirtualBox
81 This section discusses how to install and use LilyDev with VirtualBox.
83 @warning{If you already know how to install a virtual machine using a
84 disc image inside VirtualBox (or your own virtualization software) then
85 you can skip this section and go straight to @ref{lily-git}.}
89 Download Virtualbox from here:
92 @uref{http://@/www.virtualbox.org/@/wiki/@/Downloads}
95 @warning{In virtualization terminology, the operating system where
96 Virtualbox is installed is known as the @strong{host}. LilyDev
97 will be installed @q{inside} Virtualbox as a @strong{guest}.}
100 Start the VirtualBox software and click @q{New} to create a new
101 @qq{virtual machine}.
103 The @q{New Virtual Machine Wizard} will walk you through setting up your
104 guest virtual machine. Choose an appropriate name for your LilyDev
105 installation and select the @q{Linux} operating system. When selecting
106 the @q{version} use @q{Ubuntu} if available (but not the @q{64 bit}
107 option). If you do not have that specific option choose @q{Linux 2.6}
108 (again do not choose any option that has 64 bit next to it).
111 Select the amount of RAM you will allow the LilyDev guest to use from
112 your host operating system when it is running. If possible, use at
113 least 700 MB of RAM; the more RAM you can spare from your host the
114 better, although LilyDev will currently use no more than 4 GB (4096 MB)
115 even if you are able to assign more.
118 For your @q{Virtual Hard Disk}, leave the @q{Create new hard disk}
119 option checked, use the default @q{VDI} and
120 @qq{Dynamically allocated} options for the virtual hard drive. A
121 complete compile of everything (code, docs, regression tests) can reach
122 10 GB so size your virtual disk and its location accordingly.
125 Verify the summary details and click @q{Create}, when you are satisfied.
126 Your new guest will be displayed in the Virtualbox window. Click the
127 @q{Start} button and the @q{First Run Wizard} will prompt you for
128 the installation media. Click the browse icon and locate the LilyDev
129 disk image and click through the wizard to start the installation
133 When the LilyDev disk image boots, it shows a prompt:
136 ISOLINUX @code{boot:}
139 Hit the Return key (or wait 30 seconds) and then when the installer
140 screen loads, using the arrow keys select
141 @q{Install - start the installer directly} to begin the install process
142 of LilyDev on your virtual hard disk. The Ubuntu software will walk you
143 through the complete installation process.
146 At the @qq{Prepare disk space} stage, do not be afraid to select
147 @qq{Erase and use the entire disk}, since this refers to your
148 @strong{@emph{virtual disk}}, not your machine's actual hard
152 Click through the rest of the wizard, filling in any appropriate details
153 when asked and wait for the install to complete.
155 @warning{This will take anywhere from 10 minutes to up to an hour
156 depending on the speed of your computer and if Ubuntu detects you are
157 connected to the internet and needs to download any additional
158 security updates or patches, although these updates are not required to
159 compile LilyPond and it is possible to skip the additional downloads to
160 speed up the install process.}
163 When prompted by the Ubuntu installer wizard, restart the virtual
164 machine and then when prompted to @q{eject the CD} by virtual box, just
165 click inside the virtual machine window and hit the return key to
166 reboot the virtual machine. It will not try to restart the installer
167 but start the virtual machine proper. LilyDev is now installed and
171 The current version of LilyPond requires the texlive-lang-cyrillic
172 package. This package is not part of LilyDev 2.6. Add the package
176 sudo apt-get install texlive-lang-cyrillic
183 Not all hardware is supported in all virtualization tools. In
184 particular, some contributors have reported problems with USB network
185 adapters. If you have problems with network connection (for example
186 Internet connection in the host system is lost when you launch virtual
187 system), try installing and running LilyDev with your computer's
188 built-in network adapter used to connect to the network. Refer to the
189 help documentation that comes with your virtualization software.
192 @node Configuring LilyDev in VirtualBox
193 @unnumberedsubsec Configuring LilyDev in VirtualBox
195 VirtualBox has extra @q{guest additions} which although are not
196 necessary to use LilyDev or compile Lilypond, do provide some additional
197 features to your Virtual Machine to make it easier to work with. Such
198 as being able to dynamically resize the LilyDev window, allow seamless
199 interaction with your mouse pointer on both the host and guest and let
200 you copy/paste between your host and guest if needed.
205 Select the @q{Devices} menu from the virtual machine window and choose
206 @q{Install Guest Additions...}. This will automount a CD which will
207 prompt you to autorun it. Click OK and follow the instructions. It is
208 recommended to reboot the guest when the installation is complete.
210 Other virtualization software will also have their own @q{guest}
211 additions, follow the normal procedures for your virtualization software
212 with Ubuntu as the client.
215 Restart Ubuntu to complete the installation of the guest additions.
217 @advanced{If you do any kernel upgrades, you may need to reinstall
218 the additional software. Just follow the step above again and reboot
219 when the reinstallation is complete.}
224 Other items that may be helpful:
229 In the settings for the virtual machine, set the network to
230 Bridged mode to allow you to access shared folders when using Windows
234 Set up any additional features, such as @q{Shared Folders} between
235 your main operating system and Ubuntu. This is distinct from the
236 networked share folders in Windows. Consult the external
237 documentation for this.
239 Some longtime contributors have reported that @q{shared folders}
240 are rarely useful and not worth the fuss, particularly since files
241 can be shared over a network instead.
244 Pasting into a terminal is done with @code{Ctrl+Shift+v}.
247 The @qq{Places} top-menu has shortcuts to a graphical
248 @qq{navigator} like Windows Explorer or the MacOS X Finder.
251 Right-click allows you to edit a file with gedit. We recommend
255 One particular change from Windows and MacOS X is that most
256 software should be installed with your @qq{package manager}; this
257 vastly simplifies the process of installing and configuring
258 software. Go to @clicksequence{Applications @click{} Ubuntu
267 The @q{LilyPond Contributor's Git Interface} (otherwise known as
268 @command{lily-git.tcl}) is a simple-to-use GUI to help you download and
269 update the LilyPond source code as well as an aid to making software
273 * Where to get lily-git::
274 * Configuring lily-git and downloading the source code::
275 * How to use lily-git::
278 @node Where to get lily-git
279 @unnumberedsubsec Where to get lily-git
281 Depending on your development environment, lily-git may already be
282 installed on your computer.
286 If you are using LilyDev (see @ref{LilyDev}) then lily-git is already
287 installed and ready to run.
290 For those not using LilyDev then lily-git can be obtained by downloading
291 the software directly. See @ref{Manually installing lily-git.tcl}.
294 Finally, lily-git is always part of the LilyPond source code and is
295 located in @file{$LILYPOND_GIT/scripts/auxillar/lily-git.tcl}.
300 @node Configuring lily-git and downloading the source code
301 @unnumberedsubsec Configuring lily-git and downloading the source code
303 @warning{The rest of this manual assumes that you are using the
304 command-line within a terminal.}
308 Type (or copy&paste) into the Terminal:
315 You will be prompted to enter your name and your email address. This
316 information is used only to identify and label any patches you create.
317 This information can be edited if required later. See
318 @ref{Configuring Git}. Click on the @emph{Submit} button to update
319 lily-git with this information.
322 Click on the @qq{Get source} button.
324 A directory called @file{$LILYPOND_GIT} is now created within
325 your home directory and the complete source code will start to be
328 @warning{Be patient! The complete source is around 150@tie{}Mb.}
331 When the source code has been downloaded, the @qq{Command output} window
332 in lily-git will update and display @qq{Done} on the very last line.
333 The button label will change to say @qq{Update source}.
335 @warning{Some contributors have reported that occasionally nothing
336 happens at this step at all. If this occurs, then try again in a few
337 minutes -- it could be an intermittant network problem. If the
338 problem persists, please ask for help.}
341 Close the lily-git GUI and navigate to the @file{$LILYPOND_GIT}
342 directory to view and edit the source files.
347 If this is the first time you have compiled LilyPond then please go
348 to @ref{Compiling with LilyDev} before reading on.
351 @node How to use lily-git
352 @unnumberedsubsec How to use lily-git
354 @warning{Throughout the rest of this manual, most command-line
355 input should be entered from @file{~/lilypond-git/}. This is
356 known as the @emph{top source directory} and is often referred to as
357 @var{$LILYPOND_GIT}.}
359 @warning{Only work on one set of changes at once. Do not start
360 work on any new changes until your first set has been accepted.}
362 @subsubheading 1. Update source
364 At the beginning of each session of lilypond work, you should
365 click the @qq{Update source} button to get the latest changes to
368 @warning{In some rare and unfortunate circumstances, this will
369 result in a @emph{merge conflict}. If this occurs, follow the
370 instructions for @qq{Abort changes}, below. Your work will not be
374 @subsubheading 2a. New local commit
376 A single commit typically represents one logical set of related
377 changes (such as a bug-fix), and may incorporate changes to
378 multiple files at the same time.
380 When you're finished making the changes for a commit, click the
381 @qq{New local commit} button. This will open the @qq{Git Commit
382 Message} window. The message header is required, and the message
385 After entering a commit message, click @qq{OK} to finalize the
388 @advanced{for more information regarding commits and commit
389 messages, see @ref{Commits and patches}.}
392 @subsubheading 2b. Amend previous commit
394 You can go back and make changes to the most recent commit with
395 the @qq{Amend previous commit} button. This is useful if a
396 mistake is found after you have clicked the @qq{New local commit}
399 To amend the most recent commit, re-edit the source files as
400 needed and then click the @qq{Amend previous commit} button. The
401 earlier version of the commit is not saved, but is replaced by the
404 @warning{This does not update the patch @strong{files}; if you
405 have a patch file from an earlier version of the commit, you will
406 need to make another patch set when using this feature. The old
407 patch file will not be saved, but will be replaced by the new one
408 after you click on @qq{Make patch set}.}
411 @subsubheading 3. Make patch set
413 Before making a patch set from any commits, you should click the
414 @qq{Update source} button to make sure the commits are based on
415 the most recent remote snapshot.
417 When you click the @qq{Make patch set} button,
418 @command{lily-git.tcl} will produce patch files for any new
419 commits, saving them to the current directory. The command output
420 will display the name of the new patch files near the end of the
424 0001-CG-add-lily-git-instructions.patch
428 Send patch files to the appropriate place:
432 If you have a mentor, send it to them via email.
435 Translators should send patches to
436 @email{translations@@lilynet.net}.
439 More experienced contributors should upload the patch for
440 web-based review. This requires additional software and use of
441 the command-line; see @ref{Uploading a patch for review}.
444 If you have trouble uploading the patch for review,
445 ask for help on @email{lilypond-devel@@gnu.org}.
450 @subsubheading The @qq{Abort changes -- Reset to origin} button
452 @warning{Only use this if your local commit history gets
453 hopelessly confused!}
455 The button labeled @qq{Abort changes -- Reset to origin} will copy
456 all changed files to a subdirectory of @file{$LILYPOND_GIT} named
457 @file{aborted_edits/}, and will reset the repository to the
458 current state of the remote repository (at @code{git.sv.gnu.org}).
462 @node Compiling with LilyDev
463 @section Compiling with LilyDev
465 LilyDev is our @q{remix} of Ubuntu which contains all the
466 necessary dependencies to do lilypond development; for more
467 information, see @rcontrib{LilyDev}.
469 @subsubheading Preparing the build
471 To prepare the build directory, enter (or copy&paste) the below
472 text. This should take less than a minute.
474 @c we heavily recommend the out-of-tree build; do not change this!
478 sh autogen.sh --noconfigure
484 @subsubheading Building @code{lilypond}
486 Compiling lilypond will likely take between 5 and 60 minutes,
487 depending on your computer's speed and available RAM. We
488 recommend that you minimize the terminal window while it is
489 building; this can have a non-negligible effect on compilation
493 cd $LILYPOND_GIT/build/
497 You may run the compiled @code{lilypond} with:
500 cd $LILYPOND_GIT/build/
501 out/bin/lilypond my-file.ly
504 @subsubheading Building the documentation
506 Compiling the documentation is a much more involved process, and
507 will likely take 2 to 10 hours.
510 cd $LILYPOND_GIT/build/
515 The documentation is put in @file{out-www/offline-root/}. You may
516 view the html files by entering the below text; we recommend that
517 you bookmark the resulting page:
520 firefox $LILYPOND_GIT/build/out-www/offline-root/index.html
523 @subsubheading Installing
525 Don't. There is no reason to install lilypond within LilyDev.
526 All development work can (and should) stay within the
527 @file{$LILYPOND_GIT} directory, and any personal composition
528 or typesetting work should be done with an official GUB release.
531 @subsubheading Problems and other options
533 To select different build options, or isolate certain parts of the
534 build, or to use multiple CPUs while building, read
537 In particular, contributors working on the documentation should be
538 aware of some bugs in the build system, and should read the
539 workarounds in @ref{Generating documentation}.
542 @node Now start work!
543 @section Now start work!
545 LilyDev users may now skip to the chapter which is aimed at
546 their intended contributions:
549 @item @ref{Documentation work}
550 @item @ref{Translating the documentation}
551 @item @ref{Website work}
552 @item @ref{Regression tests}
553 @item @ref{Programming work}
556 These chapters are mainly intended for people not using LilyDev,
557 but they contain extra information about the
558 @qq{behind-the-scenes} activities. We recommend that you read
559 these at your leisure, a few weeks after beginning work with
563 @item @ref{Working with source code}
564 @item @ref{Compiling}