Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "SWT/Beginners"

< SWT
(Writing a patch)
(Download/import sources and binaries)
 
(11 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
Please note this article is still being written and is not final.
 
Please note this article is still being written and is not final.
  
== Eclipse Plugins ==
+
= Prerequisites =
 +
This guide assumes basic knowledge of Java, git, and general Eclipse development. Nothing in this guide covers any platform specific development knowledge -- for this documentation please see [[SWT/Beginners#Further_reading | further reading.]]
 +
 
 +
== Eclipse plugins ==
 
Download and install [https://www.eclipse.org/swt/tools.php SWT tools]. Other than that, you may find the following plugins useful (not mandatory for SWT development):
 
Download and install [https://www.eclipse.org/swt/tools.php SWT tools]. Other than that, you may find the following plugins useful (not mandatory for SWT development):
 
* [https://www.eclipse.org/egit/ EGit]
 
* [https://www.eclipse.org/egit/ EGit]
Line 20: Line 23:
 
* org.eclipse.swt.tests
 
* org.eclipse.swt.tests
 
<br />
 
<br />
This will add the SWT source code, snippets, example applications, and test cases to your workspace. Now import the binaries project. This will depend on your platform and architecture of your machine -- choose accordingly.
+
This will add the SWT source code, snippets, example applications, and test cases to your workspace.
 +
<br />
 +
<br />
 +
Now import the binaries project. This will depend on your platform and architecture of your machine -- choose accordingly. For example, on 64-bit Linux GTK I would be importing:
 +
* org.eclipse.swt.gtk.linux.x86_64
  
 
== Modify the .classpath ==
 
== Modify the .classpath ==
Line 37: Line 44:
 
# Expand the "Remotes" item
 
# Expand the "Remotes" item
 
# Right click the "origin" item, and select "Gerrit configuration"
 
# Right click the "origin" item, and select "Gerrit configuration"
# Fill in your information from gerrit (username).
+
# Fill in your information from Gerrit (username).
 +
 
 +
 
 +
For more information about using Gerrit, see the more comprehensive [[SWT/Devel/Workflow#Gerrit | SWT Gerrit page.]]
  
 
= Writing a patch =
 
= Writing a patch =
Line 74: Line 84:
 
How does this work? Well the SWT sources use Java code to interact with native libraries through JNI. This is done by adding boilerplate JNI function signatures in files like OS.java, for example. SWT Tools then generates the JNI C code which links the Java JNI functions to the actual native calls. The generated code and the JNI function signatures (as well any other Java code) are then merged as one change under the org.eclipse.swt project. This type of patch is considered a native change.
 
How does this work? Well the SWT sources use Java code to interact with native libraries through JNI. This is done by adding boilerplate JNI function signatures in files like OS.java, for example. SWT Tools then generates the JNI C code which links the Java JNI functions to the actual native calls. The generated code and the JNI function signatures (as well any other Java code) are then merged as one change under the org.eclipse.swt project. This type of patch is considered a native change.
  
After such a change is merged, the JNI C code does not need to be generated again. Changes that do not modify the JNI code are considered non-native changes, as no additional changes beyond "pure" Java code needs to be made. However SWT does not load every function possible from native libraries, only those that are actually called/needed by SWT. It is not uncommon that a bug fix will require a new native function available for use in SWT, in which case its method signature needs to be added to SWT. And thus the process repeats itself.
+
After such a change is merged, the JNI C code does not need to be generated again. Changes that do not modify the JNI code are considered non-native changes, as no additional changes beyond "pure" Java code needs to be made. However SWT does not load every function possible from native libraries, only those that are actually called/needed by SWT. It is not uncommon that a bug fix will require a new native function to be available for use in SWT, in which case its method signature needs to be added to SWT. And thus the process repeats itself.
  
 
=== Writing a non-native change ===
 
=== Writing a non-native change ===
Line 80: Line 90:
  
 
=== Writing a native change ===
 
=== Writing a native change ===
Native changes are trickier because they require the author to rebuild the native bindings. Those library objects mentioned earlier now have to be generated as well in order for SWT to run with the changes in the workspace. While these don't need to be submitted in your Gerrit change, they do have to be built for testing purposes (otherwise SWT won't run and will complain about library link errors). For instructions on building the library objects, check for a README file in that platform's project folder.
+
Native changes are trickier because they require you to rebuild the native bindings. The aforementioned library objects now have to be generated manually in order for SWT to run with local changes. While the library objects do not need to be submitted in your Gerrit change, they do have to be built for testing purposes (otherwise SWT won't run and will complain about library link errors). For instructions on building the library objects, check for a README file in binaries project folder for your platform.
  
 
After testing your patch, follow the steps below to submit a native change:
 
After testing your patch, follow the steps below to submit a native change:
Line 86: Line 96:
 
# Go to Project -> Clean. Clean the SWT sources and binaries projects. Make sure "Build Automatically" is checked in the Project menu.
 
# Go to Project -> Clean. Clean the SWT sources and binaries projects. Make sure "Build Automatically" is checked in the Project menu.
 
# After cleaning, some *.c and *.h files will show up in the Git staging area. Usually these are files like os.c, os_stats.c, os_stats.h, etc.
 
# After cleaning, some *.c and *.h files will show up in the Git staging area. Usually these are files like os.c, os_stats.c, os_stats.h, etc.
# Commit these, as well as the Java files. Submit the patch by right clicking the org.eclipse.swt project in the "Git repositories" view and select "Push to Gerrit".
+
# Commit these, as well as the Java files (or any other changes relating to your patch) Submit the patch by right clicking the org.eclipse.swt project in the "Git repositories" view and select "Push to Gerrit".
 
+
= Other patch related tasks =
+
 
+
The following are good to know in the event that you need to do them.
+
 
+
== Adding API to SWT ==
+
SWT API has to be backwards compatible, meaning changing existing API is basically not an option (except in a few cases). However it's very common to add new API -- to do so, follow the steps below.
+
 
+
# Add the API. If you are doing this in a common class, you only have to add it once. Otherwise, be sure to add the constant/method to all platforms' classes.
+
# If this is the ''first'' time you are adding API in this release cycle, bump the minor "version" fields in the pom.xml and MANIFEST.mf files. For example, 3.107.100 -> 3.108.0
+
# Write the Javadocs, and be sure to include @since tags, indicating the API is available since the API version you just bumped in step 2.
+
 
+
=== Setting an API baseline ===
+
In general, it's important to configure API tools properly to warn you about API changes and versions that need to be bumped. To set an API baseline:
+
  
# Go to Windows -> Preferences. Search for "API baseline"
+
= Further reading =
# Click "Add Baseline"
+
# Select "An existing Eclipse installation directory"
+
# Click "Browse" and point the wizard to the binary "eclipse" file for your current Eclipse installation
+
# Click "Finish"
+
  
== Writing new and noteworthy (N&N) posts ==
+
Outside of the basics contained in this tutorial, there is additional documentation that provides further insight into development on each platform.
If you've added a new feature or fixed a significant bug, it's often useful to write an N&N post. N&N posts are short HTML entries in a milestone's/release's N&N page. The N&N page showcases improvements and features for all aspects of the Eclipse IDE during that milestone/release. To write an N&N post:
+
*[[SWT/Devel/Gtk | GTK development]]
  
# Clone the [git://git.eclipse.org/gitroot/www.eclipse.org/eclipse/news.git eclipse/news] repo
+
Additionally, there are some workflow tasks which are platform agnostic. You can find these at the [[SWT/Devel/Workflow | SWT workflow documentation.]]
# Look for the folder and file corresponding to the milestone/release and component you want to write about (for example: 4.9/platform.html)
+
# Follow the instructions in the HTML page and/or look at other posts as example
+
# Add a new section with a meaningful title and a short description about the feature/bug that was fixed. Images can be added to further demonstrate the fix (follow the instructions in the HTML file re: images)
+
# Submit the change by right clicking the news project in the "Git repositories" view and select "Push to Gerrit".
+
# Once uploaded in Gerrit, add a committer from your component to review it.
+

Latest revision as of 11:39, 3 July 2019

This page is useful for beginners who would like to develop SWT. All of the information here is cross-platform, general knowledge. Please note the page is under construction.

Getting started

Please note this article is still being written and is not final.

Prerequisites

This guide assumes basic knowledge of Java, git, and general Eclipse development. Nothing in this guide covers any platform specific development knowledge -- for this documentation please see further reading.

Eclipse plugins

Download and install SWT tools. Other than that, you may find the following plugins useful (not mandatory for SWT development):

Download/import sources and binaries

SWT works using two code repositories:

  1. The source code, which contains Java and JNI source code for all widgets. This where 99% of all changes belong.
  2. The binaries, which contain the platform specific library objects. These allow the Java source code to call the operating system's toolkit.


Start by cloning both of git repos above. From the sources repo, import the following projects:

  • org.eclipse.swt
  • org.eclipse.swt.snippets
  • org.eclipse.swt.examples
  • org.eclipse.swt.tests


This will add the SWT source code, snippets, example applications, and test cases to your workspace.

Now import the binaries project. This will depend on your platform and architecture of your machine -- choose accordingly. For example, on 64-bit Linux GTK I would be importing:

  • org.eclipse.swt.gtk.linux.x86_64

Modify the .classpath

After importing the SWT sources and binaries, you will see lots of errors. This is normal, as the SWT sources have not yet been linked to the binary matching your platform and can be resolved by modifying the .classpath file.

  1. Open the "Navigator" view (not Package Explorer).
  2. In the org.eclipse.swt folder you will see a collection of .classpath files corresponding to various platforms (GTK, Win32, Cocoa, etc.).
  3. Copy the desired .classpath_* file.
  4. Paste it in the same folder, except rename it to .classpath
  5. Go to Project -> Clean, and clean the org.eclipse.swt project and the project matching your platform's binaries.

Gerrit configuration

Eclipse/SWT uses a code review tool called Gerrit. It's quite easy to configure if you have the EGit plugin installed.

  1. Open the "Git Repositories" view
  2. Expand the "org.eclipse.swt" item (assuming you have the org.eclipse.platform.swt project in your EGit repositories view)
  3. Expand the "Remotes" item
  4. Right click the "origin" item, and select "Gerrit configuration"
  5. Fill in your information from Gerrit (username).


For more information about using Gerrit, see the more comprehensive SWT Gerrit page.

Writing a patch

Commit messages

The goal of a commit message is to clarify any ambiguities for the reviewer(s) and any developer who may read the message later. It should be comprehensive and avoid skipping information that was exchanged verbally or via chat. Do not write empty commit messages.

Configuration

All commit messages must be signed off by your first and last name. Please configure your git settings to reflect as such. Additionally when committing, ensure that EGit has generated a change ID, which goes at the bottom of the commit message. It can be generated by clicking one of the buttons at the top right area of the "Commit window".

Structure

An SWT commit message should follow this format:

Bug ID : The bug description should be the same as that in Bugzilla (maybe slightly trimmed)

Description of patch/fix

Test strategy *1

JUnit Tests performed *2

Change-ID: xxxxxxxxxxx (auto generated)

Signed-off-by: Firstname Lastname <email@address.com> (auto generated)

  • Test strategy: steps outlining how to reproduce the issue. Link to a snippet, steps to follow, or a pointer to where to find such instructions.
  • JUnit tests performed: you should mention if you ran the relevant SWT JUnit tests. For example "Ran AllNonBrowserTests on Wayland" and related results. If they don't need to be ran, mention why there is no need to run the tests.

How SWT interacts with native code: native and non-native changes

Before writing an SWT patch, it's important to have a crash course on how SWT interacts with native code. Earlier we mentioned the SWT sources (org.eclipse.swt) and the binaries (such as org.eclipse.swt.gtk.linux.x86_64, as an example). The binaries project in your workspace contains library objects, such as .SO files on Linux, .dll on Windows, etc. Modifying the .classpath allows the SWT sources project to load these library objects and run the SWT from your workspace.

How does this work? Well the SWT sources use Java code to interact with native libraries through JNI. This is done by adding boilerplate JNI function signatures in files like OS.java, for example. SWT Tools then generates the JNI C code which links the Java JNI functions to the actual native calls. The generated code and the JNI function signatures (as well any other Java code) are then merged as one change under the org.eclipse.swt project. This type of patch is considered a native change.

After such a change is merged, the JNI C code does not need to be generated again. Changes that do not modify the JNI code are considered non-native changes, as no additional changes beyond "pure" Java code needs to be made. However SWT does not load every function possible from native libraries, only those that are actually called/needed by SWT. It is not uncommon that a bug fix will require a new native function to be available for use in SWT, in which case its method signature needs to be added to SWT. And thus the process repeats itself.

Writing a non-native change

Non-native changes require no special action -- submit the patch by right clicking the org.eclipse.swt project in the "Git repositories" view and select "Push to Gerrit".

Writing a native change

Native changes are trickier because they require you to rebuild the native bindings. The aforementioned library objects now have to be generated manually in order for SWT to run with local changes. While the library objects do not need to be submitted in your Gerrit change, they do have to be built for testing purposes (otherwise SWT won't run and will complain about library link errors). For instructions on building the library objects, check for a README file in binaries project folder for your platform.

After testing your patch, follow the steps below to submit a native change:

  1. Prepare all Java code, including function signatures in OS.java
  2. Go to Project -> Clean. Clean the SWT sources and binaries projects. Make sure "Build Automatically" is checked in the Project menu.
  3. After cleaning, some *.c and *.h files will show up in the Git staging area. Usually these are files like os.c, os_stats.c, os_stats.h, etc.
  4. Commit these, as well as the Java files (or any other changes relating to your patch) Submit the patch by right clicking the org.eclipse.swt project in the "Git repositories" view and select "Push to Gerrit".

Further reading

Outside of the basics contained in this tutorial, there is additional documentation that provides further insight into development on each platform.

Additionally, there are some workflow tasks which are platform agnostic. You can find these at the SWT workflow documentation.

Back to the top