papercuts-ninja team mailing list archive

[Timothy Arceri <t_arceri@xxxxxxxxxxxx>]

Hi guys,
             The time I can dedicate to this project is about to reduce significantly as my wife is due to have our first child any day now. Anyway on the train ride home from work today I slapped together a short introduction to hacking GTK Ubuntu. Its far from a complete step by step but I'm really interested in feedback from you guys on what further information you would like me to add or expand on further. Also dont be shy about letting me know about spelling errors, incorrect commands, etc.


 
Introduction to hacking GTK on Ubuntu

Before we start I'd like to point out
this in not necessarily the recommend or best way to work on bug
fixes for GTK it is simply the way in which I have figured out how to
do what seems to work best for me.

Tools:
Every good developer needs the help of
good tools the following tools are what I've been using to develop my
bug fixes for GTK I suggest you do some further research to satisfy
your own needs. 

VirtualBox – This is useful so that
you don't have to install your work in progress GTK hacks on you real
box and royally screw things up. Features such as snapshot are
invaluable for saving your development code and for reverting to a
working state before you installed your hacked version of GTK.

GIT – Essential for creating your
patch against the upstream code. You at least need to know how to 
commit your changes and create a patch see:
https://live.gnome.org/GnomeShell/Development/WorkingWithPatches

BZR – Useful for working on the
Ubuntu source code but not essential.

Grep – Being able to search the code
for what your looking for, such as a text string, or for calls to a
certain function etc is invaluable. The main command you should at
least learn is: 
grep -r “YOUR_SEARCH_STRING”  ./
This will search files in the current
directory and any child directory's for the string you provide.

Gedit – Or any good code editing tool
to actually make your code changes. 

Setting up your development environment:
Once you have downloaded and installed
Virtualbox on your system you should download and install the latest
version of Ubuntu onto Virtualbox. You want the latest version as you
want the code your working on to be as close as possible to the
upstream version so that you can submit your changes upstream after
you have a working patch. 
After installing Ubuntu to get the
virtual machine ready for building GTK run the command:
sudo apt-get build-dep gtk+3.0
This will install all the dependencies
that you need to build GTK.

Getting the source code:
To get a version of the GTK source code
that will be compatible with the version of Ubuntu you have installed
on your virtual machine boot into your virtual machine and open a
terminal. 
From here create a new director e.g.
gtk cd to the directory and type: 
apt-get source gtk+3.0
This will then download the latest
version of the source code for the version of gtk installed on your
virtual machine.
This might be a good time to make a
snapshot of your virtual machine so you can return here if you want
to revert all your changes.

What the code looks like:
Developers usually look at GTK as a
scary black box of magic but really a lot of it is just a collection
of calls to itself so in many ways its just like a any GTK
application. The remaining calls are to library's such as Glib which
again is used by most applications.
Making changes:
Search (with Nautilus, Grep, or however
you like) explorer and get to know the structure of the GTK source
code. Once you think you think you have found what you are looking
for make a small change and try building GTK.
You may have noticed I didn't mention a
debugger in the topic on tools. I think this is the time I should
come clean. In the short time I've been hacking GTK I have never used
a debugger, the main reason is probably because I've been working on
fairly simple changes but also I think by using grep to search for
what function leads to the next helps you understand much better what
the code is actually doing as you tend to read the code much more
closely rather than just stepping through until you find the spot you
are looking for. Anyway the way I've managed to get around not using
a debugger is to use good old print statements. Now you cant just use
printf as these will be redirected (where I cant be sure of the top
of my head) but you can use: g_warning() which has the same syntax as
printf and will print out a warning to the terminal when ever it is
called. 
For example you would run your GTK
application you want to test GTK with from the command line and this
would output your warning strings when the GTK code is executed.


What lies beneath:
Sometime you may track your bug all the
way through GTK and out the other side to Glib all the same
techniques apply to fixing Glib bugs as GTK although it takes a hell
of a lot longer to build (a least on my old dinosaur of a computer it
does). 

Building your changes:
Unlike most C programs your used to you
dont use the make command to build GTK for Ubuntu. Debian based
distributions usually have patches that they apply to the upstream
source code (these patches are located in the debian directory in the
source code) if you dont apply these patches when building all sorts
of weird and wonderful things will happen to your Ubuntu install and
yes I learnt this the hard way.
Anyway to build with these changes you
can run this command in the terminal:
dpkg-buildpackage -us -uc

If you have made changes it will fail
and you need to use the command:
dpkg-source –commit
to checkin the changes just like you
would into a version control system. This will cause a patch to be
added to the debian directory containing your changes.
Once you have checked in your changes
you can run the above command again and GTK will build.
Once the build is finished this is
again a good time to create a snapshot of your virtual machine.

Testing your change:
Once GTK has finished building it will
have created some .debs that you can install. You can use Ubuntu
software center but its much faster to use the command line. Type: 
sudo dpkg -i packagename.deb

Once you have installed the GTK
packages (you usually just need to install the main one) run a GTK
application from the command line and test your changes. You should
see any output/warnings/errors etc printed to the terminal.

Enjoy.

P.S How the Gnome devs do it:
Rather than using Virtual machines the
Upstream dev's use a tool JHBuild http://developer.gnome.org/jhbuild/unstable/ to create a safe Gnome environment where they can make there changes
without breaking there machine. However the documentation on how to
use it isn't aimed at beginners if you work it out though why not
create a guide for me and others to use ;-) I would love to not have
to mess around rewriting my patches to apply to the upstream source
code.

Further Reading:
I just found this link while looking
for the JHBuild link:
https://live.gnome.org/DocumentationProject/Tasks/DeveloperDocs/BeginnerTutorials

Its a GTK introduction form beginners
on the Gnome wiki.




________________________________
 From: Chris Wilson <notgary@xxxxxxxxxx>
To: Chris Wilson <notgary@xxxxxxxxxx> 
Cc: Ubuntu Papercuts Ninjas <papercuts-ninja@xxxxxxxxxxxxxxxxxxx> 
Sent: Thursday, 29 November 2012 10:29 AM
Subject: Re: [Papercuts-ninja] A wiki page for each raring cycle?
 

For people who know their way around GTK+ and Compiz:
I think it's particularly important to get a brief guide to fixing bugs in GTK+ and Compiz up on their respective pages so people know what they're doing around them. Application toolkits and operating system infrastructure in general can be a layer of abstraction more than a lot of beginners can handle, and we need to make it as easy as possible for them.

If you can get some information up there, especially a step-by-step guide to setting up development version of the package in question, and way in which to test it, then that would be awesome.


Chris



On 28 November 2012 23:23, Chris Wilson <notgary@xxxxxxxxxx> wrote:

Hi Dario,
>
>
>That's a great idea. There's not really any need to stick to the milestones, though that would be a good starting point. I've reorganised the milestones earlier tonight, so don't worry about sticking to them. Over time we'll find ourselves touching more and more packages so these pages will be useful then.
>
>
>Once you've got them set up, post them here to the list so we can all add our own tips.
>
>
>Thanks for getting stuck in with this,
>Chris
>
>
>
>
>
>Chris

_______________________________________________
Mailing list: https://launchpad.net/~papercuts-ninja
Post to     : papercuts-ninja@xxxxxxxxxxxxxxxxxxx
Unsubscribe : https://launchpad.net/~papercuts-ninja
More help   : https://help.launchpad.net/ListHelp