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.
Difference between revisions of "SWT/Beginners"
(→Writing a patch) |
(→Download sources and binaries) |
||
| 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. | ||
| − | == Download sources and binaries == | + | == Download/import sources and binaries == |
SWT works using two code repositories: | SWT works using two code repositories: | ||
# The [https://git.eclipse.org/c/platform/eclipse.platform.swt.git/ source code], which contains Java and JNI source code for all widgets. This where 99% of all changes belong. | # The [https://git.eclipse.org/c/platform/eclipse.platform.swt.git/ source code], which contains Java and JNI source code for all widgets. This where 99% of all changes belong. | ||
Revision as of 14:10, 17 August 2018
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.
Contents
Getting started
Please note this article is still being written and is not final.
Download/import sources and binaries
SWT works using two code repositories:
- The source code, which contains Java and JNI source code for all widgets. This where 99% of all changes belong.
- 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.
Eclipse Plugins
Download and install SWT tools. Other than that, you may find the following plugins useful (not mandatory for SWT development):
Gerrit configuration
Eclipse/SWT uses a code review tool called Gerrit. It's quite easy to configure if you have the EGit plugin installed.
- Open the "Git Repositories" view
- Expand the "org.eclipse.swt" item
- Expand the "Remotes" item
- Right click the "origin" item, and select "Gerrit configuration"
- Fill in your information from gerrit (username).
Writing a patch
Non-native vs native changes
SWT uses 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. 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 which 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. Often 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.
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"
- 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
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:
- Clone the eclipse/news repo
- 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)
- Upload the change to the gerrit repo for eclipse/news and add a committer from your component to review it