@menu
* LilyDev::
* lily-git::
+* git-cl::
* Compiling with LilyDev::
* Now start work!::
@end menu
@node LilyDev
@section LilyDev
-There is a disk image of a @q{remix} of Ubuntu Linux available for
-download which includes all the necessary software and tools to compile
-both LilyPond and the documentation. Called the
-@qq{Ubuntu LilyPond Developer Remix}, but known simply as @qq{LilyDev}
-for short. Although it is not possible to compile LilyPond on Windows
-and extremely difficult on MacOS, LilyDev can be installed and run
-inside a @q{virtual machine} on any of these operating systems without
-disturbing your main operating system. The LilyDev disk image can also
-be burnt to a DVD and installed like any other Ubuntu Linux
-distribution.
+@c This text was written based on LilyDev 4.0 - JL
-Most virtualization software can be used but we recommend VirtualBox as
-it is available for all major operating systems and is easy to install
-& configure.
+There is a @q{remix} of Debian GNU/Linux -- known as @qq{LilyDev} for
+short -- which includes all the necessary software and tools to compile
+LilyPond, the documentation and the website (also see
+@ref{Website work}).
-If you are not familiar with Linux, it may be beneficial to read a
-couple of @qq{introduction to Ubuntu} web pages.
+@warning{LilyDev does not include the software for the Grand Unified
+Builder -- also see @ref{Grand Unified Builder (GUB)}.}
-Some contributors have recommended a free PDF:
+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
+software. We recommend using VirtualBox as it is available for all
+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 MB in size -- and installed just
+like any standard GNU/Linux distribution.
+
+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 (a @code{.iso} file) from here:
@example
-@uref{http://www.ubuntupocketguide.com/}
+@uref{https://github.com/fedelibre/LilyDev/releases/latest}
@end example
-For those interested, the LilyDev remix is currently based on a 32bit
-version of 10.04 LTS Ubuntu (Lucid Lynx).
-
@warning{Apart from installing and configuring LilyDev in VirtualBox,
-the rest of the chapter on assumes that you are comfortable using the
-command-line. While this chapter is intended for users who may have
-never created a patch or compiled software before, experienced
-developers (who prefer to use their own development environment) may
-still find it instructive to skim over this section.}
+the rest of the chapter assumes that you are comfortable using the
+command-line and is intended for users who may have never created a
+patch or compiled software before. More experienced developers (who
+prefer to use their own development environment) may still find it
+instructive to skim over the following information.}
+
+If you are not familiar with GNU/Linux, it may be beneficial to read a
+few @qq{introduction to Linux} type web pages.
@menu
-* Where to get LilyDev::
* Installing LilyDev in VirtualBox::
* Configuring LilyDev in VirtualBox::
@end menu
-@node Where to get LilyDev
-@unnumberedsubsec Where to get LilyDev
-
-Download the Ubuntu LilyPond Developer Remix CD image file
-(approximately 1 GB) from here:
-
-@smallexample
-@uref{http://www.philholmes.net/lilypond/LilyDev/ubuntu-LilyDev-remix-2.6.iso}
-@end smallexample
-
-Some advanced users might want this file too:
-@smallexample
-@uref{http://www.philholmes.net/lilypond/LilyDev/ubuntu-LilyDev-remix-2.6.iso.md5}
-@end smallexample
-(If you don't recognize what this file is, then you don't need it.)
-
-
@node Installing LilyDev in VirtualBox
@unnumberedsubsec Installing LilyDev in VirtualBox
@enumerate
@item
-Download Virtualbox from here:
+Download VirtualBox from here:
@example
-@uref{http://@/www.virtualbox.org/@/wiki/@/Downloads}
+@uref{http://www.virtualbox.org/wiki/Downloads}
@end example
@warning{In virtualization terminology, the operating system where
-Virtualbox is installed, is the 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
The @q{New Virtual Machine Wizard} will walk you through setting up your
guest virtual machine. Choose an appropriate name for your LilyDev
installation and select the @q{Linux} operating system. When selecting
-the @q{version} use @q{Ubuntu} if available (but not the @q{64 bit}
+the @q{version} choose @q{Debian (32 bit)} (don't use the @q{64 bit}
option). If you do not have that specific option choose @q{Linux 2.6}
(again do not choose any option that has 64 bit next to it).
@item
For your @q{Virtual Hard Disk}, leave the @q{Create new hard disk}
-option checked, use the default @q{VDI} and
-@qq{Dynamically allocated} options for the virtual hard drive. A
-complete compile of everything (code, docs, regression tests) can reach
-10 GB so size your virtual disk and its location accordingly.
+option checked, use the default @q{VDI} and @qq{Dynamically allocated}
+options for the virtual hard drive. A complete compile of everything
+(code, docs, regression tests) can reach 10 GB so size your virtual disk
+and its location accordingly.
@item
Verify the summary details and click @q{Create}, when you are satisfied.
-Your new guest will be displayed in the Virtualbox window. Click the
-@q{Start} button and the @q{First Run Wizard} will prompt you for
-the installation media. Click the browse icon and locate the LilyDev
-disk image and click through the wizard to start the installation
-process.
+Your new guest will be displayed in the VirtualBox window.
-@item
-When the LilyDev disk image boots, it shows a prompt:
-
-@example
-ISOLINUX @code{boot:}
-@end example
+@warning{The image contains a @q{686-pae} kernel, so you must enable
+@code{PAE} within the virtual machine's settings -- click on
+@clicksequence{System @click{} Processor} and select
+@q{Extended features: Enable PAE/NX}.}
-Hit the Return key (or wait 30 seconds) and then when the installer
-screen loads, using the arrow keys select
-@q{Install - start the installer directly} to begin the install process
-of LilyDev on your virtual hard disk. The Ubuntu software will walk you
-through the complete installation process.
+@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 file that you downloaded (the @code{.iso} file) and click
+through the wizard to begin the installation process.
@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
-disk.
+When the LilyDev disk image boots for the first time, choose either the
+@q{Install} or the @q{Graphical install} menu item. The installer will
+then walk you through the complete installation process.
@item
-Click through the rest of the wizard, filling in any appropriate details
-when asked and wait for the install to complete.
+At the @qq{Partition disks} stage, do not be afraid to select
+@qq{Guided - use entire disk}, since this refers to your
+@strong{@emph{virtual disk}}, not your computer's own hard disk.
-@warning{This will take anywhere from 10 minutes to up to an hour
-depending on the speed of your computer and if Ubuntu detects you are
-connected to the internet and needs to download any additional
-security updates or patches, although these updates are not required to
-compile LilyPond and it is possible to skip the additional downloads to
-speed up the install process.}
+@item
+Continue to click through the rest of the wizard, filling in any
+appropriate details when asked, and wait for the install to complete.
+This will take about 10 minutes or so on a reasonably modern computer.
@item
-When prompted by the Ubuntu installer wizard, restart the virtual
-machine and then when prompted to @q{eject the CD} by virtual box, just
-click inside the virtual machine window and hit the return key to
-reboot the virtual machine. It will not try to restart the installer
-but start the virtual machine proper. LilyDev is now installed and
-running!
+When the installation is completed, just click on @q{Continue} (you
+do not have to remove any media since you installed LilyDev from a Disk
+image, which is just a file on your computer). The installer will
+reboot the virtual machine.
@end enumerate
-@knownissues
-Not all hardware is supported in all virtualization tools. In
-particular, some contributors have reported problems with 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. Refer to the
-help documentation that comes with your virtualization software.
+@noindent
+LilyDev should now be installed and running!
@node Configuring LilyDev in VirtualBox
@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
Other virtualization software will also have their own @q{guest}
additions, follow the normal procedures for your virtualization software
-with Ubuntu as the client.
+with LilyDev as the client.
@item
-Restart Ubuntu to complete the installation of the guest additions.
+Restart LilyDev to complete the installation of the guest additions.
-@advanced{If you do any kernel upgrades, you may need to reinstall
-the additional software. Just follow the step above again and reboot
-when the reinstallation is complete.}
+@advanced{If you do any kernel upgrades, you may need to reinstall the
+additional software. Just follow the step above again and reboot when
+the reinstallation is complete.}
@end enumerate
@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 the external
-documentation for this.
+your main operating system and LilyDev. This is distinct from the
+networked share folders in Windows. Consult the external documentation
+for this.
Some longtime contributors have reported that @q{shared folders}
are rarely useful and not worth the fuss, particularly since files
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
-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}.
+Right-click allows you to edit a file with the text editor (default
+is Leafpad).
@end itemize
+@knownissues
+Not all hardware is supported in all virtualization tools. In
+particular, some contributors have reported problems with 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. Refer to the
+help documentation that comes with your virtualization software.
+
@node lily-git
@section lily-git
@menu
* Where to get lily-git::
-* Configuring lily-git and downloading the source code::
+* Using lily-git to download the source code::
* How to use lily-git::
@end menu
@itemize
@item
-If you are using LilyDev (see @ref{LilyDev}) then lily-git is already
-installed and ready to run.
+If you are using LilyDev (see @ref{LilyDev}) then lily-git should
+already be installed and ready to run. If this is not the case you can
+easily turn it on by adding the following line in @code{~/.bashrc}:
+
+@example
+# add lily-git to the PATH
+PATH=$LILYPOND_GIT/scripts/auxiliar:"$@{PATH@}"
+@end example
@item
-For those not using LilyDev then lily-git can be obtained by downloading
+For those not using LilyDev, lily-git can be obtained by downloading
the software directly. See @ref{Manually installing lily-git.tcl}.
@item
-Finally, lily-git is always part of the LilyPond source code and is
-located in @file{~/lilypond-git/scripts/auxillar/lily-git.tcl}.
+lily-git is part of the LilyPond source code and is located in
+@file{$LILYPOND_GIT/scripts/auxillar/lily-git.tcl}.
@end itemize
-@node Configuring lily-git and downloading the source code
-@unnumberedsubsec Configuring lily-git and downloading the source code
-
-@warning{The rest of this manual assumes that you are using the
-command-line within a terminal.}
+@node Using lily-git to download the source code
+@unnumberedsubsec Using lily-git to download the source code
@enumerate
@item
-Type (or copy&paste) into the Terminal:
+Type the following command into a Terminal:
@example
lily-git.tcl
@end example
@noindent
-You will be prompted to enter your name and your email address. This
-information is used only to identify and label any patches you create.
-This information can be edited if required later. See
-@ref{Configuring Git}. Click on the @emph{Submit} button to update
-lily-git with this information.
+You will be prompted to enter a name and email address into the lily-git
+UI. This information is used to label any patches you create (using the
+lily-git UI or git via the command line) and can be changed later if
+required. See @ref{Configuring Git}.
+
+@item
+Click on the @emph{Submit} button to update lily-git with the
+information.
@item
Click on the @qq{Get source} button.
-A directory called @file{lilypond-git/} is now created within
-your home directory and the complete source code will start to be
-downloaded into it.
+A directory called @file{lilypond-git} is created within your home
+directory and the entire source code will start to be downloaded into
+it.
-@warning{Be patient! The complete source is around 150@tie{}Mb.}
+@warning{Be patient! There is no progress bar in the lily-git UI but the
+complete source is around 180@tie{}MB.}
@noindent
-When the source code has been downloaded, the @qq{Command output} window
-in lily-git will update and display @qq{Done} on the very last line.
-The button label will change to say @qq{Update source}.
+When the source code has been downloaded, the @qq{command output} window
+in the lily-git UI will update and display @qq{Done} on the very last
+line and the button label will change to say @qq{Update source}.
@warning{Some contributors have reported that occasionally nothing
happens at this step at all. If this occurs, then try again in a few
problem persists, please ask for help.}
@item
-Close the lily-git GUI and navigate to the @file{lilypond-git/}
+Close the lily-git GUI and navigate to the @file{lilypond-git}
directory to view and edit the source files.
@end enumerate
@noindent
-If this is the first time you have compiled LilyPond then please go
-to @ref{Compiling with LilyDev} before reading on.
+If this is the first time you will be attempting to compile LilyPond,
+please see the section @ref{Compiling with LilyDev} before continuing.
@node How to use lily-git
@unnumberedsubsec How to use lily-git
-@warning{Throughout the rest of this manual, most command-line
-input should be entered from @file{~/lilypond-git/}. This is
-known as the @emph{top source directory} and is often referred to as
-@var{$LILYPOND_GIT}}.
+Here is a brief description of what each button does in the lily-git UI.
-@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.}
+@advanced{Throughout the rest of this manual, most command-line
+input should be entered from within the top level of the
+@file{~/lilypond-git/} directory. This is known as the
+@emph{top of the source directory} and is also referred to as
+@var{$LILYPOND_GIT} as a convention for those users who may have
+configured their own locations of the LilyPond source code.}
+
+@warning{For those less experienced contributors using lily-git, we
+recommend that you only work on one set of changes at a time and not
+start 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.
+Click the @qq{Update source} button to get any recent changes to the
+source code that have been added by other contributors since your last
+session.
-@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.}
+@warning{If another contributor has updated files in the source code
+that you had been working on then updating your own copy of the source
+code may result in what is known as a @emph{merge conflict}. If this
+occurs, follow the instructions to @qq{Abort changes}, below. Note that
+your work will not be lost.}
@subsubheading 2a. New local commit
@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}.
web-based review. This requires additional software and use of
the command-line; see @ref{Uploading a patch for review}.
+@item
+If you have trouble uploading the patch for review,
+ask for help on @email{lilypond-devel@@gnu.org}.
+
@end itemize
hopelessly confused!}
The button labeled @qq{Abort changes -- Reset to origin} will copy
-all changed files to a subdirectory of @file{lilypond-git/} named
+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 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 always make sure that they alwsys have the latest
+version of git-cl installed. It is possible that changes may have been
+made to git-cl that are not (yet) included in the version of LilyDev has
+been installed.
+
+@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 the @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 login and password to both sites.
+
+@noindent
+Although that it may appear that you have to use a @q{Google} email
+address for the Rietveld Code Review Tool when you sign up, you can
+instead select the option @qq{I prefer to use my current email address}
+during sign up.
+
+@noindent
+For a user login to the LilyPond issue tracker, please send your
+request, preferably using the email address you want to use for your
+login, to the LilyPond Developer's mailing list
+(@code{lilypond-devel@@gnu.org}).
+
+@subsubheading Authorising 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 a valid login has been given for the LilyPond issye 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 Running git-cl for the first time
+
+@enumerate
+@item
+Using a terminal, move to top source directory 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
+
+@item
+When prompted for the @code{Rietveld server}:
+
+@example
+Rietveld server (host[:port]) [codereview.appspot.com]:
+@end example
+
+@item
+When prompted for the @code{Allura server} (the LilyPond issue tracker):
+
+@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 just to illustrate the
+example. Do not use this value.}
+
+@item
+Finally, when prompted for the @code{CC list} entry, add the LilyPond
+Developer's group email.
+
+@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 Ubuntu which contains all the
-necessary dependencies to do lilypond development; for more
-information, see @rcontrib{LilyDev}.
+LilyDev is our @q{remix} of Debian which contains all the
+necessary dependencies to do LilyPond development; for more
+information, see @ref{LilyDev}.
@subsubheading Preparing the build
@c we heavily recommend the out-of-tree build; do not change this!
@example
-cd ~/lilypond-git/
+cd $LILYPOND_GIT
sh autogen.sh --noconfigure
mkdir -p build/
cd 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/
+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
-cd ~/lilypond-git/build/
+cd $LILYPOND_GIT/build/
out/bin/lilypond my-file.ly
@end example
will likely take 2 to 10 hours.
@example
-cd ~/lilypond-git/build/
+cd $LILYPOND_GIT/build/
make
make doc
@end example
you bookmark the resulting page:
@example
-firefox ~/lilypond-git/build/out-www/offline-root/index.html
+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.
+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
+@file{$LILYPOND_GIT} directory, and any personal composition
or typesetting work should be done with an official GUB release.
projects / lilypond.git / blobdiff