From 512542520ca60b7018df2de43e2c5f51bf05432c Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Fri, 17 Dec 2010 14:58:52 +0000 Subject: [PATCH] CG: move lilybuntu into new "quick start" chapter. --- .gitignore | 1 + Documentation/contributor.texi | 2 + Documentation/contributor/introduction.itexi | 152 +------ Documentation/contributor/quick-start.itexi | 401 +++++++++++++++++++ Documentation/contributor/source-code.itexi | 232 +---------- Documentation/included/helpus.itexi | 2 +- 6 files changed, 414 insertions(+), 376 deletions(-) create mode 100644 Documentation/contributor/quick-start.itexi diff --git a/.gitignore b/.gitignore index 2f4d094f74..e0fae2d1e4 100644 --- a/.gitignore +++ b/.gitignore @@ -77,3 +77,4 @@ RELEASE-COMMIT Documentation/lilypond semantic.cache .lock-wscript +build/ diff --git a/Documentation/contributor.texi b/Documentation/contributor.texi index 53f796a3e3..a9e3bd7751 100644 --- a/Documentation/contributor.texi +++ b/Documentation/contributor.texi @@ -50,6 +50,7 @@ Copyright @copyright{} 2007--2010 by the authors. @menu * Introduction to contributing:: +* Quick start:: * Working with source code:: * Compiling:: * Documentation work:: @@ -74,6 +75,7 @@ Appendices @allowcodebreaks false @include contributor/introduction.itexi +@include contributor/quick-start.itexi @include contributor/source-code.itexi @include contributor/compiling.itexi @include contributor/doc-work.itexi diff --git a/Documentation/contributor/introduction.itexi b/Documentation/contributor/introduction.itexi index 3aa9380fd8..c104cee175 100644 --- a/Documentation/contributor/introduction.itexi +++ b/Documentation/contributor/introduction.itexi @@ -11,7 +11,6 @@ help LilyPond. @menu * Help us:: * Overview of work flow:: -* Lilybuntu:: * Mentors:: @end menu @@ -75,9 +74,9 @@ interface is at Git is a complex and powerful tool, but tends to be confusing at first, particularly for users not familiar with the command line -and/or version control systems. Contributors who don't want to -deal with Git directly are encouraged to use the -@command{lily-git} graphical user interface instead. +and/or version control systems. We have created the +@command{lily-git} graphical user interface to ease this +difficulty. @emph{Compiling} (@q{building}) LilyPond allows developers to see how changes to the source code affect the program itself. @@ -98,149 +97,8 @@ the developers' mailing list here: @uref{http://lists.gnu.org/mailman/listinfo/lilypond-devel}. @warning{Contributors on Windows or MacOS X wishing to compile -code or documentation are strongly advised to use @ref{Lilybuntu} -instead of trying to install all software dependencies -themselves.} - - -@node Lilybuntu -@section Lilybuntu - -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. - -@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}. - -@item -Download the @file{lilybuntu2.iso} disk image: - -@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. - -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. - -@item -Set up any additional features, such as @q{Shared Folders} between -your main operating system and ubuntu. Consult external -documentation for this step. - -@advanced{If you do any kernel upgrades, you may need to re-run -these VBOXADDITIONS instructions.} - -@end enumerate - -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 - -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{System @click{} Administration -@click{} Synaptic Package Manager}. - -@item -The rest of this manual assumes that you are using the -command-line; go to @clicksequence{Applications @click{} -Accessories @click{} Terminal}. - -@end itemize - -You should now progress to @ref{Using lily-git}. +code or documentation are strongly advised to use lilybuntu, as +discussed in @ref{Quick start}.} @node Mentors diff --git a/Documentation/contributor/quick-start.itexi b/Documentation/contributor/quick-start.itexi new file mode 100644 index 0000000000..4bbb180f66 --- /dev/null +++ b/Documentation/contributor/quick-start.itexi @@ -0,0 +1,401 @@ +@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:: +@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. + +We have additional instructions 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. + +@item +Set up any additional features, such as @q{Shared Folders} between +your main operating system and ubuntu. Consult external +documentation for this step. + +@advanced{If you do any kernel upgrades, you may need to re-run +these VBOXADDITIONS instructions.} + +@end enumerate + + +@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{System @click{} Administration +@click{} Synaptic Package Manager}. + +@item +The rest of this manual assumes that you are using the +command-line; go to @clicksequence{Applications @click{} +Accessories @click{} Terminal}. + +@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 install 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. You should now be able to modify the source files using +your normal text editor. + +@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 music 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}). + + + + diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index 533eca6a10..65ac35e3b6 100644 --- a/Documentation/contributor/source-code.itexi +++ b/Documentation/contributor/source-code.itexi @@ -4,14 +4,13 @@ @node Working with source code @chapter Working with source code -New contributors should only read @ref{Using lily-git}. Please -ignore the rest of this chapter. +@warning{New contributors should read @ref{Quick start}, and in +particular @ref{Using lily-git}, instead of this chapter.} -Advanced contributors will find the rest of this material quite -useful, particularly if they are working on major new features. +Advanced contributors will find this material quite useful, +particularly if they are working on major new features. @menu -* Using lily-git:: * Starting with Git:: * Basic Git procedures:: * Advanced Git procedures:: @@ -21,232 +20,9 @@ useful, particularly if they are working on major new features. @end menu -@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} - -@subsubheading Lilybuntu - -@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 install 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. You should now be able to modify the source files using -your normal text editor. - -@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 music 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 Starting with Git @section Starting with Git - Using the Git program directly (as opposed to using the @command{lily-git.tcl} GUI) allows you to have much greater control over the contributing process. You should consider using Git if diff --git a/Documentation/included/helpus.itexi b/Documentation/included/helpus.itexi index 9bd73c5cab..e94c513aed 100644 --- a/Documentation/included/helpus.itexi +++ b/Documentation/included/helpus.itexi @@ -52,7 +52,7 @@ compile LilyPond. @warning{We suggest that contributors using Windows or MacOS X do @strong{not} attempt to set up their own development environment; -instead, use @rcontrib{Lilybuntu}.} +instead, use lilybuntu as discussed in @rcontrib{Quick start}.} Contributors using Linux or FreeBSD may also use Lilybuntu, but if they prefer their own development environment, they should read -- 2.39.2