From 7c7244befe5572b1eba7cd34f40d586178ca4e06 Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Mon, 20 Dec 2010 17:22:36 +0000 Subject: [PATCH] CG: updates for ubuntu lilydev remix. --- .../contributor/administration.itexi | 6 +- Documentation/contributor/introduction.itexi | 4 +- Documentation/contributor/quick-start.itexi | 190 +++++++----------- Documentation/contributor/source-code.itexi | 86 ++++++++ 4 files changed, 167 insertions(+), 119 deletions(-) diff --git a/Documentation/contributor/administration.itexi b/Documentation/contributor/administration.itexi index 15a6612c11..8dbc9eb68f 100644 --- a/Documentation/contributor/administration.itexi +++ b/Documentation/contributor/administration.itexi @@ -277,7 +277,7 @@ We often receive reports of typos and minor text updates to the documentation. It would be great if somebody could create properly-formatted patches for these corrections. -Technical requirements: ability to run @ref{Lilybuntu}. +Technical requirements: ability to run @ref{Lilydev}. @item LSR editor: LSR contains many useful examples of lilypond, but some snippets @@ -294,7 +294,7 @@ chapters 1 and 2 (or be willing to read the docs to find out). often find them in Ponds of Lilies) and new feature implementors. Technical requirements: development environment (such as -@ref{Lilybuntu}), ability to read+write scheme and/or C++ code. +@ref{Lilydev}), ability to read+write scheme and/or C++ code. @end itemize @@ -831,7 +831,7 @@ discuss giving them push access. Unsolicited requests from contributors for access will almost always be turned down. -@subsubheading Creating the @strong{Lilybuntu} respin +@subsubheading Creating the @strong{Lilydev} respin @enumerate diff --git a/Documentation/contributor/introduction.itexi b/Documentation/contributor/introduction.itexi index c104cee175..cf7e2b7978 100644 --- a/Documentation/contributor/introduction.itexi +++ b/Documentation/contributor/introduction.itexi @@ -97,8 +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 lilybuntu, as -discussed in @ref{Quick start}.} +code or documentation are strongly advised to use our Ubuntu +LilyPond Developer Remix, as discussed in @ref{Quick start}.} @node Mentors diff --git a/Documentation/contributor/quick-start.itexi b/Documentation/contributor/quick-start.itexi index 18ef51379c..9a370e24ac 100644 --- a/Documentation/contributor/quick-start.itexi +++ b/Documentation/contributor/quick-start.itexi @@ -11,7 +11,8 @@ 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. +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 @@ -19,25 +20,25 @@ instructions, but be aware that this chapter is intended for helpful users who may have never created a patch before.} @menu -* Lilybuntu:: +* Lilydev:: * Using lily-git:: -* Compiling with lilybuntu:: +* Compiling with lilydev:: * Now start work!:: @end menu -@node Lilybuntu -@section Lilybuntu +@node Lilydev +@section Lilydev text. @menu -* Installing lilybuntu:: -* Configuring lilybuntu in virtualbox:: -* Using lilybuntu:: +* Installing lilydev:: +* Configuring lilydev in virtualbox:: +* Using lilydev:: @end menu -@node Installing lilybuntu -@subsection Installing lilybuntu +@node Installing lilydev +@subsection Installing lilydev @enumerate @item @@ -50,33 +51,39 @@ Any virtualization tool can be used, but we recommend VirtualBox: @end example In virtualization terminology, your main operating system is the -@qq{host}, while lilybuntu is the @qq{guest}. +@qq{host}, while lilydev is the @qq{guest}. @item -Download the @file{lilybuntu2.iso} disk image: (approximately 1 -GB) +Download the Ubuntu LilyPond Developer Remix disk image: +(approximately 1 GB) @example -@uref{http://files.lilynet.net/lilybuntu2.iso} +@uref{http://files.lilynet.net/ubuntu-lilydev-remix-1.0.iso} @end example -@advanced{There is a md5sum available: -@uref{http://files.lilynet.net/lilybuntu2.iso.md5}} +@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.0.iso.md5} +@uref{http://files.lilynet.net/ubuntu-lilydev-remix-1.0.iso.torrent} +} @item -Install @file{lilybuntu2.iso} as the @qq{guest} operating system -on your virtualized system. - -@itemize +Create a new @qq{virtual machine} inside your virtualization +software. -@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 +Install @file{lilydev2.iso} as the @qq{guest} operating system +on your virtualized system. + +@enumerate + +@item +When @file{lilydev2.iso} boots, it shows an ISOLINUX @code{boot:} prompt. Type: @example @@ -91,12 +98,12 @@ At the @qq{Prepare disk space} stage, do not be afraid to select @item When prompted to remove the installation CD, go to @clicksequence{Devices @click{} CD/DVD Devices} and de-select -@file{lilybuntu2.iso}. +@file{lilydev2.iso}. -@end itemize +@end enumerate @advanced{ -The latest version of lilybuntu is based on Ubuntu 10.04.1; if you +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. @@ -106,23 +113,25 @@ a guest operating system. Do any extra configuration for your virtualization software. There are additional instructions for VirtualBox in -@ref{Configuring lilybuntu in virtualbox}. +@ref{Configuring lilydev in virtualbox}. If you use other virtualization software, then follow the normal procedures for your virtualization software with Ubuntu as the client. -@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 +@knownissues + +Not all hardware is supported in all virtualization tools. In +particular, some contributors have reported problems with USB +devices. If you would like to investigate further, then look for +help for your virtualization tool using your normal OS as the +@qq{host} and Ubuntu as the @qq{client}. + -@node Configuring lilybuntu in virtualbox -@subsection Configuring lilybuntu in virtualbox +@node Configuring lilydev in virtualbox +@subsection Configuring lilydev in virtualbox VirtualBox has extra @qq{guest additions} which can make the virtualization easier to use (full-screen, easy file sharing @@ -143,8 +152,12 @@ 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. +Once the script is finished, @qq{eject} the virtual CD, and then +go to @clicksequence{Devices @click{} CD/DVD Devices} and +de-select @file{VBoxGuestAdditions.iso}. + +@item +Restart Ubuntu to complete the installation. @advanced{If you do any kernel upgrades, you may need to re-run these VBOXADDITIONS instructions.} @@ -164,15 +177,15 @@ your main operating system and ubuntu. This is distinct from the networked share folders in Windows. Consult external documentation for this step. -TODO: maybe we should just nuke this point? is it easier to do -networked file sharing in osx, linux, etc, thus making the -virtualbox "shared folders" not useful? +Some longtime contributors have reported that @q{shared folders} +are rarely useful and not worth the fuss, particularly since files +can be shared over a network instead. @end itemize -@node Using lilybuntu -@subsection Using lilybuntu +@node Using lilydev +@subsection Using lilydev If you are not familiar with Linux, it may be beneficial to read a couple of @qq{introduction to Ubuntu} webpages. @@ -187,12 +200,20 @@ Software Center}. @item The rest of this manual assumes that you are using the -command-line; go to @clicksequence{Applications @click{} -Accessories @click{} Terminal}. +command-line; double-click on the @q{Terminal} icon on the +desktop. @item Pasting into a terminal is done with @code{Ctrl+Shift+v}. +@item +The @qq{Places} top-menu has shortcuts to a graphical +@qq{navigator} like Windows Explorer or the MacOS X Finder. + +@item +Right-click allows you to edit a file with gedit. We recommend +using gedit. + @item Some contributors have recommended: (pdf available for free) @@ -203,8 +224,6 @@ Some contributors have recommended: (pdf available for free) @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 @@ -220,17 +239,15 @@ share changes to the lilypond source code. @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}.} +command-line; double-click on the @q{Terminal} icon on the +desktop.} @enumerate @item -@code{lily-git.tcl} has already been installed for you. Simply type -(or copy&paste): +Type (or copy&paste) into the Terminal: @example -cd -wish lily-git.tcl +lily-git.tcl @end example @item @@ -248,66 +265,12 @@ files. @end enumerate -You should now progress to @ref{Compiling with lilybuntu}. +You should now progress to @ref{Compiling with lilydev}. @warning{Throughout the rest of this manual, most command-line input should be entered from @file{~/lilypond-git/}. This is referred to as the @emph{top source directory}.} - -@subsubheading Other operating 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 @@ -423,18 +386,20 @@ current state of the remote repository (at @code{git.sv.gnu.org}). -@node Compiling with lilybuntu -@section Compiling with lilybuntu +@node Compiling with lilydev +@section Compiling with lilydev -Lilybuntu is our @q{remix} of Ubuntu which contains all the +Lilydev is our @q{remix} of Ubuntu which contains all the necessary dependencies to do lilypond development; for more -information, see @rcontrib{Lilybuntu}. +information, see @rcontrib{Lilydev}. @subsubheading Preparing the build To prepare the build directory, enter (or copy&paste) the below text. This should take less than a minute. +@c we heavily recommend the out-of-tree build; do not change this! + @example cd ~/lilypond-git/ sh autogen.sh --noconfigure @@ -443,9 +408,6 @@ cd build/ ../configure @end example -@advanced{this is called an @qq{out-of-tree} build; we heavily -recommend this build method.} - @subsubheading Building @code{lilypond} Compiling lilypond will likely take between 5 and 30 minutes, @@ -494,7 +456,7 @@ this chapter. @node Now start work! @section Now start work! -Lilybuntu 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 diff --git a/Documentation/contributor/source-code.itexi b/Documentation/contributor/source-code.itexi index 65ac35e3b6..4c45e9c8ee 100644 --- a/Documentation/contributor/source-code.itexi +++ b/Documentation/contributor/source-code.itexi @@ -11,6 +11,7 @@ Advanced contributors will find this material quite useful, particularly if they are working on major new features. @menu +* Manually installing lily-git.tcl:: * Starting with Git:: * Basic Git procedures:: * Advanced Git procedures:: @@ -20,6 +21,91 @@ particularly if they are working on major new features. @end menu +@node Manually installing lily-git.tcl +@section Manually installing lily-git.tcl + +We have created an easy-to-use GUI to simplify git for new +contributors. If you are comfortable with the command-line, then +skip ahead to @ref{Starting with Git}. + +@warning{These instructions are only for people who are @emph{not} +using @ref{Lilydev}.} + +@c there's some duplication in this section with stuff covered in +@c Quick Start, but moving it into a macro inside included/ would +@c be getting a bit icky. -gp + +@enumerate +@item +If you haven't already, download and install Git. + +@itemize + +@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 +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. + +@end enumerate + +@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}.} + +Further instructions are in @ref{Daily use of lily-git.tcl}. + +@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 Starting with Git @section Starting with Git -- 2.39.2