X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fcontributor%2Fquick-start.itexi;h=90706569fb4511a5fc0791f61b61fbc7c31c9934;hb=5ffa69e62d79a9b5eac909b86d78cda0fc5fdfa9;hp=4bbb180f663e89c8f85a00015ced5243baa7f756;hpb=512542520ca60b7018df2de43e2c5f51bf05432c;p=lilypond.git diff --git a/Documentation/contributor/quick-start.itexi b/Documentation/contributor/quick-start.itexi index 4bbb180f66..90706569fb 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,23 +20,26 @@ 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 lilydev:: +* Now start work!:: @end menu -@node Lilybuntu -@section Lilybuntu +@node Lilydev +@section Lilydev -text. +This section discusses how to install and use the Ubuntu LilyPond +Development Remix. @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 @@ -48,34 +52,42 @@ 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.1.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.1.iso.md5} +@c @* +@c @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 music 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 -@code{boot:} prompt. Type: +Install @file{ubuntu-lilydev-remix-1.1.iso} as the @qq{guest} +operating system on your virtualized system. + +@enumerate + +@item +When @file{ubuntu-lilydev-remix-1.1.iso} boots, it shows an +ISOLINUX @code{boot:} prompt. Type: @example install @@ -89,12 +101,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{ubuntu-lilydev-remix-1.1.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. @@ -103,24 +115,31 @@ a guest operating system. @item Do any extra configuration for your virtualization software. -We have additional instructions in -@ref{Configuring lilybuntu in virtualbox}. +There are additional instructions for VirtualBox in +@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, 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}. -@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 @@ -141,22 +160,40 @@ 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 -Set up any additional features, such as @q{Shared Folders} between -your main operating system and ubuntu. Consult external -documentation for this step. +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: + +@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. + +@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. -@node Using lilybuntu -@subsection Using lilybuntu +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 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. @@ -166,19 +203,35 @@ couple of @qq{introduction to Ubuntu} webpages. 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}. +software. Go to @clicksequence{Applications @click{} Ubuntu +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) + +@example +@uref{http://www.ubuntupocketguide.com/} +@end example @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 @@ -194,17 +247,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 install 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 @@ -212,85 +263,28 @@ 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 +directory (around 121Mb). 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}. +@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 +problem persists, please ask for help.} + @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. +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 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} @@ -398,4 +392,110 @@ current state of the remote repository (at @code{git.sv.gnu.org}). +@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}. + +@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 +mkdir -p build/ +cd build/ +../configure +@end example + +@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. + +@example +cd ~/lilypond-git/build/ +make +@end example + +You may run the compiled @code{lilypond} with: + +@example +cd ~/lilypond-git/build/ +out/bin/lilypond my-file.ly +@end example + +@subsubheading Building the documentation + +Compiling the documentation is a much more involved process, and +will likely take 2 to 10 hours. + +@example +cd ~/lilypond-git/build/ +make +make doc +@end example + +The documentation is put in @file{out-www/offline-root/}. You may +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 +@end example + +@subsubheading Installing + +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 +or typesetting work should be done with an official GUB release. + + +@subsubheading Problems and other options + +To select different build options, or isolate certain parts of the +build, or to use multiple CPUs while building, read +@ref{Compiling}. + +In particular, contributors working on the documentation should be +aware of some bugs in the build system, and should read the +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 +their intended contributions: + +@itemize +@item @ref{Documentation work} +@item @ref{Translating the documentation} +@item @ref{Website work} +@item @ref{Regression tests} +@item @ref{Programming work} +@end itemize + +These chapters are mainly intended for people not using LilyDev, +but they contain extra information about the +@qq{behind-the-scenes} activities. We recommend that you read +these at your leisure, a few weeks after beginning work with +LilyDev. + +@itemize +@item @ref{Working with source code} +@item @ref{Compiling} +@end itemize + +