X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fquick-start.itexi;h=d41b7ad3e7d06169474acdb3893a61e358cca418;hb=97a0169312a260933246ab224e4f8b0969871dd5;hp=e56eab872219a4d8d2d66461b1178fba662e197f;hpb=e49d6df0e5302762e33717571c408615d74f705d;p=lilypond.git diff --git a/Documentation/contributor/quick-start.itexi b/Documentation/contributor/quick-start.itexi index e56eab8722..d41b7ad3e7 100644 --- a/Documentation/contributor/quick-start.itexi +++ b/Documentation/contributor/quick-start.itexi @@ -3,311 +3,348 @@ @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.} +Want to submit a patch for LilyPond? Great! Never created a patch +before? Never compiled software before? No problem! This chapter is +for you and will help you do this as quickly and easily as possible. @menu -* Lilydev:: -* Using lily-git:: -* Compiling with lilydev:: +* LilyDev:: +* lily-git:: +* git-cl:: +* Compiling with LilyDev:: * Now start work!:: @end menu -@node Lilydev -@section Lilydev +@node LilyDev +@section LilyDev -This section discusses how to install and use the Ubuntu LilyPond -Development Remix. +@c This text was written based on LilyDev 4.0 - JL -@menu -* Installing lilydev:: -* Configuring lilydev in virtualbox:: -* Using lilydev:: -@end menu +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}). -@node Installing lilydev -@subsection Installing lilydev +@warning{LilyDev does not include the software for the Grand Unified +Builder -- also see @ref{Grand Unified Builder (GUB)}.} -@enumerate -@item -Install some virtualization software. +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}. -Any virtualization tool can be used, but we recommend VirtualBox: +@noindent +Download the LilyDev disk image file (a @code{.iso} file) from here: @example -@uref{http://@/www.virtualbox.org/@/wiki/@/Downloads} +@uref{https://github.com/fedelibre/LilyDev/releases/latest} @end example -In virtualization terminology, your main operating system is the -@qq{host}, while lilydev is the @qq{guest}. +@warning{Apart from installing and configuring LilyDev in VirtualBox, +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 +* Installing LilyDev in VirtualBox:: +* Configuring LilyDev in VirtualBox:: +@end menu + +@node Installing LilyDev in VirtualBox +@unnumberedsubsec Installing LilyDev in VirtualBox + +This section discusses how to install and use LilyDev with VirtualBox. + +@warning{If you already know how to install a virtual machine using a +disc image inside VirtualBox (or your own virtualization software) then +you can skip this section and go straight to @ref{lily-git}.} + +@enumerate @item -Download the Ubuntu LilyPond Developer Remix disk image: -(approximately 1 GB) +Download VirtualBox from here: @example -@uref{http://files.lilynet.net/ubuntu-lilydev-remix-1.1.iso} +@uref{http://www.virtualbox.org/wiki/Downloads} @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} -} +@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}.} @item -Create a music new @qq{virtual machine} inside your virtualization -software. +Start the VirtualBox software and click @q{New} to create a new +@qq{virtual machine}. -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. +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} 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 -Install @file{ubuntu-lilydev-remix-1.1.iso} as the @qq{guest} -operating system on your virtualized system. +Select the amount of RAM you will allow the LilyDev guest to use from +your host operating system when it is running. If possible, use at +least 700 MB of RAM; the more RAM you can spare from your host the +better, although LilyDev will currently use no more than 4 GB (4096 MB) +even if you are able to assign more. -@enumerate +@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. @item -When @file{ubuntu-lilydev-remix-1.1.iso} boots, it shows an -ISOLINUX @code{boot:} prompt. Type: +Verify the summary details and click @q{Create}, when you are satisfied. +Your new guest will be displayed in the VirtualBox window. -@example -install -@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}.} @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. +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 -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. -} +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 -Do any extra configuration for your virtualization software. +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. -There are additional instructions for VirtualBox in -@ref{Configuring lilydev in virtualbox}. +@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. -If you use other virtualization software, then follow the normal -procedures for your virtualization software with Ubuntu as the -client. +@item +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 -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}. +@noindent +LilyDev should now be installed and running! -@node Configuring lilydev in virtualbox -@subsection Configuring lilydev in virtualbox +@node Configuring LilyDev in VirtualBox +@unnumberedsubsec 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). +VirtualBox has extra @q{guest additions} which although are not +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 +you copy/paste between your host and guest if needed. @enumerate @item -In @emph{VirtualBox}, select @clicksequence{Devices @click{} -Install Guest Additions...}. +Select the @q{Devices} menu from the virtual machine window and choose +@q{Install Guest Additions...}. This will automount a CD which will +prompt you to autorun it. Click OK and follow the instructions. It is +recommended to reboot the guest when the installation is complete. -@item -In @emph{Ubuntu}, select @clicksequence{Places @click{} -VBOXADDITIONS_}. A file-system window will open. +Other virtualization software will also have their own @q{guest} +additions, follow the normal procedures for your virtualization software +with LilyDev as the client. @item -Double-click on the @file{autorun.sh} file, then select @qq{Run in -Terminal}, and enter your password when prompted. +Restart LilyDev to complete the installation of the guest additions. -@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}. +@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.} -@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: +@noindent +Other items that 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. +Bridged mode to allow you to access shared folders when using Windows +hosts. @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. +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 can be shared over a network instead. -@end itemize +@item +Pasting into a terminal is done with @code{Ctrl+Shift+v}. +@item +Right-click allows you to edit a file with the text editor (default +is Leafpad). -@node Using lilydev -@subsection Using lilydev +@end itemize -If you are not familiar with Linux, it may be beneficial to read a -couple of @qq{introduction to Ubuntu} webpages. +@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. -@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. +@node lily-git +@section lily-git -@item -Pasting into a terminal is done with @code{Ctrl+Shift+v}. +The @q{LilyPond Contributor's Git Interface} (otherwise known as +@command{lily-git.tcl}) is a simple-to-use GUI to help you download and +update the LilyPond source code as well as an aid to making software +patches. -@item -The @qq{Places} top-menu has shortcuts to a graphical -@qq{navigator} like Windows Explorer or the MacOS X Finder. +@menu +* Where to get lily-git:: +* Using lily-git to download the source code:: +* How to use lily-git:: +@end menu -@item -Right-click allows you to edit a file with gedit. We recommend -using gedit. +@node Where to get lily-git +@unnumberedsubsec Where to get lily-git +Depending on your development environment, lily-git may already be +installed on your computer. + +@itemize @item -Some contributors have recommended: (pdf available for free) +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 -@uref{http://www.ubuntupocketguide.com/} +# add lily-git to the PATH +PATH=$LILYPOND_GIT/scripts/auxiliar:"$@{PATH@}" @end example -@end itemize - - -@node Using lily-git -@section Using lily-git +@item +For those not using LilyDev, lily-git can be obtained by downloading +the software directly. See @ref{Manually installing lily-git.tcl}. -@command{lily-git.tcl} is a graphical tool to help you access and -share changes to the lilypond source code. +@item +lily-git is part of the LilyPond source code and is located in +@file{$LILYPOND_GIT/scripts/auxillar/lily-git.tcl}. -@menu -* Install and configuration of lily-git.tcl:: -* Daily use of lily-git.tcl:: -@end menu +@end itemize -@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.} +@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 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. -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}. +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! 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 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 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 +@warning{Some contributors have reported that occasionally nothing +happens at this step at all. If this occurs, then try again in a few +minutes -- it could be 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. +Close the lily-git GUI and navigate to the @file{lilypond-git} +directory to view and edit the source files. @end enumerate -You should now progress to @ref{Compiling with lilydev}. +@noindent +If this is the first time you will be attempting to compile LilyPond, +please see the section @ref{Compiling with LilyDev} before continuing. -@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 How to use lily-git +@unnumberedsubsec How to use lily-git +Here is a brief description of what each button does in the lily-git UI. -@node Daily use of lily-git.tcl -@unnumberedsubsec Daily use of @command{lily-git.tcl} +@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{Only work on one set of changes at once. Do not start -work on any new changes until your first set has been accepted.} +@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 @@ -325,7 +362,7 @@ 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}.} +messages, see @ref{Commits}.} @subsubheading 2b. Amend previous commit @@ -370,11 +407,6 @@ Send patch files to the appropriate place: @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}. @@ -384,6 +416,10 @@ 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}. +@item +If you have trouble uploading the patch for review, +ask for help on @email{lilypond-devel@@gnu.org}. + @end itemize @@ -393,18 +429,230 @@ the command-line; see @ref{Uploading a patch for review}. 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 -@node Compiling with lilydev -@section Compiling with lilydev +@menu +* Installing git-cl:: +* Updating git-cl:: +* Configuring git-cl:: +@end menu -Lilydev is our @q{remix} of Ubuntu which contains all the -necessary dependencies to do lilypond development; for more -information, see @rcontrib{Lilydev}. +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} + +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. + +@subsubheading Set up a login account for Rietveld Code Review Tool + +@noindent +For the Rietveld Code Review Tool you will need a Google account but +this does @emph{not} require @q{Google} email address; i.e. @emph{any} +email address for your Google account can be used. Just select the +option @qq{I prefer to use my current email address} when you sign up +with Google. + +@warning{In order for @code{git-cl} to work correctly with this Google +account, your Google Account Settings must have the +@q{Access for less secure apps} set to @q{Allowed} -- this is normally +the default setting.} + +@subsubheading Set up a login account for LilyPond's Issue Tracker + +@noindent +Please register a user account at +@code{https://sourceforge.net/user/registration} preferably using the +same email address that you want to use LilyPond Developer mailing list +login. + +@noindent +Once you have created this Sourceforge user account, send an email to +the LilyPond Developer's mailing list (@code{lilypond-devel@@gnu.org}) +asking for write access to the issue tracker along with your Sourceforce +@emph{Username} (not email address) and someone will then be able to set +this up for you. + +@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 +information, see @ref{LilyDev}. @subsubheading Preparing the build @@ -414,7 +662,7 @@ 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/ +cd $LILYPOND_GIT sh autogen.sh --noconfigure mkdir -p build/ cd build/ @@ -423,21 +671,24 @@ 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 @@ -447,7 +698,8 @@ Compiling the documentation is a much more involved process, and will likely take 2 to 10 hours. @example -cd ~/lilypond-git/build/ +cd $LILYPOND_GIT/build/ +make make doc @end example @@ -456,14 +708,14 @@ 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 +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. @@ -481,7 +733,7 @@ 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 +LilyDev users may now skip to the chapter which is aimed at their intended contributions: @itemize