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
We will start by setting up a configuration file and directories from where we will work.
Using the built in script
In the latest Gnome Developer Kit 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
![/!\](/gnome/gnome-responsive/img/dialog-warning-symbolic.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.
Open ~/.conaryrc for editing:
gedit ~/.conaryrc
Here is an example file, please change the lines appropriately as explained below:
name Your Name contact your@email.com cleanAfterCook False [gnome:trunk] buildLabel gnome.rpath.org@gnome:trunk
The cleanAfterCook option ensures that conary leaves the building directory behind, where you can find for example sources and object files.
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
- gnome.rpath.org is the URL of the repository. buildLabel specifies where you find needed stuff to work on.
Now we need to create these directories:
mkdir -p $HOME/conary/cache mkdir -p $HOME/conary/builds mkdir -p $HOME/conary/gnome
- Conary puts all its stuff under ~/conary and nowhere else. ~/conary/gnome is where you can work with stuff from the gnome:trunk repository.
Conary use the concept of 'context' to define "association between the build environment and a Conary repository". To set up the context for gnome:trunk:
cd $HOME/source/gnome/ cvc context gnome:trunk
Full configuration documentation for conary: http://wiki.rpath.com/wiki/Conary:Configuration
Building Packages
You can manage the source and building of packages with cvc (Conary Version Control).
Checking out and building a gnome module
To start, simply use the following command to checkout your desired module (for this example we'll use empathy):
cvc co empathy # co is shortcut for 'checkout'
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:
cvc cook empathy.recipe
If you are presented with an error message about missing dependencies, simply install these dependencies through conary,
sudo conary update libtelepathy:devel telepathy-mission-control:devel
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 ~/conary/builds/empathy/empathy-HEAD/ and the installed program in ~/conary/builds/empathy/_ROOT_/.
Now that 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 trunk.
All you have to do is add a list of patches to the recipe file:
gedit ~/source/gnome/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 patches = ['fixme.patch', 'mypatch.patch', 'http://bugzilla.gnome.org/attachment.cgi?id=100212']
18
19 def install(r):
20 GnomePackageRecipe.install(r)
21 r.Install('data/empathy.desktop','%(datadir)s/applications/')
As you can see we have a patches variable.
- 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 either 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
Have a look at the sources
TODO: Could people really mess with the source? Won't conary be confused if it's externally changed?
Conary maintains a local copy of the sources, from which it builds the package. This can be found in the cache path, for example:
cd ~/conary/cache/empathy/git.gnome.org_empathy_/git/ ls
If this directory doesn't exist, we can request an update by running cvc refresh from within the checkout directory:
cd ~/conary/gnome/empathy/ cvc refresh
Previously you can directly utilize the repository at ~/conary/cache/empathy/git.gnome.org_empathy_/git/, but as of conary=2.0.45-1-1, conary uses bare GIT repository(see git help clone) to store the source, as it brings some good such as saving spaces. This is a bare repository:
$ ls ~/conary/cache/empathy/git.gnome.org_empathy_/git/ config description FETCH_HEAD HEAD hooks info objects refs
But you can still make use of it, because git can clone from bare repositories. To clone it to another place on your file system:
mkdir ~/src cd ~/src git clone ~/conary/cache/empathy/git.gnome.org_empathy_/git/ empathy
As you may see in git help clone, git will use hardlinks to save space when possible.
Create a patch
Please read here for more about git and gnome.
For this example we will edit the desktop file of empathy (the menu entry).
gedit ~/conary/cache/empathy/git.gnome.org_empathy_/git/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 Git commands. If you have write privileges you can even commit your changes back to Gnome's Git. First we'll make a patch so we can build and test our changes.
cd ~/conary/cache/empathy/git.gnome.org_empathy_/git/ git diff # should show our changes git diff > ~/source/gnome/trunk/empathy/mypatch.patch
(We ran git 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 ~/source/gnome/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
Read about the routine by which we update the Developer Kit.
Conary package manager and version control documentation: http://wiki.rpath.com/wiki/Conary