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 Debian 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{Debian 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 or copied to a USB stick and installed like any
29 other GNU/Linux distribution.
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 Linux} web pages.
38 For those interested, the LilyDev remix is currently based on a 32bit
39 version of Debian 7 (Wheezy). The image is generated using Debian
40 @uref{http://live.debian.net/, live-build} and the configuration
41 files are hosted on GitHub:
44 @uref{https://github.com/fedelibre/LilyDev}
47 @warning{Apart from installing and configuring LilyDev in VirtualBox,
48 the rest of the chapter assumes that you are comfortable using the
49 command-line. While this chapter is intended for users who may have
50 never created a patch or compiled software before, experienced
51 developers (who prefer to use their own development environment) may
52 still find it instructive to skim over this section.}
55 * Where to get LilyDev::
56 * Installing LilyDev in VirtualBox::
57 * Configuring LilyDev in VirtualBox::
61 @node Where to get LilyDev
62 @unnumberedsubsec Where to get LilyDev
64 Download the LilyDev image file (approximately 850 MB) from here:
67 @uref{http://www.et.byu.edu/~sorensen/lilydev-3.0.iso}
70 Some advanced users might want this file too:
72 @uref{http://www.et.byu.edu/~sorensen/lilydev-3.0.iso.md5}
74 (If you don't recognize what this file is, then you don't need it.)
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} choose @q{Debian (32 bit)} (don't use 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.
127 @warning{The image contains a 686-pae kernel, so you must enable PAE
128 in the virtual machine settings: click on @clicksequence{System @click{} Processor}
129 and select @q{Extended features: Enable PAE/NX}.}
132 Click the @q{Start} button and the @q{First Run Wizard} will prompt you for
133 the installation media. Click the browse icon and locate the LilyDev
134 disk image and click through the wizard to start the installation
138 When the LilyDev disk image boots, you should choose the @q{Install} or
139 the @q{Graphical install} menu item to begin the installation of
140 LilyDev on your virtual hard disk. The installer will walk you
141 through the complete installation process.
143 @warning{If the root password is left blank when prompted, the configured user
144 account will be be given root privileges automatically. This means that only
145 one password needs to be remembered.}
148 At the @qq{Partition disks} stage, do not be afraid to select
149 @qq{Guided - use entire disk}, since this refers to your
150 @strong{@emph{virtual disk}}, not your machine's actual hard
154 Click through the rest of the wizard, filling in any appropriate details
155 when asked and wait for the install to complete.
156 This will take about 10 minutes in a recent computer.
159 When the installation is completed, just click on Continue (you
160 don't have to remove any media since you installed from a file
161 on your host filesystem). The installer will reboot the virtual
162 machine: LilyDev is now installed and running!
168 Not all hardware is supported in all virtualization tools. In
169 particular, some contributors have reported problems with USB network
170 adapters. If you have problems with network connection (for example
171 Internet connection in the host system is lost when you launch virtual
172 system), try installing and running LilyDev with your computer's
173 built-in network adapter used to connect to the network. Refer to the
174 help documentation that comes with your virtualization software.
177 @node Configuring LilyDev in VirtualBox
178 @unnumberedsubsec Configuring LilyDev in VirtualBox
180 VirtualBox has extra @q{guest additions} which although are not
181 necessary to use LilyDev or compile Lilypond, do provide some additional
182 features to your Virtual Machine to make it easier to work with. Such
183 as being able to dynamically resize the LilyDev window, allow seamless
184 interaction with your mouse pointer on both the host and guest and let
185 you copy/paste between your host and guest if needed.
190 Select the @q{Devices} menu from the virtual machine window and choose
191 @q{Install Guest Additions...}. This will automount a CD which will
192 prompt you to autorun it. Click OK and follow the instructions. It is
193 recommended to reboot the guest when the installation is complete.
195 Other virtualization software will also have their own @q{guest}
196 additions, follow the normal procedures for your virtualization software
197 with LilyDev as the client.
200 Restart LilyDev to complete the installation of the guest additions.
202 @advanced{If you do any kernel upgrades, you may need to reinstall
203 the additional software. Just follow the step above again and reboot
204 when the reinstallation is complete.}
209 Other items that may be helpful:
214 In the settings for the virtual machine, set the network to
215 Bridged mode to allow you to access shared folders when using Windows
219 Set up any additional features, such as @q{Shared Folders} between
220 your main operating system and LilyDev. This is distinct from the
221 networked share folders in Windows. Consult the external
222 documentation for this.
224 Some longtime contributors have reported that @q{shared folders}
225 are rarely useful and not worth the fuss, particularly since files
226 can be shared over a network instead.
229 Pasting into a terminal is done with @code{Ctrl+Shift+v}.
232 Right-click allows you to edit a file with the text editor (default
236 One particular change from Windows and MacOS X is that most
237 software should be installed with your @qq{package manager}; this
238 vastly simplifies the process of installing and configuring
239 software. If you use LilyDev 3.0 and you need a graphical
240 package manager type this command in a terminal:
242 @c synaptic will be added in the next version of LilyDev
245 sudo apt-get install synaptic
248 Go to the menu at the bottom left and click on
249 @clicksequence{Preferences @click{} Synaptic Package Manager}.
257 The @q{LilyPond Contributor's Git Interface} (otherwise known as
258 @command{lily-git.tcl}) is a simple-to-use GUI to help you download and
259 update the LilyPond source code as well as an aid to making software
263 * Where to get lily-git::
264 * Configuring lily-git and downloading the source code::
265 * How to use lily-git::
268 @node Where to get lily-git
269 @unnumberedsubsec Where to get lily-git
271 Depending on your development environment, lily-git may already be
272 installed on your computer.
276 If you are using LilyDev (see @ref{LilyDev}) then lily-git should be
277 already installed and ready to run. This is not the case for the
278 current version (3.0), but you can easily turn it on by adding this
282 # add lily-git to the PATH
283 PATH=$LILYPOND_GIT/scripts/auxiliar:"$@{PATH@}"
287 For those not using LilyDev then lily-git can be obtained by downloading
288 the software directly. See @ref{Manually installing lily-git.tcl}.
291 Finally, lily-git is always part of the LilyPond source code and is
292 located in @file{$LILYPOND_GIT/scripts/auxillar/lily-git.tcl}.
297 @node Configuring lily-git and downloading the source code
298 @unnumberedsubsec Configuring lily-git and downloading the source code
300 @warning{The rest of this manual assumes that you are using the
301 command-line within a terminal.}
305 Type (or copy&paste) into the Terminal:
312 You will be prompted to enter your name and your email address. This
313 information is used only to identify and label any patches you create.
314 This information can be edited if required later. See
315 @ref{Configuring Git}. Click on the @emph{Submit} button to update
316 lily-git with this information.
319 Click on the @qq{Get source} button.
321 A directory called @file{$LILYPOND_GIT} is now created within
322 your home directory and the complete source code will start to be
325 @warning{Be patient! The complete source is around 150@tie{}Mb.}
328 When the source code has been downloaded, the @qq{Command output} window
329 in lily-git will update and display @qq{Done} on the very last line.
330 The button label will change to say @qq{Update source}.
332 @warning{Some contributors have reported that occasionally nothing
333 happens at this step at all. If this occurs, then try again in a few
334 minutes -- it could be an intermittant network problem. If the
335 problem persists, please ask for help.}
338 Close the lily-git GUI and navigate to the @file{$LILYPOND_GIT}
339 directory to view and edit the source files.
344 If this is the first time you have compiled LilyPond then please go
345 to @ref{Compiling with LilyDev} before reading on.
348 @node How to use lily-git
349 @unnumberedsubsec How to use lily-git
351 @warning{Throughout the rest of this manual, most command-line
352 input should be entered from @file{~/lilypond-git/}. This is
353 known as the @emph{top source directory} and is often referred to as
354 @var{$LILYPOND_GIT}.}
356 @warning{Only work on one set of changes at once. Do not start
357 work on any new changes until your first set has been accepted.}
359 @subsubheading 1. Update source
361 At the beginning of each session of lilypond work, you should
362 click the @qq{Update source} button to get the latest changes to
365 @warning{In some rare and unfortunate circumstances, this will
366 result in a @emph{merge conflict}. If this occurs, follow the
367 instructions for @qq{Abort changes}, below. Your work will not be
371 @subsubheading 2a. New local commit
373 A single commit typically represents one logical set of related
374 changes (such as a bug-fix), and may incorporate changes to
375 multiple files at the same time.
377 When you're finished making the changes for a commit, click the
378 @qq{New local commit} button. This will open the @qq{Git Commit
379 Message} window. The message header is required, and the message
382 After entering a commit message, click @qq{OK} to finalize the
385 @advanced{for more information regarding commits and commit
386 messages, see @ref{Commits and patches}.}
389 @subsubheading 2b. Amend previous commit
391 You can go back and make changes to the most recent commit with
392 the @qq{Amend previous commit} button. This is useful if a
393 mistake is found after you have clicked the @qq{New local commit}
396 To amend the most recent commit, re-edit the source files as
397 needed and then click the @qq{Amend previous commit} button. The
398 earlier version of the commit is not saved, but is replaced by the
401 @warning{This does not update the patch @strong{files}; if you
402 have a patch file from an earlier version of the commit, you will
403 need to make another patch set when using this feature. The old
404 patch file will not be saved, but will be replaced by the new one
405 after you click on @qq{Make patch set}.}
408 @subsubheading 3. Make patch set
410 Before making a patch set from any commits, you should click the
411 @qq{Update source} button to make sure the commits are based on
412 the most recent remote snapshot.
414 When you click the @qq{Make patch set} button,
415 @command{lily-git.tcl} will produce patch files for any new
416 commits, saving them to the current directory. The command output
417 will display the name of the new patch files near the end of the
421 0001-CG-add-lily-git-instructions.patch
425 Send patch files to the appropriate place:
429 If you have a mentor, send it to them via email.
432 Translators should send patches to
433 @email{translations@@lilynet.net}.
436 More experienced contributors should upload the patch for
437 web-based review. This requires additional software and use of
438 the command-line; see @ref{Uploading a patch for review}.
441 If you have trouble uploading the patch for review,
442 ask for help on @email{lilypond-devel@@gnu.org}.
447 @subsubheading The @qq{Abort changes -- Reset to origin} button
449 @warning{Only use this if your local commit history gets
450 hopelessly confused!}
452 The button labeled @qq{Abort changes -- Reset to origin} will copy
453 all changed files to a subdirectory of @file{$LILYPOND_GIT} named
454 @file{aborted_edits/}, and will reset the repository to the
455 current state of the remote repository (at @code{git.sv.gnu.org}).
459 @node Compiling with LilyDev
460 @section Compiling with LilyDev
462 LilyDev is our @q{remix} of Debian which contains all the
463 necessary dependencies to do lilypond development; for more
464 information, see @ref{LilyDev}.
466 @subsubheading Preparing the build
468 To prepare the build directory, enter (or copy&paste) the below
469 text. This should take less than a minute.
471 @c we heavily recommend the out-of-tree build; do not change this!
475 sh autogen.sh --noconfigure
481 @subsubheading Building @code{lilypond}
483 Compiling lilypond will likely take between 5 and 60 minutes,
484 depending on your computer's speed and available RAM. We
485 recommend that you minimize the terminal window while it is
486 building; this can have a non-negligible effect on compilation
490 cd $LILYPOND_GIT/build/
494 You may run the compiled @code{lilypond} with:
497 cd $LILYPOND_GIT/build/
498 out/bin/lilypond my-file.ly
501 @subsubheading Building the documentation
503 Compiling the documentation is a much more involved process, and
504 will likely take 2 to 10 hours.
507 cd $LILYPOND_GIT/build/
512 The documentation is put in @file{out-www/offline-root/}. You may
513 view the html files by entering the below text; we recommend that
514 you bookmark the resulting page:
517 firefox $LILYPOND_GIT/build/out-www/offline-root/index.html
520 @subsubheading Installing
522 Don't. There is no reason to install lilypond within LilyDev.
523 All development work can (and should) stay within the
524 @file{$LILYPOND_GIT} directory, and any personal composition
525 or typesetting work should be done with an official GUB release.
528 @subsubheading Problems and other options
530 To select different build options, or isolate certain parts of the
531 build, or to use multiple CPUs while building, read
534 In particular, contributors working on the documentation should be
535 aware of some bugs in the build system, and should read the
536 workarounds in @ref{Generating documentation}.
539 @node Now start work!
540 @section Now start work!
542 LilyDev users may now skip to the chapter which is aimed at
543 their intended contributions:
546 @item @ref{Documentation work}
547 @item @ref{Translating the documentation}
548 @item @ref{Website work}
549 @item @ref{Regression tests}
550 @item @ref{Programming work}
553 These chapters are mainly intended for people not using LilyDev,
554 but they contain extra information about the
555 @qq{behind-the-scenes} activities. We recommend that you read
556 these at your leisure, a few weeks after beginning work with
560 @item @ref{Working with source code}
561 @item @ref{Compiling}