Merge branch 'master' into lilypond/translation

[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.

@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::
* Compiling with lilybuntu::
* Now start work!::
@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.

There are additional instructions for VirtualBox 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.

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

TODO: maybe we should just nuke this point?  is it easier to do
networked file sharing in osx, linux, etc, thus making the
virtualbox "shared folders" not useful?

@end itemize


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

@item
The rest of this manual assumes that you are using the
command-line; go to @clicksequence{Applications @click{}
Accessories @click{} Terminal}.

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

@item
Some contributors have recommended: (pdf available for free)

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

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

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



@node Compiling with lilybuntu
@section Compiling with lilybuntu

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

@subsubheading Preparing the build

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

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

@advanced{this is called an @qq{out-of-tree} build; we heavily
recommend this build method.}

@subsubheading Building @code{lilypond}

Compiling lilypond will likely take between 5 and 30 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 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 Other options

To select different build options, or isolate certain parts of the
build, or to use multiple CPUs while building, read the rest of
this chapter.


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

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

@itemize
@item @rcontrib{Documentation work}
@item @rcontrib{Translate the documentation}
@item @rcontrib{Website work}
@item @rcontrib{Regression tests}
@item @rcontrib{Programming work}
@end itemize