Doc: CG: add instructions for staging branch

[lilypond.git] / Documentation / contributor / quick-start.itexi

@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.  The full name is @qq{Ubuntu LilyPond Developer Remix},
but we refer to it as @qq{lilydev} for short.

@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
* Lilydev::
* Using lily-git::
* Compiling with lilydev::
* Now start work!::
@end menu

@node Lilydev
@section Lilydev

This section discusses how to install and use the Ubuntu LilyPond
Development Remix.

@menu
* Installing lilydev::
* Configuring lilydev in virtualbox::
* Using lilydev::
@end menu

@node Installing lilydev
@subsection Installing lilydev

@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
@strong{host}, while lilydev is the @strong{guest}.

@item
Download the Ubuntu LilyPond Developer Remix disk image:
(approximately 1 GB)

@example
@uref{http://www.et.byu.edu/~sorensen/ubuntu-lilydev-remix-1.1.iso}
@end example

@advanced{Some users might want these files, but if you don't
recognize what they are, then you don't want them:
@*
@uref{http://www.et.byu.edu/~sorensen/ubuntu-lilydev-remix-1.1.iso.md5}
@c @*
@c @uref{http://files.lilynet.net/ubuntu-lilydev-remix-1.0.iso.torrent}
}

@item
Create a new @qq{virtual machine} inside your virtualization
software.

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
Install @file{ubuntu-lilydev-remix-1.1.iso} as the @strong{guest}
operating system on your virtualized system.

@enumerate

@item
When @file{ubuntu-lilydev-remix-1.1.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
@strong{@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{ubuntu-lilydev-remix-1.1.iso}.

@end enumerate

@advanced{
The latest version of lilydev 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.

There are additional instructions for VirtualBox in
@ref{Configuring lilydev in virtualbox}.

If you use other virtualization software, then follow the normal
procedures for your virtualization software with Ubuntu as the
client.

@end enumerate

@knownissues

Not all hardware is supported in all virtualization tools.  In
particular, some contributors have reported problems with USB
devices, for example USB network adapters.  If you have problems
with network connection (for example internet connection in the
host system is lost when you launch virtual system), try installing
and running Lilydev with your computer's built-in network adapter
used to connect to the network.
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}.


@node Configuring lilydev in virtualbox
@subsection Configuring lilydev 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, @qq{eject} the virtual CD, and then
go to @clicksequence{Devices @click{} CD/DVD Devices} and
de-select @file{VBoxGuestAdditions.iso}.

@item
Restart Ubuntu to complete the installation.

@advanced{If you do any kernel upgrades, you may need to re-run
these VBOXADDITIONS instructions.}
@end enumerate

Some other steps may be helpful:

@itemize
@item
In the settings for the virtual machine, set the network to
Bridged mode to allow you to access shared folders on your Windows
host.

@item
Set up any additional features, such as @q{Shared Folders} between
your main operating system and ubuntu.  This is distinct from the
networked share folders in Windows.  Consult external
documentation for this step.

Some longtime contributors have reported that @q{shared folders}
are rarely useful and not worth the fuss, particularly since files
can be shared over a network instead.

@end itemize


@node Using lilydev
@subsection Using lilydev

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{Applications @click{} Ubuntu
Software Center}.

@item
The rest of this manual assumes that you are using the
command-line; double-click on the @q{Terminal} icon on the
desktop.

@item
Pasting into a terminal is done with @code{Ctrl+Shift+v}.

@item
The @qq{Places} top-menu has shortcuts to a graphical
@qq{navigator} like Windows Explorer or the MacOS X Finder.

@item
Right-click allows you to edit a file with gedit.  We recommend
using gedit.

@item
Some contributors have recommended a free pdf:

@example
@uref{http://www.ubuntupocketguide.com/}
@end example

@end itemize


@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; double-click on the @q{Terminal} icon on the
desktop.}

@enumerate
@item
Type (or copy&paste) into the Terminal:

@example
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 150@tie{}Mb).  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}.

@warning{Some contributors have reported that nothing happens at
this step.  If this occurs, then try again in a few minutes -- we
suspect that this is an intermittant network problem.  If the
problem persists, please ask for help.}

@item
Navigate to the @file{lilypond-git/} directory to view the source
files.

@end enumerate

You should now progress to @ref{Compiling with lilydev}.

@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}.}


@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}).



@node Compiling with lilydev
@section Compiling with lilydev

Lilydev is our @q{remix} of Ubuntu which contains all the
necessary dependencies to do lilypond development; for more
information, see @rcontrib{Lilydev}.

@subsubheading Preparing the build

To prepare the build directory, enter (or copy&paste) the below
text.  This should take less than a minute.

@c we heavily recommend the out-of-tree build; do not change this!

@example
cd ~/lilypond-git/
sh autogen.sh --noconfigure
mkdir -p build/
cd build/
../configure
@end example

@subsubheading Building @code{lilypond}

Compiling lilypond will likely take between 5 and 60 minutes,
depending on your computer's speed and available RAM.  We
recommend that you minimize the terminal window while it is
building; this can have a non-negligible effect on compilation
speed.

@example
cd ~/lilypond-git/build/
make
@end example

You may run the compiled @code{lilypond} with:

@example
cd ~/lilypond-git/build/
out/bin/lilypond my-file.ly
@end example

@subsubheading Building the documentation

Compiling the documentation is a much more involved process, and
will likely take 2 to 10 hours.

@example
cd ~/lilypond-git/build/
make
make doc
@end example

The documentation is put in @file{out-www/offline-root/}.  You may
view the html files by entering the below text; we recommend that
you bookmark the resulting page:

@example
firefox ~/lilypond-git/build/out-www/offline-root/index.html
@end example

@subsubheading Installing

Don't.  There is no reason to install lilypond within lilydev.
All development work can (and should) stay within the
@file{$HOME/lilypond-git/} directory, and any personal composition
or typesetting work should be done with an official GUB release.


@subsubheading Problems and other options

To select different build options, or isolate certain parts of the
build, or to use multiple CPUs while building, read
@ref{Compiling}.

In particular, contributors working on the documentation should be
aware of some bugs in the build system, and should read the
workarounds in @ref{Generating documentation}.


@node Now start work!
@section Now start work!

Lilydev users may now skip to the chapter which is aimed at
their intended contributions:

@itemize
@item @ref{Documentation work}
@item @ref{Translating the documentation}
@item @ref{Website work}
@item @ref{Regression tests}
@item @ref{Programming work}
@end itemize

These chapters are mainly intended for people not using LilyDev,
but they contain extra information about the
@qq{behind-the-scenes} activities.  We recommend that you read
these at your leisure, a few weeks after beginning work with
LilyDev.

@itemize
@item @ref{Working with source code}
@item @ref{Compiling}
@end itemize