# About

The SWT Linux port is based on the GTK.

The natives are build using make and (by default) gcc.

# Development overview
SWT is made up of 2 parts, Java and the natives (written in C).

* **Java Part**
If you only make changes in the Java part or need to configure SWT for running
snippets, then you don't need to recompile the natives, instead, you can just
use the pre-compiled libraries in the binary repository.

* **Natives Part**
Make sure the binary project for your platform is imported and open in your
workspace.

## Building Natives

### Building 64bit natives for GTK3

You need to install the following on your system:

* make
* gcc
* GTK+ development files (gtk3-devel)
* Java 8 or 11 JDK
* (optional) Webkit for GTK development files (webkit2gtk3-devel)

### Building and Testing locally

Import and build the SWT project `bundles/org.eclipse.swt` in Eclipse. See the
platform independent Readme for how to set the .classpath. This will populate
the `bundles/org.eclipse.swt/bin/library` with the native code and build files.

To build SWT natives run the `build.sh` script in `./bin/library` directory. To
use the locally build natives run the build script with the 'install' argument
(`./build.sh install`) or --help to see more options.

You can find additional information on GTK SWT development can be found in
Eclipse Wiki.

https://wiki.eclipse.org/SWT/Devel/Gtk/Dev_guide

# About

The document is structured so that you only need to read up to the point that you require, with advanced topics at the bottom.

The SWT windows port is based on the Win32 api.

The natives are compiled via an ant build.xml script with the Microsoft Visual Studio (2017) C++ compiler.

# Development overview
SWT is made up of 2 parts, Java and the natives (written in C).

* **Java Part**
If you only make changes in the Java part or need to configure SWT for running snippets,
then you don't need to recompile the natives, instead, you can just use the pre-compiled
libraries in the binary repository.

* **Natives Part**
(Make sure the binary project for your platform is imported and open in your workspace).

## Configure workspace to run snippets.

* Download & install Java *JDK* (Last tested on JDK9) http://www.oracle.com/technetwork/java/javase/downloads/index.html
* Download and install Eclipse. Either the "Eclipse IDE for Eclipse Committers" or a recent integration build:
  http://download.eclipse.org/eclipse/downloads/
* (Optionally) install CDT from marketplace if you want to work on C/Native parts of SWT.
* (if not already installed) installed EGit integration.
* Open the git perspective. Add the following two repositories, which can be found on: (use git protocol)
	- http://git.eclipse.org/c/platform/eclipse.platform.swt.git/
	- http://git.eclipse.org/c/platform/eclipse.platform.swt.binaries.git/
* From swt repo, import most projects (except Cocoa/Gtk, root 'swt' project, once)
* In org.eclipse.swt project, you need to copy .classpath_win32 to .classpath  & refresh/rebuild workspace.
  (This can be done via command line or by not-filtering *.resources in package view).
* From swt.binary repo, import the project that reflects your platform.
* In the snippet project, add the swt project as dependency to launch snippets.
* You should be able to run snippets now. (e.g Snippet1).

## (Advanced) Building Natives.

### Building just 64bit natives with no Webkit
(Last tested on Win10 64 bit & Java 11. May 2019):

You need to install the following on your system:

* Microsoft Visual Studio - Community and Windows 10 SDK:  (1*)
  https://visualstudio.microsoft.com/vs/community/
  Either select the components "MSVC C++-x64/x86-Buildtools" and "Windows 10 SDK"
  or the workload "Desktop development with C++" which includes the required components and some more.
* (Optional) Install Cygwin
* Install Java 8 or 11. Oracle JDK or IBM JDK:
  http://www.oracle.com/technetwork/java/javase/overview/java8-2100321.html
  https://developer.ibm.com/javasdk/downloads/

### Building and Testing locally

In the binary git repo, in the windows project, you can build the natives via the build.xml. To do so:

* In Eclipse, in the binary project org.eclipse.swt.win32.win32.x86_64, right click on build.xml:
* Run As -> Ant Build ...
* On the Targets tab check the build_libraries target  (it should be the only one check for just the natives).
* On the JRE tab select "Run in the same JRE as the workspace"
* On the Refresh tab check "Refresh resources upon completion" to refresh your workspace after running the build; this ensures that Eclipse will pick up the fresh binaries
* Press the "Run" button to begin.
* If compile fails, inspect build log for warnings, they can point out issues in your configuration.

To test if you binaries actually get used, you could try to checkout an older binary repo commit with old
bindings. Then try to run a snippet and get the 'missing natives' error. Then if you build the natives
and the snippet(s) work, it shows that you've build them successfully.

### Optional additional configuration
* Install and configure Cygwin SSH Server on Windows. (Make sure 'openssh' package is installed).
  See: https://docs.oracle.com/cd/E24628_01/install.121/e22624/preinstall_req_cygwin_ssh.htm#EMBSC281
* Configure the machine for password-less SSH authentication with the Hudson machine.
  For more details you can refer: http://users.cecs.anu.edu.au/~xzhang/pubDoc/IT/SSH%20without%20password%20from%20Windows.htm
  Sharing some key steps below(which I recall):
  - Generate the 'dsa' public/private key from your "swtbuild" account from windows machine.
  - Now login to the Hudson machine with "swtbuild" account.
  - Copy the public keys and register then on the Hudson machine.. this should enable password-less authentication.

## (More advanced) (Optional) Building Webkit
Note, I.E is the default backend. But Webkit is also a possible alternative Browser backend.

Disclaimer:

Note Webkit SDKs are an older version being consumed by SWT native build process and Webkit build binaries are no more available for download in public Webkit download page (https://webkit.org/downloads/)

But WebKit-r72896 sources are still avilable for download via either of:
https://builds-nightly.webkit.org/files/trunk/src/WebKit-r72896.tar.bz2
http://build.eclipse.org/eclipse/swt/WebKit-r72896.tar.bz2

Webkit SDKs:

* WebKit-r72896 http://build.eclipse.org/eclipse/swt/WebKit-r72896.zip
* WebKitSupportLibrary http://build.eclipse.org/eclipse/swt/WebKitSupportLibrary.zip


Steps:

* Create an SWT Build dir such as `C:\SWT_BUILD_DIR`
* In your enviornment:
    `set SWT_BUILD_DIR=YOUR.DIR`
* Unzip two Webkit SDks into:
  - `SWT_BUILD_DIR\Webkit\r72896`
  - `SWT_BLUID_DIR\Webkit\SupportLibrary`
  - (Note: SWT's Webkit support exists for SWT 32bit on Windows, so Webkit SDKs are consumed only by the SWT 32bit build process)

## Custom Java paths and 32 bit builds

You can specify a specific java sdk via:
  `set SWT_JAVA_HOME=<YOUR_PATH>`

To do a 32 bit build, install a 32bit java & specify it's path or put it into:
`SWT_BUILD_DIR\Java\Oracle\jdk1.8.0-latest\x86`

For building windows native build for 32bit, you need to convert the source to 32bit first, by running 'replace.64.to.32' target.
Once sources are converted to 32bit you can run the 'build_libraries' target for ${workspace_loc:/org.eclipse.swt.win32.win32.x86/build.xml}

## Hudson
(Optional for local setup)
Now you can point the Windows hudson job to this machine and trigger a native build.
Note: For testing purpose from hudson, temporarily turn the nativeChanges flag to 'true' to force a native build compilation.

# Footnotes
[1]  https://bugs.eclipse.org/bugs/show_bug.cgi?id=526802

macOS Development for org.eclipse.swt
=====================================

Please follow the following pattern for macOS development:

* Copy `.classpath_cocoa` to `.classpath`
* Update `.bridgesupport` files when necessary, i.e. consuming new api in newer macOS versions
* Generate native and Java code using `MacGenerator`



Updating .bridgesupport files
-----------------------------

The `.bridgesupport` files are located in `Eclipse SWT PI/cocoa/org/eclipse/swt/internal/cocoa`. They are
generated using the tool `gen_bridge_metadata` which is included with macOS (Xcode).

Please note that we use an undocumented option with the `gen_bridge_metadata` to generate a complete XML including the `declared_type`.
It's not clear why that option is undocumented.

FWIW, there seems to be an issue with the tool that is included in macOS. After lots of reading and asking questions, it seems that
the best approach is to build a current version yourself and launch it from there
(see tip [here](https://twitter.com/watson1978/status/786929396711948288)).

    git clone https://github.com/HipByte/BridgeSupport.git
    cd BridgeSupport
    make

    # once done let's define a function to make generation more convenient
    #
    # gen_bridge_metadata_complete() {
    #    RUBYLIB=./DSTROOT/System/Library/BridgeSupport/ruby-2.0                 \
    #    ./gen_bridge_metadata.rb                                                \
    #        --format complete                                                   \
    #        --cflags "-I.                                                       \
    #                  -isysroot /                                               \
    #                  -mmacosx-version-min=10.12                                \
    #                  -DTARGET_OS_MAC=1                                         \
    #                  -D__ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__=101200    \
    #                  -F/System/Library/Frameworks                              \
    #                  -framework $1 "                                           \
    #        --framework /System/Library/Frameworks/$1.framework
    #  }
    #
    # (now all in one line)
    gen_bridge_metadata_complete() { RUBYLIB=$(pwd)/DSTROOT/System/Library/BridgeSupport/ruby-2.0 $(pwd)/gen_bridge_metadata.rb --format complete --cflags "-I. -isysroot / -mmacosx-version-min=10.12 -DTARGET_OS_MAC=1 -D__ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__=101200 -F/System/Library/Frameworks -framework $1" --framework /System/Library/Frameworks/$1.framework; }

Once done with that, go back into the `org.eclipse.swt` bundle directory and execute the following commands to generate all the `.bridgesupport` files.

     # should be executed from the BridgeSupport directory
     # (where the gen_bridge_metadata is located)
     #
     gen_bridge_metadata_complete AppKit            > '<org.eclipse.swt>/Eclipse SWT PI/cocoa/org/eclipse/swt/internal/cocoa/AppKitFull.bridgesupport'
     gen_bridge_metadata_complete CoreFoundation    > '<org.eclipse.swt>/Eclipse SWT PI/cocoa/org/eclipse/swt/internal/cocoa/CoreFoundationFull.bridgesupport'
     gen_bridge_metadata_complete CoreText          > '<org.eclipse.swt>/Eclipse SWT PI/cocoa/org/eclipse/swt/internal/cocoa/CoreTextFull.bridgesupport'
     gen_bridge_metadata_complete Foundation        > '<org.eclipse.swt>/Eclipse SWT PI/cocoa/org/eclipse/swt/internal/cocoa/FoundationFull.bridgesupport'
     gen_bridge_metadata_complete SecurityInterface > '<org.eclipse.swt>/Eclipse SWT PI/cocoa/org/eclipse/swt/internal/cocoa/SecurityInterfaceFull.bridgesupport'
     gen_bridge_metadata_complete WebKit.framework  > '<org.eclipse.swt>/Eclipse SWT PI/cocoa/org/eclipse/swt/internal/cocoa/WebKitFull.bridgesupport'

The `.extras` files are created by the `MacGenerator` later. They store additional information (eg., how types are mapped to SWT).
We don't need to worry about them now.


Generate code using MacGenerator
--------------------------------

There are two possible option:

* Install the `org.eclipse.swt.tools` plug-in into Eclipse and use the view.
* Import the `org.eclipse.swt.tools` project into a second workspace and run `MacGeneratorUI` as vanilla Java application.

Running `MacGeneratorUI` from within a second workspace has the benefit that you can tweak the `MacGeneratorUI` tool should you run into any issues.
It should consume `org.eclipse.swt` from a target platform (not in source form). The project `org.eclipse.swt.tools.base` and `org.eclipse.swt.tools.spies`
should also be in that second workspace.

Please note that `MacGeneratorUI` makes certain assumptions (hard-coded) about the environment and paths. That's usually fine
because all is within the same Git repository. It should only break when things are restructured without adjusting it. However, that's also
the reason why you should run it from within a second workspace with SWT consumed from a target platform. It modifies SWT *in* the same
Git repo. If SWT is also in the same workspace, you will run into issues once some generation breaks SWT.

More information on how to use the generator is available [here](https://www.eclipse.org/swt/macgen.php). Volunteers wanted to convert
this information into this readme.


Compiling native libs
---------------------

This is done from within the binaries project.

    cd <eclipse.platform.swt.binaries>/bundles/org.eclipse.swt.cocoa.macosx.x86_64
    mvn clean package -Dnative=cocoa.macosx.x86_64 -Pbuild-individual-bundles


Happy development!

org.eclipse.swt
===============

Main plug-in for the SWT user interface library.

Setting the classpath:
----------------------

To compile this project, you need to set the classpath specific for your operating and windowing system.
For this, rename one of the following files to `.classpath`:

* .classpath_win32 - Windows
* .classpath_cocoa - Mac OS X
* .classpath_gtk - Linux and all Unix variants

Similar class paths renaming should be done for ./examples/org.eclipse.swt.snippets/

To see these files, you may have to remove the filter for ".* resources":
* In the Project Explorer: view menu > Customize View... > Filters
* In the Package Explorer: view menu > Filters...


Dependencies:
-------------

* **SWT Binaries**
  You also need to clone the binary Git repository:
  https://git.eclipse.org/r/#/admin/projects/platform/eclipse.platform.swt.binaries
  and import the project for your platform into your workspace.

  Ensure that the fragment matching your windowingSystem.operatingSystem.cpuArchitecture
  (e.g. org.eclipse.swt.gtk.linux.x86_64) is open in your workspace.
  The fragments provide the platform-specific native libraries.

Using Assertions:
----------------
Assertions are added to the code. These don't run in production, but they do when:
* JUnits are ran, they turn on assertions by default.
* If you run a java run configuration and add '-ea' to the 'VM Arguments'

Assertions look like:

	assert expression ;
	assert expression : msg ;

See: https://docs.oracle.com/javase/8/docs/technotes/guides/language/assert.html

More Information:
-----------------

See the [Readme.md](../../Readme.md) in the main directory of the Git repository for this project to learn more about SWT development.