Tips for libchamplain Contributors

Back to libchamplain's wiki

libchamplain's code source is in git. Git is still new to a lot of people, therefore, here are the most common tasks a contributor can encounter. While these instructions are gitorious centric, they are easy to follow for new contributors. libchamplain's main repository is located on git.gnome.org.

libchamplain is written using Telepathy's coding style. It is close to GNU's.

Obtaining the code

1. Create an account/Log in on gitorious.

2. Create a clone of the mainline repository. The suggested name is fine. In the rest of this page pierlux-clone is the name given to this cloned repository. This will create a remote copy of the mainline repository for you to work on.

3. Clone it locally to your computer

   git clone git://gitorious.org/libchamplain/pierlux-clone.git

4. If not already, tell git who you are 

   git config --global user.name "FirstName LastName"
   git config --global user.email "user@example.com"

You are ready to work.

Making changes

1. Create a branch to work on.

   git branch my-branch

2. Modify the files you need to change.

3. Add the files to the index

   git add my-file.c

4. Commit the changes

   git commit

   Your favorite editor will be brough for you to enter a description.

5. Optionnaly, push those changes to your personnal remote repository

   git push origin my-branch

That's it.

To switch to another branch after commiting all your changes, use

git checkout my-other-branch

Getting latest changes

1. Checkout the master branch

   git checkout master

2. Pull changes from mainline

   git pull git://gitorious.org/libchamplain/mainline.git master

3. Push those changes to your personnal remote repo.

   git push origin master

Now, you need to update your branch to make sure it uses the latests changes

1. Check out your branch

   git checkout my-branch

2. Rebase it on master

   git rebase master

3. Now pray for there is no conflicts. Follow the instructions given by git.

4. Once done, optionally push that branch to your remote repository. You need to delete the remote version of the branch first as you just completely rewrote it by rebasing.

   git push origin :my-branch
   git push origin my-branch

Sumbitting changes

Once you pushed your changes to your remote repository,

1. Go on your clone page at http://gitorious.org/projects/libchamplain/repos/pierlux-clone

2. Click on "Merge Request". An email will be sent to the mainline manager, asking him to review the changes your suggestted him. You may continue to work as usual.

Troubleshooting

The remote end hung up unexpectedly

You anonymously cloned your personnal remote repository using http. You can't push your changes this way. You have to add a remote that uses git:// or ssh. If you visit your remote repository's page on gitorious, there is a link to "push url" (visible when you are logged in).

Fixing memory leaks and debugging

Libchamplain can be affected by memory leaks because it's written in C and memory needs to be managed manually. This will have a big impact on any application and on the different bindings. Luckily tools are available can provide us with great help.

In order to see where (in which file, line and function) a bug or leak is happening libchamplain and your program must first be compiled with debugging symbols. This can be done easily with by overwriting the environment variable CFLAGS:

CFLAGS="-O0 -g3" ./configure && make && sudo make install

Valgrind

Valgrind has a builtin memory check that can detect most memory leaks. Failing to manipulate libchamplain's data structures properly can have disastrous consequences. This happens mostly when a pointer is freed twice, not initialized, dereferenced when NULL or when memory is written out of bounds. In such cases valgrind can help to detect this bugs.

To use valgrind simply run any executable with the following command:

valgrind --tool=memcheck --leak-check=full --show-reachable=yes --trace-children=yes --log-file=leaks.txt ./launcher-gtk

The output will be saved in the file leaks.txt.

If the program is using different memory allocators then setting the environment variables G_SLICE and G_DEBUG can help when finding leaks.

G_SLICE=always-malloc G_DEBUG=gc-friendly valgrind --tool=memcheck --leak-check=full --show-reachable=yes --trace-children=yes --log-file=leaks.txt ./launcher-gtk

Valgrind error suppression

Valgrind will produce a lot of information as other libraries (glib, gtk2 and clutter) or even OpenGL drivers (fglrx is quite terrible with valgrind) could have some "leaks". These are not always real leaks but global initialization of variables that are never reclaimed at the the end of the program because most libraries don't provide a cleanup function as the OS takes care of this. Nevertheless this is very annoying as the output becomes too verbose.

Luckily valgrind can be instructed to ignore error by providing a suppressions file. To generate a suppression file all that's needed is to execute a program through valgrind and to clean up the output file, then that file can be reused for all programs. A good way to generate the suppression file is to use one of the demos and to execute it.

valgrind --tool=memcheck --leak-check=full --show-reachable=yes --trace-children=yes --gen-suppressions=all demos/.libs/launcher-gtk 2> champlain.sup

Once the suppressions file is generated it should be cleaned of all comments added by valgrind:

perl -i -pe 's/^=.*\n$//' champlain.sup

Then the suppression file can be used with any program by doing:

valgrind --tool=memcheck --leak-check=full --show-reachable=yes --trace-children=yes --suppressions=champlain.sup demos/.libs/launcher-gtk

NOTE: Before using the suppressions file you should filter out all champlain related errors as these are the ones that need to be addressed.

GDB

Sometimes a program will crash without giving too much information, in such situations it will be preferable to run the program through a debugger. To run a program through the debugger do:

gdb --args PROGRAM ARGS

Take note that the demo programs in the folder demo are not real program but shell scripts. Thus in order to debug a demo you have to use the real executable which can be found in the folder .libs. For instance to debug the demo launcher-gtk simply do:

libtool --mode=execute gdb --args demos/launcher-gtk

Other times the program will run but emit warnings to the console. While the warning may be clear it will most likely fail to report the exact location where the error occurred. This can be found by telling glib to transform all warnings into fatal errors and by running the program through the debugger. Once the warning will be emitted it will cause the program to abort. To debug all glib warnings simply do:

G_DEBUG=fatal-warnings libtool --mode=execute gdb --args ./launcher-gtk

More information on How to run and debug your GTK+ application and How to run and debug your GLib application.

Bindings

If you want to debug or trace language bindings then you have to follow the same instructions but you must use your interpreter as the program to debug. For instance if you want to test the Perl demo capitals.pl which you execute normally as:

perl -Mblib examples/capitals.pl

And you want find where a segmentation fault occures in that program, simply run gdb with the interpreter as the executable (using the full path of the interpreter):

G_DEBUG=fatal-warnings gdb --args /usr/bin/perl -Mblib examples/capitals.pl

Clang Static Analyzer

Even though no static analysis tool can find all problems in your source code, it can help you find bugs that you would not notice otherwise. Clang (LLVM's C language frontend) contains such a tool.

First, you need to install LLVM and clang - under Ubuntu this means installing packages of the same names; alternatively, you can compile them from the tarballs. Under Ubuntu 10.4 there appears to be some packaging problem, so you have to create a symlink to the analyzer:

sudo ln -s /usr/bin/ccc-analyzer /usr/bin/c++-analyzer 

To get the report, go to the libchamplain root directory and run:

scan-build ./configure

(with whatever configure options you want to use), and

scan-build make

(if you have multicore CPU, use the -j option to speed up the analysis). If there are any problems detected, the scanner creates a directory of the form scan-build-YYYY-MM-DD-N under /tmp. To see the results, just open index.html with your web browser inside this directory and see the problems.

Clang can be used also as an alternative compiler for libchamplain. Run

./configure CC=clang

to use it for compilation.

OProfile

OProfile can be used for performance optimization. You can find details about how to use it on its web page, so just two useful tips if you decide to use it:

• Under 64bit Linux, you have to compile the program with -fno-omit-frame-pointer. Unfortunately if you want performance results from other libraries your program uses, you have to recompile these libraries as well.

• You can use Gprof2Dot for visualization of the results. Its web page also contains several useful tips about OProfile usage and profiling with it.

Bugzilla integration

This is an attempt to integrate our git workflow with libchamplain's bugzilla.

Configuration

• Get git-send-bugzilla: http://git.collabora.co.uk/?p=user/cassidy/git-bugzilla;a=shortlog;h=refs/heads/description (FIXME: use upstream once patches have been merged)

• edit .git/config in your libchamplain git repo and add the following options:

[bugzilla]
        url = "https://bugzilla.gnome.org"
        username = "plbeaudoin@gnome.org"
        password = "XXXXX"
        squash = 1

Submit branches

• Let's say you have a branch "fix-12345" fixing bug #12345 and $URL is the gitweb http address of your branch
• git-send-bugzilla -m "Proposed fix in branch fix-12345 $URL" 12345 master

Unit tests

So far only the Perl bindings have unit tests. Since libchamplain has no tests yet the only way to find regressions is to run the Perl unit tests. These tests cover the C API although all calls are made through the Perl accesors. To execute the tests first install the build dependencies and libchamplain too, under Ubuntu the following will work:

sudo apt-get install libextutils-depends-perl libextutils-pkgconfig-perl libclutter-perl

Don't forget to install libchamplain as our build process (autoconf & co.) was never configured for the Perl bindings. Once all dependencies are installed build the Perl bindings, you don't have to install them; building them is enough.

cd bindings/perl/Champlain/
perl Makfile.PL && make && make test

That's it! You can now run the unit tests at any time by doing "make test" from the Perl bindings folder. To run a single test file simply do:

perl -Mblib t/ChamplainView.t