eclipse-platform · fedejeanne · Apr 24, 2024 · Apr 15, 2024
diff --git a/bundles/org.eclipse.swt/Readme.Linux.md b/bundles/org.eclipse.swt/Readme.Linux.md
@@ -4,40 +4,24 @@ 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
+### Building 64bit natives for GTK
 
 You need to install the following on your system:
 
 * make
 * gcc
-* GTK+ development files (gtk3-devel)
-* Java 17 JDK
+* GTK3/GTK4 development files (see https://www.gtk.org/docs/installations/linux/)
+* Java 17 JDK (https://adoptium.net/marketplace/?version=17)
 * (optional) Webkit for GTK development files (webkit2gtk3-devel)
 
 ### Building and Testing locally
 
 Import and build the SWT project `bundles/org.eclipse.swt` and `binaries/org.eclipse.swt.gtk.linux.${arch}` in Eclipse.
 
-To build SWT natives run the `Build-SWT-native-binaries-for-running-platform` Maven launch configuration.
-Alternatively run the `build.sh` script in `binaries/org.eclipse.swt.gtk.linux.${arch}/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.
+See **Building and Testing locally** in [Readme.md](Readme.md) for further instructions.
 
-You can find additional information on GTK SWT development can be found in
-Eclipse Wiki.
+Additional information on GTK SWT development can be found in Eclipse Wiki:
 
 https://wiki.eclipse.org/SWT/Devel/Gtk/Dev_guide
diff --git a/bundles/org.eclipse.swt/Readme.Win32.md b/bundles/org.eclipse.swt/Readme.Win32.md
@@ -2,77 +2,29 @@
 
 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 SWT windows port is based on the Win32 API.
 
-The natives are compiled via an ant build.xml script with the Microsoft Visual Studio (2019) C++ compiler.
+The natives are compiled using the Microsoft Visual Studio (2019) C++ compiler.
 
-# Development overview
-SWT is made up of 2 parts, Java and the natives (written in C).
+## Building Natives.
 
-* **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:
-  https://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)
-	- https://github.com/eclipse-platform/eclipse.platform.swt
-* From swt repo, import most projects (except Cocoa/Gtk, root 'swt' project, once)
-* And 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):
+### Building 64bit natives
+(Last tested on Win10 64 bit & Java 17. April 2024):
 
 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 11. Oracle JDK or IBM JDK:  
-  http://www.oracle.com/technetwork/java/javase/overview/java8-2100321.html  
-  https://developer.ibm.com/javasdk/downloads/  
+* Java 17 JDK (https://adoptium.net/marketplace/?version=17)
 
 ### 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.
-
+Import and build the SWT project `bundles/org.eclipse.swt` and `binaries/org.eclipse.swt.win32.win32.${arch}` in Eclipse.
+
+See **Building and Testing locally** in [Readme.md](Readme.md) for further instructions.
+
 ## (More advanced) (Optional) Building Webkit
 Note, I.E is the default backend. But Webkit is also a possible alternative Browser backend.
 
@@ -99,25 +51,3 @@ Steps:
   - `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
-
-
-
diff --git a/bundles/org.eclipse.swt/Readme.macOS.md b/bundles/org.eclipse.swt/Readme.macOS.md
@@ -82,13 +82,19 @@ More information on how to use the generator is available [here](https://www.ecl
 this information into this readme.
 
 
-Compiling native libs
----------------------
+## Building Natives
 
-This is done from within the binaries project.
+### Building 64bit natives for Cocoa
 
-    cd <eclipse.platform.swt>/binaries/org.eclipse.swt.cocoa.macosx.x86_64
-    mvn clean package -Dnative=cocoa.macosx.x86_64
+You need to install the following on your system:
 
+* XCode Command Line Tools (already present in XCode)
+* Java 17 JDK (https://adoptium.net/marketplace/?version=17)
 
-Happy development!
+### Building and Testing locally
+
+Import and build the SWT project `bundles/org.eclipse.swt` and `binaries/org.eclipse.swt.cocoa.macosx.${arch}` in Eclipse.
+
+See **Building and Testing locally** in [Readme.md](Readme.md) for further instructions.
+
+Happy development!
diff --git a/bundles/org.eclipse.swt/Readme.md b/bundles/org.eclipse.swt/Readme.md
@@ -3,12 +3,34 @@ org.eclipse.swt
 
 Main plug-in for the SWT user interface library.
 
+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 and you can just
+use the pre-compiled libraries in the binary repository instead.
+
+* **Natives Part**
+
+Make sure the binary project for your platform is imported and open in your workspace,
+_for example_
+  * `binaries/org.eclipse.swt.win32.win32.x86_64` for Windows or
+  * `binaries/org.eclipse.swt.gtk.linux.x86_64` for Linux or
+  * `binaries/org.eclipse.swt.cocoa.macosx.x86_64` for Mac
+
+These examples refer to the architecture `x86_64` but there are other projects for
+other architectures, like `aarch64` (or `loongarch64` / `ppc64le` for Linux)
+
 Dependencies:
 -------------
 
 * **SWT Binaries**  
 
-  Ensure that the fragment matching your windowingSystem.operatingSystem.cpuArchitecture  
+  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 and compile the java source code.
 
@@ -25,6 +47,34 @@ Assertions look like:
 
 See: https://docs.oracle.com/javase/8/docs/technotes/guides/language/assert.html
 
+Running the snippets:
+---------------------
+
+* Download & install Java *JDK* (Last tested on JDK17)
+* Download and install a pre-configured Eclipse SDK using Oomph as described in [Contributing.md](https://github.com/eclipse-platform/.github/blob/main/CONTRIBUTING.md#creating-an-eclipse-development-environment).
+* (Optionally) You can uncheck everything that has nothing to do with SWT from the **Projects** selection page
+* (Optionally) install CDT from marketplace if you want to work on C/Native parts of SWT.
+* You should be able to run snippets now. (_e.g._ `Snippet1`).
+
+Building and Testing locally:
+-----------------------------
+
+From Eclipse:
+
+* If necessary, install the **M2E - Maven integration for Eclipse** (see [m2e](https://eclipse.dev/m2e/))
+* Open the **Launch Configurations** dialog.
+* Run the **Maven** configuration called: `Build-SWT-native-binaries-for-running-platform`.
+* If compile fails, inspect build log for warnings, they can point out issues in your configuration.
+
+The Maven configuration will perform a `clean` and then call [`build-native-libraries`](https://github.com/eclipse-platform/eclipse.platform.swt/blob/979d3f1580b4786aee1efe046da8a6f836300804/binaries/pom.xml#L92-L134),
+which sets the required environment variables and then runs the appropriate
+build script for the current platform (`build.sh`/`build.bat`). The script is located in the
+source folder `Eclipse SWT PI\<current-ws>\library` in the appropriate fragment.
+
+To test if you binaries actually get used, you could try to revert back to some older version and
+run a snippet, you should get the 'missing natives' error. Then if you build the natives
+and the snippet(s) work, it means that you've build them successfully.
+
 More Information:
 -----------------