Further improve general and native binaries build instructions

Author: HannesWell

AGENTS.md

@@ -33,32 +33,15 @@ SWT consists of two main parts:
 ### Build Commands
 ```bash
 # Build the entire project
-mvn clean install
-
-# Build (and include) specific platform native binaries
-mvn clean install '-Dnative=<ws>.<os>.<arch>'
+mvn clean verify
 
 # Skip tests
-mvn clean install -DskipTests
+mvn clean verify -DskipTests
 ```
 
 ### Building native binaries
 
-Run from the repository root, specifying the target platform:
-
-```bash
-# Windows (x86_64)
-mvn clean install '-Dnative=win32.win32.x86_64' -DskipTests
-
-# Linux (x86_64)
-mvn clean install '-Dnative=gtk.linux.x86_64' -DskipTests
-
-# macOS (x86_64 / aarch64)
-mvn clean install '-Dnative=cocoa.macosx.x86_64' -DskipTests
-mvn clean install '-Dnative=cocoa.macosx.aarch64' -DskipTests
-```
-
-For Linux GTK3-only or GTK4-only builds, set `GTK_VERSION=3.0` or `GTK_VERSION=4.0` in the environment before running.
+See `bundles/org.eclipse.swt/Readme.md#building-native-binaries` for instructions how to build the SWT native binaries.
 
 **CRITICAL**: Files like `os.c`, `os_stats.c`, `os_stats.h` are **auto-generated**. Never edit them directly!
 Instead: modify Java source (e.g., `OS.java`), clean/rebuild the project, then run the native build command above.

README.md

@@ -81,21 +81,19 @@ The `while`-loop processes all GUI related events until the shell is disposed wh
 Before exiting, any claimed GUI resources needs to be freed.
 
 
-## Building Native Binaries
-
-Run from the repository root:
+## Building
 
+To build all SWT artifacts and to run all tests,
+execute at the CLI from the repository root:
 ```bash
-# Windows (x86_64)
-mvn clean install '-Dnative=win32.win32.x86_64' -DskipTests
-
-# Linux (x86_64)
-mvn clean install '-Dnative=gtk.linux.x86_64' -DskipTests
-
-# macOS (x86_64 / aarch64)
-mvn clean install '-Dnative=cocoa.macosx.x86_64' -DskipTests
-mvn clean install '-Dnative=cocoa.macosx.aarch64' -DskipTests
+mvn clean verify
 ```
+To build only the artifacts, without testing, run
+```bash
+mvn clean verify -DskipTests
+```
+
+For instructions on building the native binaries of SWT see the section [Building native binaries](bundles/org.eclipse.swt/Readme.md#building-native-binaries).
 
 # Contributing to SWT
 

bundles/org.eclipse.swt/Readme.Linux.md

@@ -16,12 +16,6 @@ You need to install the following on your system:
 * Java 21 JDK (https://adoptium.net/marketplace/?version=21)
 * (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.
-
-See **Building and Testing locally** in [Readme.md](Readme.md) for further instructions.
-
 Additional information on GTK SWT development can be found in Eclipse Wiki:
 
 https://wiki.eclipse.org/SWT/Devel/Gtk/Dev_guide

bundles/org.eclipse.swt/Readme.Win32.md

@@ -18,9 +18,3 @@ You need to install the following on your system:
   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.
 * Java 17 JDK (https://adoptium.net/marketplace/?version=17)
-
-### Building and Testing locally
-
-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.

bundles/org.eclipse.swt/Readme.macOS.md

@@ -90,11 +90,3 @@ You need to install the following on your system:
 
 * XCode Command Line Tools (already present in XCode)
 * Java 21 JDK (https://adoptium.net/marketplace/?version=21)
-
-### 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!

bundles/org.eclipse.swt/Readme.md

@@ -23,15 +23,20 @@ _for example_
   * `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)
+other architectures, like `aarch64` (or `loongarch64` / `ppc64le` for Linux).
+
+For details about the operating system specific SWT implementations and their (build) requirements, see
+- [Linux](Readme.Linux.md)
+- [macOS](Readme.macOS.md)
+- [Windows](Readme.Win32.md)
 
 Dependencies:
 -------------
 
-* **SWT Binaries**  
+* **SWT native binaries**
 
-  Ensure that the fragment matching your _windowingSystem.operatingSystem.cpuArchitecture_
-  (e.g. org.eclipse.swt.gtk.linux.x86_64) is open in 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 and compile the java source code.
 
 Using Assertions:
@@ -56,20 +61,51 @@ Running the snippets:
 * (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:
------------------------------
+## Building native binaries
+
+To build only SWT's native binaries, run from the CLI (at the repository root):
+```bash
+cd binaries/org.eclipse.swt.<ws>.<os>.<arch>
+mvn clean antrun:run@build-native-binaries -Dnative=<ws>.<os>.<arch>
+```
+With the placeholder
+- `<os>` replaced by one of the supported values `macosx`, `linux` or `win32`,
+- `<ws>` replaced by `cocoa` (for Mac), `gtk` (for Linux) or `win32` (for Windows),
+- `<arch>` replaced by `x86_64`, `aarch64`, `ppc64le` or `riscv64`,
+
+according to the targeted platform.
+
+For example to build the native binaries for Linux (GTK) running on x86 64bit CPUs, execute
+```bash
+cd binaries/org.eclipse.swt.gtk.linux.x86_64
+mvn clean antrun:run@build-native-binaries -Dnative=gtk.linux.x86_64
+```
 
-From Eclipse:
+For Linux, to build only the GTK3 binaries, set the environment variable `GTK_VERSION` to value `3.0`,
+to build only GTK4 binaries, set `GTK_VERSION` to `4.0`.
 
-* If necessary, install the **M2E - Maven integration for Eclipse** (see [m2e](https://eclipse.dev/m2e/))
+The Maven build will perform a `clean` and then calls [`build-native-libraries`](https://github.com/eclipse-platform/eclipse.platform.swt/blob/a589ee9fedcfdab60f90902da87f5058faf94be9/binaries/pom.xml#L133-L173),
+which sets the required environment variables and runs the appropriated build script for the current platform (`build.sh`/`build.bat`).
+The script is located in the source folder `Eclipse SWT PI\<current-ws>\library` of the corresponding SWT native fragment.
+
+To build the native binaries as part of a complete build of all SWT artifacts, run:
+```bash
+mvn clean verify -Dnative=<ws>.<os>.<arch>
+```
+using the placeholder from above.
+
+#### Building native binaries from within the Eclipse IDE
+
+* Ensure the **M2E - Maven integration for Eclipse** is installed (see [m2e](https://eclipse.dev/m2e/))
 * Open the **Launch Configurations** dialog.
 * Run the **Maven** configuration called: `Build-SWT-native-binaries-for-running-platform`.
+  * This will build the native binaries for the current target 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.
+Testing the native binaries
+----------------------------
+
+Import and build the SWT project `bundles/org.eclipse.swt` and `binaries/org.eclipse.swt.<ws>.<os>.<arch>` in Eclipse.
 
 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