@menu
* LilyDev::
* lily-git::
+* git-cl::
* Compiling with LilyDev::
* Now start work!::
@end menu
@warning{LilyDev does not include the software for the Grand Unified
Builder -- also see @ref{Grand Unified Builder (GUB)}.}
-While compiling LilyPond on MacOs and Windows is possible, both
+While compiling LilyPond on Mac OS and Windows is possible, both
environments are complex to set up. LilyDev can be easily installed
and run inside a @q{virtual machine} on either of these operating
systems relatively easily using readily available virtualization
major operating systems and is very easy to install & configure.
The LilyDev disk image can also be written to a USB device or @q{burnt}
-to a DVD -- it is approximately 900 GB in size -- and installed just
+to a DVD -- it is approximately 900 MB in size -- and installed just
like any standard GNU/Linux distribution.
-The current image is based on a 32bit version of Debian 8 (@q{Jessie})
-and the Disk image was generated using Debian
+The current image is based on a 32-bit version of Debian 8 (@q{Jessie})
+and the disk image was generated using Debian
@uref{http://live.debian.net/, live-build 4}.
@noindent
-Download the LilyDev disk image file from here:
+Download the LilyDev disk image file (a @code{.iso} file) from here:
@example
@uref{https://github.com/fedelibre/LilyDev/releases/latest}
instructive to skim over the following information.}
If you are not familiar with GNU/Linux, it may be beneficial to read a
-a few @qq{introduction to Linux} type web pages.
+few @qq{introduction to Linux} type web pages.
@menu
* Installing LilyDev in VirtualBox::
@enumerate
@item
-Download Virtualbox from here:
+Download VirtualBox from here:
@example
@uref{http://www.virtualbox.org/wiki/Downloads}
@end example
@warning{In virtualization terminology, the operating system where
-Virtualbox is installed is known as the @strong{host}. LilyDev
-will be installed @q{inside} Virtualbox as a @strong{guest}.}
+VirtualBox is installed is known as the @strong{host}. LilyDev
+will be installed @q{inside} VirtualBox as a @strong{guest}.}
@item
Start the VirtualBox software and click @q{New} to create a new
@item
Verify the summary details and click @q{Create}, when you are satisfied.
-Your new guest will be displayed in the Virtualbox window.
+Your new guest will be displayed in the VirtualBox window.
@warning{The image contains a @q{686-pae} kernel, so you must enable
@code{PAE} within the virtual machine's settings -- click on
@item
Click the @q{Start} button and the @q{First Run Wizard} will prompt you
for the installation media. Click the browse icon, locate the LilyDev
-disk image and click through the wizard to begin the installation
-process.
+disk image file that you downloaded (the @code{.iso} file) and click
+through the wizard to begin the installation process.
@item
When the LilyDev disk image boots for the first time, choose either the
@unnumberedsubsec Configuring LilyDev in VirtualBox
VirtualBox has extra @q{guest additions} which although are not
-necessary to use LilyDev or compile Lilypond, do provide some additional
+necessary to use LilyDev or compile LilyPond, do provide some additional
features to your Virtual Machine to make it easier to work with. Such
as being able to dynamically resize the LilyDev window, allow seamless
interaction with your mouse pointer on both the host and guest and let
it.
@warning{Be patient! There is no progress bar in the lily-git UI but the
-complete source is around 180@tie{}Mb.}
+complete source is around 180@tie{}MB.}
@noindent
When the source code has been downloaded, the @qq{command output} window
commit.
@advanced{for more information regarding commits and commit
-messages, see @ref{Commits and patches}.}
+messages, see @ref{Commits}.}
@subsubheading 2b. Amend previous commit
current state of the remote repository (at @code{git.sv.gnu.org}).
+@node git-cl
+@section git-cl
+
+@menu
+* Installing git-cl::
+* Updating git-cl::
+* Configuring git-cl::
+@end menu
+
+Git-cl is a @q{helper script} that uploads patches to Google's Rietveld
+Code Review Tool -- used by the developers for patch review -- and, at
+the same time, updates LilyPond's issue tracker.
+
+
+@node Installing git-cl
+@unnumberedsubsec Installing @code{git-cl}
+
+@warning{LilyDev users can jump straight to the next section on updating
+@command{git-cl} as it will already be installed in your home
+directory.}
+
+@enumerate
+
+@item
+Download @command{git-cl} by running the command:
+
+@example
+git clone https://github.com/gperciva/git-cl.git
+@end example
+
+@noindent
+or, if that command fails for any reason, try:
+
+@example
+git clone git://github.com/gperciva/git-cl.git
+@end example
+
+@item
+Add the @file{git-cl/} directory to your @var{PATH} or create a symbolic
+link to the @command{git-cl} and @command{upload.py} scripts in one of
+your @var{PATH} directories (e.g. @file{$HOME/bin}).
+
+In GNU/Linux you can add directories to @var{PATH} by adding this line
+to your @file{.bashrc} file located in your home directory:
+
+@example
+PATH=~/directory_containing_git-cl:"$@{PATH@}"
+@end example
+
+@end enumerate
+
+
+@node Updating git-cl
+@unnumberedsubsec Updating @code{git-cl}
+
+LilyDev users should make sure that they always have the latest
+version of git-cl installed. It is possible that changes have been
+made to git-cl that are not (yet) included in the version of LilyDev
+that you are using.
+
+@noindent
+Using a terminal run the following commands:
+
+@example
+cd ~/git-cl/
+git pull
+@end example
+
+This will download and update you to the lastest version of git-cl.
+
+
+@node Configuring git-cl
+@unnumberedsubsec Configuring @code{git-cl}
+
+@subsubheading Set up login accounts
+
+Because @code{git-cl} updates two separate websites (Google's Rietveld
+Code Review Tool and LilyPond's issue tracker) you @emph{must} have a
+valid user account (login and password) for both sites.
+
+@noindent
+For the Rietveld Code Review Tool you will need a Google account. Note
+that a Google account does not require that you have or use a @q{Google}
+email address. You can use @emph{any} email address for your Google
+account. Just select the option @qq{I prefer to use my current email
+address} when you sign up.
+
+@warning{In order for @code{git-cl} to work, your Google Account
+Settings must have the @q{Access for less secure apps} set to
+@q{Allowed}. This is normally the default setting.}
+
+@noindent
+For the LilyPond issue tracker, please request a user account by sending
+an email to the LilyPond Developer's mailing list
+(@code{lilypond-devel@@gnu.org}), preferably using the same email
+address that you want to use for your user login.
+
+@subsubheading Authorizing git-cl for the LilyPond issue tracker
+
+The @code{git-cl} command itself also needs to be @q{authorized} so that
+it can access the LilyPond issue tracker.
+
+@enumerate
+@item
+Once you have been given a valid login for the LilyPond issue tracker,
+go to the @q{Account settings} and select the @q{OAuth} tab.
+
+@item
+Locate the @q{Register New Application} section and enter @code{git-cl}
+in the @q{Application Name:} field.
+
+@item
+Click on the @q{Register new application} button. You should now see
+@q{git-cl} listed under the @q{My Applications} section.
+
+@item
+Click on the @q{Generate Bearer Token} button. You should now see
+@q{git-cl} listed under the @q{Authorized Applications} section along
+with a value for the @q{Bearer Token} entry. This value is used, in the
+next steps, to allow git-cl to access and update the LilyPond issue
+tracker.
+
+@end enumerate
+
+@subsubheading Installing ca-certificates
+
+In order to have @code{git-cl} properly update issues on the SourceForge
+Allura issue tracker, you must have the package @code{ca-certificates}
+installed. You can check to see if the package is installed with
+
+@example
+apt --installed list | grep ca-certificates
+@end example
+
+If @code{ca-certificates} is installed, you will get a result that shows
+the version that is installed. If it is not installed, there will be
+no version displayed.
+
+Install @code{ca-certificates} with the following:
+
+@example
+sudo apt-get install ca-certificates
+@end example
+
+
+@subsubheading Running git-cl for the first time
+
+@enumerate
+@item
+Using a terminal, move to the top level of the @code{$LILYPOND_GIT}
+directory and then run @code{git-cl} with the @code{config} option:
+
+@example
+cd $LILYPOND_GIT
+git-cl config
+@end example
+
+@noindent
+You will see a series of prompts. For most of them you can simply
+accept the default value by responding with a newline (i.e. by pressing
+return or enter).
+
+@item
+The prompt for the @code{Rietveld server} (the patch review tool), which
+defaults to @code{codereview.appspot.com}
+
+@example
+Rietveld server (host[:port]) [codereview.appspot.com]:
+@end example
+
+@item
+The prompt for the @code{Allura server} (the issue tracker), which
+defaults to @code{https://sourceforge.net/p/testlilyissues/issues/}
+
+@example
+Allura server [https://sourceforge.net/p/testlilyissues/issues/]:
+@end example
+
+@item
+When prompted for the @code{Allura bearer token} copy/paste the value
+generated in the previous steps for
+@emph{Authorising git-cl for the LilyPond issue tracker}
+
+@smallexample
+Allura bearer token (see https://sourceforge.net/auth/oauth/): fdbfca60801533465480
+@end smallexample
+
+@warning{The above is a @q{fake} bearer token used just for
+illustration. Do not use this value.}
+
+@item
+Finally, the prompt for the @code{CC list}, which defaults to
+@code{lilypond-devel@@gnu.org}, the LilyPond Developer's email list.
+
+@example
+CC list ("x" to clear) [lilypond-devel@@gnu.org]:
+@end example
+
+@end enumerate
+
+The @code{git-cl} script should now be correctly configured for use.
+
@node Compiling with LilyDev
@section Compiling with LilyDev
LilyDev is our @q{remix} of Debian which contains all the
-necessary dependencies to do lilypond development; for more
+necessary dependencies to do LilyPond development; for more
information, see @ref{LilyDev}.
@subsubheading Preparing the build
@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.
+Compiling LilyPond will take anywhere between 1 and 15 minutes on most
+@q{modern} computers -- depending on CPU and available RAM. We also
+recommend that you minimize the terminal window while it is building;
+this can help speed up on compilation times.
@example
cd $LILYPOND_GIT/build/
make
@end example
+@noindent
+It is possible to run @code{make} with the @code{-j} option to help
+speed up compilation times even more. See @ref{Compiling LilyPond}
+
You may run the compiled @code{lilypond} with:
@example
@subsubheading Installing
-Don't. There is no reason to install lilypond within LilyDev.
+Don't. There is no reason to install LilyPond within LilyDev.
All development work can (and should) stay within the
@file{$LILYPOND_GIT} directory, and any personal composition
or typesetting work should be done with an official GUB release.
projects / lilypond.git / blobdiff