+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@node Quick start
+@chapter Quick start
+
+Want to submit a patch for LilyPond? Great! This chapter is
+designed to let you do this as quickly and easily as possible.
+
+It is not possible to compile LilyPond on Windows, and extremely
+difficulty to compile it on MacOS X. We have therefore made a
+@q{remix} of Ubuntu which includes all necessary dependencies to
+compile both LilyPond and the documentation. This can be run
+inside a virtual machine without disturbing your main operating
+system.
+
+@advanced{experienced developers may prefer to use their own
+development environment. It may be instructive to skim over these
+instructions, but be aware that this chapter is intended for
+helpful users who may have never created a patch before.}
+
+@menu
+* Lilybuntu::
+* Using lily-git::
+@end menu
+
+@node Lilybuntu
+@section Lilybuntu
+
+text.
+
+@menu
+* Installing lilybuntu::
+* Configuring lilybuntu in virtualbox::
+* Using lilybuntu::
+@end menu
+
+@node Installing lilybuntu
+@subsection Installing lilybuntu
+
+@enumerate
+@item
+Install some virtualization software.
+
+Any virtualization tool can be used, but we recommend VirtualBox:
+
+@example
+@uref{http://@/www.virtualbox.org/@/wiki/@/Downloads}
+@end example
+
+In virtualization terminology, your main operating system is the
+@qq{host}, while lilybuntu is the @qq{guest}.
+
+@item
+Download the @file{lilybuntu2.iso} disk image: (approximately 1
+GB)
+
+@example
+@uref{http://files.lilynet.net/lilybuntu2.iso}
+@end example
+
+@advanced{There is a md5sum available:
+@uref{http://files.lilynet.net/lilybuntu2.iso.md5}}
+
+@item
+Install @file{lilybuntu2.iso} as the @qq{guest} operating system
+on your virtualized system.
+
+@itemize
+
+@item
+If possible, use at least 700 MB of RAM (1GB would be better) for
+the virtual machine, and use @qq{dynamically expanding storage}
+for the virtual hard drive. A complete compile of everything
+(code, docs, regression tests) can reach 10 GB.
+
+@item
+When @file{lilybuntu2.iso} boots, it shows an ISOLINUX
+@code{boot:} prompt. Type:
+
+@example
+install
+@end example
+
+@item
+At the @qq{Prepare disk space} stage, do not be afraid to select
+@qq{Erase and use the entire disk}, since this refers to your
+@emph{virtual disk}, not your machine's actual hard drive.
+
+@item
+When prompted to remove the installation CD, go to
+@clicksequence{Devices @click{} CD/DVD Devices} and de-select
+@file{lilybuntu2.iso}.
+
+@end itemize
+
+@advanced{
+The latest version of lilybuntu is based on Ubuntu 10.04.1; if you
+encounter any difficulties installing it, search for one of the
+many tutorials for installing that particular version of Ubuntu as
+a guest operating system.
+}
+
+@item
+Do any extra configuration for your virtualization software.
+
+We have additional instructions in
+@ref{Configuring lilybuntu in virtualbox}.
+
+If you use other virtualization software, then follow the normal
+procedures for your virtualization software with Ubuntu as the
+client.
+
+@advanced{not all hardware is supported in all virtualization
+tools. In particular, some contributors have reported problems
+with USB devices. If you would like to investigate further, then
+look for help for your virtualization tool using your normal OS as
+the @qq{host} and Ubuntu as the @qq{client}.}
+
+@end enumerate
+
+
+@node Configuring lilybuntu in virtualbox
+@subsection Configuring lilybuntu in virtualbox
+
+VirtualBox has extra @qq{guest additions} which can make the
+virtualization easier to use (full-screen, easy file sharing
+between host and guest operating systems, shared clipboards, etc).
+
+@enumerate
+
+@item
+In @emph{VirtualBox}, select @clicksequence{Devices @click{}
+Install Guest Additions...}.
+
+@item
+In @emph{Ubuntu}, select @clicksequence{Places @click{}
+VBOXADDITIONS_}. A file-system window will open.
+
+@item
+Double-click on the @file{autorun.sh} file, then select @qq{Run in
+Terminal}, and enter your password when prompted.
+
+@item
+Once the script is finished, restart Ubuntu to complete the
+installation.
+
+@item
+Set up any additional features, such as @q{Shared Folders} between
+your main operating system and ubuntu. Consult external
+documentation for this step.
+
+@advanced{If you do any kernel upgrades, you may need to re-run
+these VBOXADDITIONS instructions.}
+
+@end enumerate
+
+
+@node Using lilybuntu
+@subsection Using lilybuntu
+
+If you are not familiar with Linux, it may be beneficial to read a
+couple of @qq{introduction to Ubuntu} webpages.
+
+@itemize
+@item
+One particular change from Windows and MacOS X is that most
+software should be installed with your @qq{package manager}; this
+vastly simplifies the process of installing and configuring
+software. Go to @clicksequence{System @click{} Administration
+@click{} Synaptic Package Manager}.
+
+@item
+The rest of this manual assumes that you are using the
+command-line; go to @clicksequence{Applications @click{}
+Accessories @click{} Terminal}.
+
+@end itemize
+
+
+@c if you change this node name, you'll need to change the @ref in
+@c web/ and/or included/, along with all the translations.
+@node Using lily-git
+@section Using lily-git
+
+@command{lily-git.tcl} is a graphical tool to help you access and
+share changes to the lilypond source code.
+
+@menu
+* Install and configuration of lily-git.tcl::
+* Daily use of lily-git.tcl::
+@end menu
+
+@node Install and configuration of lily-git.tcl
+@unnumberedsubsec Install and configuration of @command{lily-git.tcl}
+
+@warning{The rest of this manual assumes that you are using the
+command-line; go to @clicksequence{Applications @click{}
+Accessories @click{} Terminal}.}
+
+@enumerate
+@item
+@code{lily-git.tcl} has already been install for you. Simply type
+(or copy&paste):
+
+@example
+cd
+wish lily-git.tcl
+@end example
+
+@item
+Click on the @qq{Get source} button.
+
+This will create a directory called @file{lilypond-git/} within
+your home directory, and will download the source code into that
+directory (around 55Mb). When the process is finished, the
+@qq{Command output} window will display @qq{Done}, and the button
+label will change to say @qq{Update source}.
+
+@item
+Navigate to the @file{lilypond-git/} directory to view the source
+files. You should now be able to modify the source files using
+your normal text editor.
+
+@end enumerate
+
+You should now progress to @ref{Compiling with lilybuntu}.
+
+@warning{Throughout the rest of this manual, most command-line
+input should be entered from @file{~/lilypond-git/}. This is
+referred to as the @emph{top source directory}.}
+
+
+@subsubheading Other operating music systems
+
+@enumerate
+@item
+If you haven't already, download and install Git.
+
+@itemize
+
+@item
+Lilybuntu users: git has already been installed for you.
+
+@item Windows users: download the @code{.exe} file labeled
+@qq{Full installer for official Git} from:
+
+@example
+@uref{http://code.google.com/p/msysgit/downloads/list}
+@end example
+
+@item Other operating systems: either install @command{git} with
+your package manager, or download it from the @qq{Binaries}
+section of:
+
+@example
+@uref{http://git-scm.com/download}
+@end example
+
+@end itemize
+
+
+@item
+Download the @command{lily-git.tcl} script from:
+
+@c don't change the cgit link below to gitweb; gitweb uses
+@c long filenames like "scripts_auxiliar_lily-git.tcl"
+
+@example
+@uref{http://git.sv.gnu.org/cgit/lilypond.git/plain/scripts/auxiliar/lily-git.tcl}
+@end example
+
+@item
+To run the program from the command line, navigate to the
+directory containing @command{lily-git.tcl} and enter:
+
+@example
+wish lily-git.tcl
+@end example
+
+@item
+Go read the lilybuntu instructions, starting from the @qq{get
+source} step.
+
+@end enumerate
+
+@advanced{the @qq{Get source} button does not fetch the entire
+history of the git repository, so utilities like @command{gitk}
+will only be able to display the most recent additions. As you
+continue to work with @command{lily-git.tcl}, the @qq{Update
+source} button will take any new additions and add it to whatever
+is currently in your repository's history.}
+
+
+@node Daily use of lily-git.tcl
+@unnumberedsubsec Daily use of @command{lily-git.tcl}
+
+@warning{Only work on one set of changes at once. Do not start
+work on any new changes until your first set has been accepted.}
+
+@subsubheading 1. Update source
+
+At the beginning of each session of lilypond work, you should
+click the @qq{Update source} button to get the latest changes to
+the source code.
+
+@warning{In some rare and unfortunate circumstances, this will
+result in a @emph{merge conflict}. If this occurs, follow the
+instructions for @qq{Abort changes}, below. Your work will not be
+lost.}
+
+
+@subsubheading 2a. New local commit
+
+A single commit typically represents one logical set of related
+changes (such as a bug-fix), and may incorporate changes to
+multiple files at the same time.
+
+When you're finished making the changes for a commit, click the
+@qq{New local commit} button. This will open the @qq{Git Commit
+Message} window. The message header is required, and the message
+body is optional.
+
+After entering a commit message, click @qq{OK} to finalize the
+commit.
+
+@advanced{for more information regarding commits and commit
+messages, see @ref{Commits and patches}.}
+
+
+@subsubheading 2b. Amend previous commit
+
+You can go back and make changes to the most recent commit with
+the @qq{Amend previous commit} button. This is useful if a
+mistake is found after you have clicked the @qq{New local commit}
+button.
+
+To amend the most recent commit, re-edit the source files as
+needed and then click the @qq{Amend previous commit} button. The
+earlier version of the commit is not saved, but is replaced by the
+new one.
+
+@warning{This does not update the patch @strong{files}; if you
+have a patch file from an earlier version of the commit, you will
+need to make another patch set when using this feature. The old
+patch file will not be saved, but will be replaced by the new one
+after you click on @qq{Make patch set}.}
+
+
+@subsubheading 3. Make patch set
+
+Before making a patch set from any commits, you should click the
+@qq{Update source} button to make sure the commits are based on
+the most recent remote snapshot.
+
+When you click the @qq{Make patch set} button,
+@command{lily-git.tcl} will produce patch files for any new
+commits, saving them to the current directory. The command output
+will display the name of the new patch files near the end of the
+output:
+
+@example
+0001-CG-add-lily-git-instructions.patch
+Done.
+@end example
+
+Send patch files to the appropriate place:
+
+@itemize
+@item
+If you have a mentor, send it to them via email.
+
+@item
+New contributors should send the patch attached to an email to
+@email{frogs@@lilynet.net}. Please add @qq{[PATCH]} to the
+subject line.
+
+@item
+Translators should send patches to
+@email{translations@@lilynet.net}.
+
+@item
+More experienced contributors should upload the patch for
+web-based review. This requires additional software and use of
+the command-line; see @ref{Uploading a patch for review}.
+
+@end itemize
+
+
+@subsubheading The @qq{Abort changes -- Reset to origin} button
+
+@warning{Only use this if your local commit history gets
+hopelessly confused!}
+
+The button labeled @qq{Abort changes -- Reset to origin} will copy
+all changed files to a subdirectory of @file{lilypond-git/} named
+@file{aborted_edits/}, and will reset the repository to the
+current state of the remote repository (at @code{git.sv.gnu.org}).
+
+
+
+
projects / lilypond.git / commitdiff