X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fquick-start.itexi;fp=Documentation%2Fcontributor%2Fquick-start.itexi;h=526d415c1241f4ca26158d06bb7037eab63d97d4;hb=e90f0536f9be39ada0bef0aeb0d275dec3b2fb5b;hp=0000000000000000000000000000000000000000;hpb=a8c9e8a7ca320ab0df5fd32e717fd62cd7635ce6;p=lilypond.git

diff --git a/Documentation/contributor/quick-start.itexi b/Documentation/contributor/quick-start.itexi
new file mode 100644
index 0000000000..526d415c12
--- /dev/null
+++ b/Documentation/contributor/quick-start.itexi
@@ -0,0 +1,502 @@
+@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
+@qq{host}, while lilydev is the @qq{guest}.
+
+@item
+Download the Ubuntu LilyPond Developer Remix disk image:
+(approximately 1 GB)
+
+@example
+@uref{http://files.lilynet.net/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://files.lilynet.net/ubuntu-lilydev-remix-1.1.iso.md5}
+@c @*
+@c @uref{http://files.lilynet.net/ubuntu-lilydev-remix-1.0.iso.torrent}
+}
+
+@item
+Create a music 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 @qq{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
+@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.  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: (pdf available for free)
+
+@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 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}.
+
+@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}.}
+
+@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 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 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
+
+
+