A brief overview of how to get started developing and contributing to GNOME with the GNOME Developer Kit
Contents
Setting up conary version control system
Configuring Conary
The conary version control (cvc) allows you to download and build applications from rpath. We will start by setting up a configuration file and directories from where we will work.
Using the built in script
In the latest GnomeDeveloperKit there is a shell script to automate configuring and setting up conary for GNOME Development.
To begin run the following command in a terminal and follow the prompts:
setup_build_env.sh
This script will setup a conary configuration file in ~/.conaryrc with your details and make the appropriate directory structure for developing gnome with conary. You may skip the next step or read over it if you are interested in what this script did.
Configuring Conary for GNOME development manually
![/!\](/moin_static161/gnome/img/alert.png "/!\"){kind=small}
Notice: If you used the script in the previous step you can skip down to the next section. The script primarily does exactly what this part of the tutorial covers.
The first thing we need to do is configure conary cvc to download from the GNOME rBuilder repository.
Open ~/.conaryrc for editing:
gedit ~/.conaryrc
Here is an example file, please change the lines appropriately as explained below:
lookaside /home/user/conary/cache buildPath /home/user/conary/builds name Your Name contact your@email.com cleanAfterCook False [gnome:trunk] buildLabel gnome.rpath.org@gnome:trunk
The lookaside line is a cache for use during the building of packages. You should replace user to your username or preferred directory.
The buildpath is where the source and built application is stored. You should replace user to your username or preferred directory.
The cleanAfterCook option ensures that conary leaves the SVN directory behind so we can edit the source if we like (more later on).
name and contact are really only necessary if you are building packages for Conary repositories. More details here: http://wiki.foresightlinux.org/display/DEV/Foresight+Linux+2.x
Now we need to create these directories:
mkdir -p $HOME/conary/cache mkdir -p $HOME/conary/builds mkdir -p $HOME/conary/gnome.rpath.org/gnome/trunk
You may notice we've also made a gnome.rpath.org/gnome/trunk directory. This is where we set the conary context so that a checkout in this folder is retrieved from the gnome trunk.
Finally we change directory to our gnome development environment and set cvc to use the gnome:trunk repository:
cd $HOME/conary/gnome.rpath.org/gnome/trunk cvc context gnome:trunk
Full configuration documentation for conary: http://wiki.rpath.com/wiki/Conary:Configuration
Checking out and building a gnome module
Now that we have configured conary to use gnome's rpath repository we can check out a gnome module to develop on.
To start, simply use the following command to checkout your desired module (for this example we'll use empathy):
cvc co empathy
We'll now see an empathy folder has been created. Inside there we will find a file named empathy.recipe. This contains instructions for cvc on how to build our application. The following command will build empathy from the gnome source:
cvc cook empathy.recipe
However if you are following this example you will have now been presented with an error message about missing dependencies. For this particular example they are libtelepathy:devel and telepathy-mission-control:devel. We can simply install these dependencies through conary like so conary update libtelepathy:devel telepathy-mission-control:devel and then continue.
Once all of the dependencies are resolved rerunning the cvc cook command should successfully download, and build your desired package. When completed, you will find the source in buildPath/package_name-- and the installed program in buildPath/_ROOT_ in the appropriate filepath.
For Example:
~/conary/builds/empathy-- ~/conary/builds/_ROOT_/usr/bin/empathy
Now we have built our module we can use conary to install it to our actual filesystem (and make the application available in the menu if applicable). cvc will have made a conary changeset file (*.ccs) in the checkout directory. Changeset files are used to install and update packages in conary.
conary showcs empathy-r599.ccs # Will display the version information conary showcs --ls empathy-r599.ccs # Will list the included files conary showcs --deps empathy-r599.ccs # Will list all of the package's dependencies
After inspecting the changeset file you can install it through conary thus updating your system with:
sudo conary update empathy-r599.ccs
Applying patches for testing
For details on how to get, review and test patches it is highly recommended to read the Preliminary Patch Review. When you get to the test section you can continue with the instructions on this page.
As mentioned before, the recipe file for a module contains instructions for cvc to build with. One of the most useful things we can instruct cvc to do is to apply patches before it builds. This means we can test and check patches quickly and easily against the upstream SVN.
All you have to do is add a list of patches to the recipe file:
gedit ~/conary/gnome.rpath.org/gnome/trunk/empathy/empathy.recipe
This is a standard python file for those familiar with the language. What we are going to do is add a comma separated list of patches to apply to the module before building. Take note of the patches line in the sample below:
1 #
2 # Copyright (c) 2007 Foresight Linux
3 # This file is distributed under the terms of the MIT License.
4 # A copy is available at http://www.rpath.com/permanent/mit-license.html
5 #
6
7 loadSuperClass('gnomepackage')
8 class Empathy(GnomePackageRecipe):
9
10 name = 'empathy'
11 version = GnomePackageRecipe._getVersion(name)
12
13 buildRequires = ['aspell:devel','GConf:devel', 'GConf:runtime', 'ORBit2:devel', 'dbus-glib:runtime','gnome-keyring:devel', 'gnome-vfs:devel', 'libart_lgpl:devel', 'libbonobo:devel', 'libbonoboui:devel', 'libglade:devel', 'libgnome:devel', 'libgnomecanvas:devel', 'libgnomeui:devel', 'libtelepathy:devel', 'popt:devel', 'telepathy-mission-control:devel', 'evolution-data-server:devel', 'gnome-panel:devel', 'desktop-file-utils:config']
14
15 extraConfig = ' --enable-python=no --enable-voip=yes'
16
17 def install(r):
18 GnomePackageRecipe.install(r)
19 r.Install('data/empathy.desktop','%(datadir)s/applications/')
20
21 patches = ['fixme.patch', 'mypatch.patch', 'http://bugzilla.gnome.org/attachment.cgi?id=100212']
As you can see we add a patches variable at the bottom of the file if one doesn't already exist. Make sure the patches variable is indented as far as the name variable, i.e 4 spaces in from the class declaration. To add more patches we just put them in a comma separated list as you can see above. The best part is that patches can be in the same folder as the recipe or from the internet. This is great since, as you can see, I've linked to multiple patches, including one attached to empathy in the bugzilla database.
Once you have changed the recipe file to suit, simply run cvc cook empathy.recipe to rebuild the application and see the results.
Because we've made changes to the module you may see a new changeset file in the directory: ls *.ccs. Make sure you are using the latest file when you are working with the module (it doesn't matter if there is only one changeset file):
sudo conary update empathy-r599.ccs
Editing the source, creating patches and rebuilding
Conary creates source packages of modules into tar.bz2 files that it uses with the cvc cook command. Conary keeps a copy of the Gnome SVN it checks out so it can update it when a cvc refresh command is run. This can be found in the cache path, for example:
cd ~/conary/cache/empathy/svn.gnome.org_svn_empathy_trunk/svn ls
If this directory doesn't exist, we can request an update by running cvc refresh from within the checkout directory:
cd ~/conary/gnome.rpath.org/gnome/trunk/empathy cvc refresh empathy--.tar.bz2
Working with the SVN has many advantages. It means we can work with the source code directly, create patches against the upstream trunk and it avoids the messy build and configuration residue. So the basic process is to edit a file, create a patch and apply it through the recipe.
For this example we will edit the desktop file of empathy (the menu entry).
gedit ~/conary/cache/empathy/svn.gnome.org_svn_empathy_trunk/svn/data/empathy.desktop.in.in
We will then change the _Name = Empathy Instant Messenger line to _Name = Empathy is for chatting.
We can then apply the usual SVN commands. If you have write privileges you can even commit your changes back to Gnome's SVN. First we'll make a patch so we can build and test our changes.
cd ~/conary/cache/empathy/svn.gnome.org_svn_empathy_trunk/svn svn diff # should show our changes svn diff > ~/conary/gnome.rpath.org/gnome/trunk/empathy/mypatch.patch
(We ran the SVN diff twice. Once to show the output to make sure it is there, and the second time to create a patch file).
Now we have created the patch, we can open up the recipe file as shown above and add 'mypatch.patch' to the list of patches to apply. Then we cook the program, and update it:
cd ~/conary/gnome.rpath.org/gnome/trunk/empathy gedit empathy.recipe cvc cook empathy.recipe sudo conary update empathy-r599.ccs
Now we can test our changes (we should have changed the name of the program in our menu if you have been following this example). If all is well we can submit the mypatch.patch file back to bugzilla for reviewing (of course only do it if you have made a useful change). Read more about contributing patches on the Submitting Patches page.
Miscellaneous
As a final note we can roll the system back to it's previous state before the last conary update command. This is useful for testing multiple patches and rebuilding systems.
sudo conary rollback 1
The above example will undo the last conary update command, but we can go back N positions by changing the number 1.
Resources
See also: GnomeDeveloperKit
Conary package manager and version control documentation: http://wiki.rpath.com/wiki/Conary
