SWT/Devel/Gtk/Dev guide

The Comprehensive Guide to SWT Development for Linux/Gtk

This is a work in progress. Certain sections may be missing, or incomplete.

About SWT

SWT is the layer between PlatformUI and the underlying Gtk2 or Gtk3 of the system. It can be launched to use Gtk2 or Gtk3, but cannot use them both at the same time. Communication from Java (SWT layer) to C (native Gtk layer) occurs through calls defined in OS.java. The image below describes this hierarchy better:

You will learn:

• How to configure your machine (Eclipse/Git) to contribute SWT patches
• Info on building .SO images to run snippets with newest SWT Master
• Info on Gtk Versions, compiling various Gtk Versions
• How to add your own gtk_ methods to OS.java
• Tips on SWT Development, how to navigate the code base
• Understanding the underlying glue (swtFixed) between SWT/Java and Gtk/C
• Learn how to compile various Gtk versions for testing with SWT
• Learn how to make a Gtk application in Eclipse & how to debug it
• Learn to debug Gtk itself
• Learn how to debug the native Gtk (C) part of a running SWT (Java) application
• Learn how to debug the swtFixed custom C code of a running SWT (Java) application

Upon completion of this document, hopefully you will know SWT-fu (as in kung-fu).

Knowledge Pre-requisites

• Solid Java knowledge: from class inheritence to multi-threading
• Some C experience: know thy pointers and make files
• Gtk background highly recommended but can be learned
• Eclipse: knowing how to use Eclipse is quite essential. But you don't have to know about JFace/PlatformUI/RCP development internals
• Git: for example you should know the difference between merge and rebase. But all git-bits can be learned

Communication and support

SWT Community

If you have questions, you should post them to:

 platform-swt-inbox@eclipse.org

It's also a good idea to sign up for the SWT mailing list. There are #swt-gtk and #eclipse-dev channels on Freenode (IRC) as well.

Following SWT bugs in Bugzilla

Whenever you work on a project, you should consider following the default assignee of the project in Bugzilla. This way you find out about new issues and what issues get worked on. To do so, go to bugzilla https://bugs.eclipse.org/ -> Preferences -> Email preferences, and add the email below to your watch list:

 platform-swt-inbox@eclipse.org

SWT Development Environment Setup

There is an important distinction when running SWT: using the pre-compiled .JAR file, or using the source code in your local Git repository.

.JAR

You can download the SWT .JAR file, and add it as a library in your project: https://www.eclipse.org/swt/. However, when you make changes to the SWT source code, these changes will not be visible when running SWT. This is only useful if you develop 'using' SWT, but not SWT itself.

Source code

To develop SWT itself, being able to run SWT using the changes made to the source code is important. The process to do is lengthy, but valuable.

Add the SWT project to the build path

In order to run snippets with the SWT source code, you will need to add the SWT project to the snippets' project build path. To do this:

• Right click the SWT snippets project in the Package Exlporer
• Select "Properties"
• Select "Java Build Path" on the right hand side
• Select the "Projects" tab and click "Add..."
• Select the SWT project and click "OK"

Install the SWT Developer Tools Eclipse Plugin

SWT developer tools automatically builds the custom C code that SWT uses to work with Gtk. Without the tools, you cannot develop SWT. Install the latest from the Eclipse update site: https://www.eclipse.org/swt/updatesite.php

Remember to re-install these tools if you re-install Eclipse.

Eclipse git (Egit)

Eclipse git is used to compare SWT files against older versions. Not strictly necessary, but highly recommended as it's sometimes easier to use Git through Eclipse than it is through the command line. If you are on Fedora, run:

 sudo dnf install eclipse-git

SWT source code and binary repositories

Check out the repositories holding the SWT sources and binaries. I usually do this from inside Eclipse, but you can also clone things from the command line. The URI's for the repositories are:

 git://git.eclipse.org/gitroot/platform/eclipse.platform.swt.git
 git://git.eclipse.org/gitroot/platform/eclipse.platform.swt.binaries.git

Modify the .classpath files

At first you might get many many errors. You first have to tell the project, that you are on Linux/Gtk for things to compile/run properly. Specifically for Gtk, you must do the following:

• Open the 'Navigator' view (not package explorer)
• Under 'org.eclipse.swt' look for the .classpath files
• Rename .classpath_gtk to .classpath
• Clean up projects (in Eclipse, Project -> Clean)
• Now run a test snippet or ControlExample.java, it should work without the compilation errors

Configure git for review

To contribute to SWT, you need to modify your Git config to be able to push to Gerrit, which is the Eclipse Project's review system. Open your Git root, navigate to the SWT repository, and open the Git config file with a text editor . On my system it looks like this:

 ~/git/eclipse.platform.swt/.git/config

Add review branch: (adjust for your own user name instead of 'lufimtsev'):

 [remote "review"]
   url = ssh://lufimtsev@git.eclipse.org:29418/platform/eclipse.platform.swt.git
   push = HEAD:refs/for/master

Under the existing master, add 'rebase = true':

 [branch "master"]
   rebase = true

Add your name and email for signing off commits:

 [user]
   name = Lev Ufimtsev
   email = lufimtse@redhat.com

You can now push your changes to the review branch (Gerrit) for review:

 git push review

Enable 32/64 bit checking by SWT Tools

The Java source code has to work on both 32 and 64 bit machines. On 32 bit machines, calls to Gtk that use long in the parameter will not compile. All such longs should have an /*int*/ annotation after it. For example:

 //This will cause a 32 bit build to fail:
 void gtk_css_provider_load_from_css (long context, String css)  { .. }
  //                                      ^ missing /*int*/
 
 //Every 'long' should followed by a '/*int*/' like so:
 void gtk_css_provider_load_from_css (long /*int*/ context, String css)

To avoid missing these things by accident, SWT Tools can automatically check these things and mark them as errors. This functionality must first be enabled though. By now you should have SWT Developer tools already installed. To enable checking automatically:

• Right click on the 'org.eclipse.swt' project.
• From the drop down menu, enable 'SWT Tools -> Report 32/64 bit problems'
• Now if you don't include the /*int*/ a warning will be thrown in your the problem view

References

https://www.eclipse.org/swt/fixbugs.php