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 @c This text was written based on LilyDev 4.0 - JL
22 There is a @q{remix} of Debian GNU/Linux -- known as @qq{LilyDev} for
23 short -- which includes all the necessary software and tools to compile
24 LilyPond, the documentation and the website (also see
27 @warning{LilyDev does not include the software for the Grand Unified
28 Builder -- also see @ref{Grand Unified Builder (GUB)}.}
30 While compiling LilyPond on MacOs and Windows is possible, both
31 environments are complex to set up. LilyDev can be easily installed
32 and run inside a @q{virtual machine} on either of these operating
33 systems relatively easily using readily available virtualization
34 software. We recommend using VirtualBox as it is available for all
35 major operating systems and is very easy to install & configure.
37 The LilyDev disk image can also be written to a USB device or @q{burnt}
38 to a DVD -- it is approximately 900 GB in size -- and installed just
39 like any standard GNU/Linux distribution.
41 The current image is based on a 32bit version of Debian 8 (@q{Jessie})
42 and the Disk image was generated using Debian
43 @uref{http://live.debian.net/, live-build 4}.
46 Download the LilyDev disk image file from here:
49 @uref{https://github.com/fedelibre/LilyDev/releases/latest}
52 @warning{Apart from installing and configuring LilyDev in VirtualBox,
53 the rest of the chapter assumes that you are comfortable using the
54 command-line and is intended for users who may have never created a
55 patch or compiled software before. More experienced developers (who
56 prefer to use their own development environment) may still find it
57 instructive to skim over the following information.}
59 If you are not familiar with GNU/Linux, it may be beneficial to read a
60 a few @qq{introduction to Linux} type web pages.
63 * Installing LilyDev in VirtualBox::
64 * Configuring LilyDev in VirtualBox::
68 @node Installing LilyDev in VirtualBox
69 @unnumberedsubsec Installing LilyDev in VirtualBox
71 This section discusses how to install and use LilyDev with VirtualBox.
73 @warning{If you already know how to install a virtual machine using a
74 disc image inside VirtualBox (or your own virtualization software) then
75 you can skip this section and go straight to @ref{lily-git}.}
79 Download Virtualbox from here:
82 @uref{http://www.virtualbox.org/wiki/Downloads}
85 @warning{In virtualization terminology, the operating system where
86 Virtualbox is installed is known as the @strong{host}. LilyDev
87 will be installed @q{inside} Virtualbox as a @strong{guest}.}
90 Start the VirtualBox software and click @q{New} to create a new
93 The @q{New Virtual Machine Wizard} will walk you through setting up your
94 guest virtual machine. Choose an appropriate name for your LilyDev
95 installation and select the @q{Linux} operating system. When selecting
96 the @q{version} choose @q{Debian (32 bit)} (don't use the @q{64 bit}
97 option). If you do not have that specific option choose @q{Linux 2.6}
98 (again do not choose any option that has 64 bit next to it).
101 Select the amount of RAM you will allow the LilyDev guest to use from
102 your host operating system when it is running. If possible, use at
103 least 700 MB of RAM; the more RAM you can spare from your host the
104 better, although LilyDev will currently use no more than 4 GB (4096 MB)
105 even if you are able to assign more.
108 For your @q{Virtual Hard Disk}, leave the @q{Create new hard disk}
109 option checked, use the default @q{VDI} and @qq{Dynamically allocated}
110 options for the virtual hard drive. A complete compile of everything
111 (code, docs, regression tests) can reach 10 GB so size your virtual disk
112 and its location accordingly.
115 Verify the summary details and click @q{Create}, when you are satisfied.
116 Your new guest will be displayed in the Virtualbox window.
118 @warning{The image contains a @q{686-pae} kernel, so you must enable
119 @code{PAE} within the virtual machine's settings -- click on
120 @clicksequence{System @click{} Processor} and select
121 @q{Extended features: Enable PAE/NX}.}
124 Click the @q{Start} button and the @q{First Run Wizard} will prompt you
125 for the installation media. Click the browse icon, locate the LilyDev
126 disk image and click through the wizard to begin the installation
130 When the LilyDev disk image boots for the first time, choose either the
131 @q{Install} or the @q{Graphical install} menu item. The installer will
132 then walk you through the complete installation process.
135 At the @qq{Partition disks} stage, do not be afraid to select
136 @qq{Guided - use entire disk}, since this refers to your
137 @strong{@emph{virtual disk}}, not your computer's own hard disk.
140 Continue to click through the rest of the wizard, filling in any
141 appropriate details when asked, and wait for the install to complete.
142 This will take about 10 minutes or so on a reasonably modern computer.
145 When the installation is completed, just click on @q{Continue} (you
146 do not have to remove any media since you installed LilyDev from a Disk
147 image, which is just a file on your computer). The installer will
148 reboot the virtual machine.
153 LilyDev should now be installed and running!
156 @node Configuring LilyDev in VirtualBox
157 @unnumberedsubsec Configuring LilyDev in VirtualBox
159 VirtualBox has extra @q{guest additions} which although are not
160 necessary to use LilyDev or compile Lilypond, do provide some additional
161 features to your Virtual Machine to make it easier to work with. Such
162 as being able to dynamically resize the LilyDev window, allow seamless
163 interaction with your mouse pointer on both the host and guest and let
164 you copy/paste between your host and guest if needed.
169 Select the @q{Devices} menu from the virtual machine window and choose
170 @q{Install Guest Additions...}. This will automount a CD which will
171 prompt you to autorun it. Click OK and follow the instructions. It is
172 recommended to reboot the guest when the installation is complete.
174 Other virtualization software will also have their own @q{guest}
175 additions, follow the normal procedures for your virtualization software
176 with LilyDev as the client.
179 Restart LilyDev to complete the installation of the guest additions.
181 @advanced{If you do any kernel upgrades, you may need to reinstall the
182 additional software. Just follow the step above again and reboot when
183 the reinstallation is complete.}
188 Other items that may be helpful:
193 In the settings for the virtual machine, set the network to
194 Bridged mode to allow you to access shared folders when using Windows
198 Set up any additional features, such as @q{Shared Folders} between
199 your main operating system and LilyDev. This is distinct from the
200 networked share folders in Windows. Consult the external documentation
203 Some longtime contributors have reported that @q{shared folders}
204 are rarely useful and not worth the fuss, particularly since files
205 can be shared over a network instead.
208 Pasting into a terminal is done with @code{Ctrl+Shift+v}.
211 Right-click allows you to edit a file with the text editor (default
217 Not all hardware is supported in all virtualization tools. In
218 particular, some contributors have reported problems with USB network
219 adapters. If you have problems with network connection (for example
220 Internet connection in the host system is lost when you launch virtual
221 system), try installing and running LilyDev with your computer's
222 built-in network adapter used to connect to the network. Refer to the
223 help documentation that comes with your virtualization software.
229 The @q{LilyPond Contributor's Git Interface} (otherwise known as
230 @command{lily-git.tcl}) is a simple-to-use GUI to help you download and
231 update the LilyPond source code as well as an aid to making software
235 * Where to get lily-git::
236 * Configuring lily-git and downloading the source code::
237 * How to use lily-git::
240 @node Where to get lily-git
241 @unnumberedsubsec Where to get lily-git
243 Depending on your development environment, lily-git may already be
244 installed on your computer.
248 If you are using LilyDev (see @ref{LilyDev}) then lily-git should be
249 already installed and ready to run. This is not the case for the
250 current version (3.0), but you can easily turn it on by adding this
254 # add lily-git to the PATH
255 PATH=$LILYPOND_GIT/scripts/auxiliar:"$@{PATH@}"
259 For those not using LilyDev then lily-git can be obtained by downloading
260 the software directly. See @ref{Manually installing lily-git.tcl}.
263 Finally, lily-git is always part of the LilyPond source code and is
264 located in @file{$LILYPOND_GIT/scripts/auxillar/lily-git.tcl}.
269 @node Configuring lily-git and downloading the source code
270 @unnumberedsubsec Configuring lily-git and downloading the source code
272 @warning{The rest of this manual assumes that you are using the
273 command-line within a terminal.}
277 Type (or copy&paste) into the Terminal:
284 You will be prompted to enter your name and your email address. This
285 information is used only to identify and label any patches you create.
286 This information can be edited if required later. See
287 @ref{Configuring Git}. Click on the @emph{Submit} button to update
288 lily-git with this information.
291 Click on the @qq{Get source} button.
293 A directory called @file{$LILYPOND_GIT} is now created within
294 your home directory and the complete source code will start to be
297 @warning{Be patient! The complete source is around 150@tie{}Mb.}
300 When the source code has been downloaded, the @qq{Command output} window
301 in lily-git will update and display @qq{Done} on the very last line.
302 The button label will change to say @qq{Update source}.
304 @warning{Some contributors have reported that occasionally nothing
305 happens at this step at all. If this occurs, then try again in a few
306 minutes -- it could be an intermittant network problem. If the
307 problem persists, please ask for help.}
310 Close the lily-git GUI and navigate to the @file{$LILYPOND_GIT}
311 directory to view and edit the source files.
316 If this is the first time you have compiled LilyPond then please go
317 to @ref{Compiling with LilyDev} before reading on.
320 @node How to use lily-git
321 @unnumberedsubsec How to use lily-git
323 @warning{Throughout the rest of this manual, most command-line
324 input should be entered from @file{~/lilypond-git/}. This is
325 known as the @emph{top source directory} and is often referred to as
326 @var{$LILYPOND_GIT}.}
328 @warning{Only work on one set of changes at once. Do not start
329 work on any new changes until your first set has been accepted.}
331 @subsubheading 1. Update source
333 At the beginning of each session of lilypond work, you should
334 click the @qq{Update source} button to get the latest changes to
337 @warning{In some rare and unfortunate circumstances, this will
338 result in a @emph{merge conflict}. If this occurs, follow the
339 instructions for @qq{Abort changes}, below. Your work will not be
343 @subsubheading 2a. New local commit
345 A single commit typically represents one logical set of related
346 changes (such as a bug-fix), and may incorporate changes to
347 multiple files at the same time.
349 When you're finished making the changes for a commit, click the
350 @qq{New local commit} button. This will open the @qq{Git Commit
351 Message} window. The message header is required, and the message
354 After entering a commit message, click @qq{OK} to finalize the
357 @advanced{for more information regarding commits and commit
358 messages, see @ref{Commits and patches}.}
361 @subsubheading 2b. Amend previous commit
363 You can go back and make changes to the most recent commit with
364 the @qq{Amend previous commit} button. This is useful if a
365 mistake is found after you have clicked the @qq{New local commit}
368 To amend the most recent commit, re-edit the source files as
369 needed and then click the @qq{Amend previous commit} button. The
370 earlier version of the commit is not saved, but is replaced by the
373 @warning{This does not update the patch @strong{files}; if you
374 have a patch file from an earlier version of the commit, you will
375 need to make another patch set when using this feature. The old
376 patch file will not be saved, but will be replaced by the new one
377 after you click on @qq{Make patch set}.}
380 @subsubheading 3. Make patch set
382 Before making a patch set from any commits, you should click the
383 @qq{Update source} button to make sure the commits are based on
384 the most recent remote snapshot.
386 When you click the @qq{Make patch set} button,
387 @command{lily-git.tcl} will produce patch files for any new
388 commits, saving them to the current directory. The command output
389 will display the name of the new patch files near the end of the
393 0001-CG-add-lily-git-instructions.patch
397 Send patch files to the appropriate place:
401 If you have a mentor, send it to them via email.
404 Translators should send patches to
405 @email{translations@@lilynet.net}.
408 More experienced contributors should upload the patch for
409 web-based review. This requires additional software and use of
410 the command-line; see @ref{Uploading a patch for review}.
413 If you have trouble uploading the patch for review,
414 ask for help on @email{lilypond-devel@@gnu.org}.
419 @subsubheading The @qq{Abort changes -- Reset to origin} button
421 @warning{Only use this if your local commit history gets
422 hopelessly confused!}
424 The button labeled @qq{Abort changes -- Reset to origin} will copy
425 all changed files to a subdirectory of @file{$LILYPOND_GIT} named
426 @file{aborted_edits/}, and will reset the repository to the
427 current state of the remote repository (at @code{git.sv.gnu.org}).
431 @node Compiling with LilyDev
432 @section Compiling with LilyDev
434 LilyDev is our @q{remix} of Debian which contains all the
435 necessary dependencies to do lilypond development; for more
436 information, see @ref{LilyDev}.
438 @subsubheading Preparing the build
440 To prepare the build directory, enter (or copy&paste) the below
441 text. This should take less than a minute.
443 @c we heavily recommend the out-of-tree build; do not change this!
447 sh autogen.sh --noconfigure
453 @subsubheading Building @code{lilypond}
455 Compiling lilypond will likely take between 5 and 60 minutes,
456 depending on your computer's speed and available RAM. We
457 recommend that you minimize the terminal window while it is
458 building; this can have a non-negligible effect on compilation
462 cd $LILYPOND_GIT/build/
466 You may run the compiled @code{lilypond} with:
469 cd $LILYPOND_GIT/build/
470 out/bin/lilypond my-file.ly
473 @subsubheading Building the documentation
475 Compiling the documentation is a much more involved process, and
476 will likely take 2 to 10 hours.
479 cd $LILYPOND_GIT/build/
484 The documentation is put in @file{out-www/offline-root/}. You may
485 view the html files by entering the below text; we recommend that
486 you bookmark the resulting page:
489 firefox $LILYPOND_GIT/build/out-www/offline-root/index.html
492 @subsubheading Installing
494 Don't. There is no reason to install lilypond within LilyDev.
495 All development work can (and should) stay within the
496 @file{$LILYPOND_GIT} directory, and any personal composition
497 or typesetting work should be done with an official GUB release.
500 @subsubheading Problems and other options
502 To select different build options, or isolate certain parts of the
503 build, or to use multiple CPUs while building, read
506 In particular, contributors working on the documentation should be
507 aware of some bugs in the build system, and should read the
508 workarounds in @ref{Generating documentation}.
511 @node Now start work!
512 @section Now start work!
514 LilyDev users may now skip to the chapter which is aimed at
515 their intended contributions:
518 @item @ref{Documentation work}
519 @item @ref{Translating the documentation}
520 @item @ref{Website work}
521 @item @ref{Regression tests}
522 @item @ref{Programming work}
525 These chapters are mainly intended for people not using LilyDev,
526 but they contain extra information about the
527 @qq{behind-the-scenes} activities. We recommend that you read
528 these at your leisure, a few weeks after beginning work with
532 @item @ref{Working with source code}
533 @item @ref{Compiling}