@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
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
@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
@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.
@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
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.
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
@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
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}
+@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
+
+
projects / lilypond.git / blobdiff