diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000000..74266002f1a --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,157 @@ +# GitHub Copilot Instructions for Eclipse Platform SWT + +## Project Overview + +This is the **Eclipse Platform SWT** (Standard Widget Toolkit) repository - a cross-platform GUI library for JVM-based desktop applications. SWT is the foundation for the Eclipse IDE and many other desktop applications. + +## Architecture + +SWT consists of two main parts: +1. **Java code** - Platform-independent widget implementations and APIs +2. **Native code (C)** - Platform-specific implementations using native windowing systems + +### Platform Support +- **Linux**: GTK3 (stable) and GTK4 (experimental) +- **Windows**: Win32 API +- **macOS**: Cocoa + +### Key Components +- `bundles/org.eclipse.swt` - Main SWT bundle with Java and native code +- `bundles/org.eclipse.swt.svg` - SVG support +- `bundles/org.eclipse.swt.tools` - Build and development tools +- `binaries/` - Platform-specific binary fragments +- `examples/` - Example code and snippets +- `tests/` - JUnit tests + +## Build System + +### Technology Stack +- **Build Tool**: Maven with Tycho plugin +- **Java Version**: Java 17 (compiler target), Java 21 (build/runtime in CI) +- **Supported Architectures**: x86_64, aarch64, loongarch64, ppc64le, riscv64 + +### Build Commands +```bash +# Build the entire project +mvn clean verify + +# Build specific platform binary +mvn clean verify -Dnative=gtk.linux.x86_64 + +# Skip tests +mvn clean verify -DskipTests +``` + +### Building Natives +To rebuild native libraries: +1. Ensure the appropriate binary project is imported in your workspace (e.g., `binaries/org.eclipse.swt.gtk.linux.x86_64`) +2. Native build scripts are platform-specific and located in the binary fragments +3. For GTK on Linux: See `docs/gtk-dev-guide.md` for detailed instructions + +## Coding Standards + +### Java Code +- **Indentation**: Tabs (as per Eclipse project conventions) +- **Line Length**: Keep lines reasonably short, no strict limit +- **Naming**: Follow standard Java conventions (camelCase for methods/variables, PascalCase for classes) +- **Comments**: Use JavaDoc for public APIs; inline comments where needed for clarity +- **Assertions**: Use assertions for runtime checks (enabled in tests, disabled in production) + +### Native Code (C) +- **Platform-specific**: Code goes in platform folders (gtk/, win32/, cocoa/) +- **JNI**: Communication between Java and native code uses JNI +- **OS.java**: Central file for native method declarations + +### Code Organization +- Platform-independent code: `bundles/org.eclipse.swt/Eclipse SWT/common/` +- Platform-specific code: `bundles/org.eclipse.swt/Eclipse SWT/{gtk,win32,cocoa}/` +- Emulated widgets: `bundles/org.eclipse.swt/Eclipse SWT/emulated/` + +## Testing + +### Running Tests +```bash +# Run all tests +mvn clean verify + +# Run specific test class +mvn test -Dtest=ClassName +``` + +### Test Location +- Main tests: `tests/org.eclipse.swt.tests/` +- Tests automatically run with assertions enabled + +### Writing Tests +- Follow existing test patterns in the repository +- Platform-specific tests should be in appropriate fragments +- Use JUnit for all tests + +## Development Workflow + +### Making Changes + +1. **Java-only changes**: Can be tested without rebuilding natives +2. **Native changes**: Require rebuilding the platform-specific binary fragment +3. **Cross-platform changes**: Test on all affected platforms + +### Pull Request Guidelines +- Sign the Eclipse Foundation Contributor License Agreement (CLA) +- Ensure all tests pass +- Follow the contribution guidelines in CONTRIBUTING.md +- Reference related GitHub issues + +### CI/CD +- GitHub Actions runs builds on Linux, Windows, and macOS +- Matrix builds test with Java 21 on all platforms +- All tests must pass before merge + +## Important Files and Patterns + +### Key Files +- `OS.java` - Central native method declarations for platform integration +- `Display.java` - Main event loop and display management +- `Widget.java` - Base class for all widgets +- `Control.java` - Base class for all controls + +### Common Patterns +- **Resource Management**: Always dispose of SWT resources (Display, Shell, Image, etc.) +- **Threading**: UI operations must run on the UI thread (use `Display.asyncExec()` or `Display.syncExec()`) +- **Event Handling**: Use listeners (typed or untyped) for event handling +- **Layout Management**: Use layout managers (GridLayout, FillLayout, etc.) instead of absolute positioning + +## Platform-Specific Considerations + +### GTK (Linux) +- Communication from Java to C happens through `OS.java` +- GTK3 is stable; GTK4 is experimental +- Can be toggled using `SWT_GTK4` environment variable +- See `docs/gtk-dev-guide.md` for comprehensive GTK development guide + +### Windows +- Uses Win32 API +- WebView2 support available (see `Readme.WebView2.md`) +- Platform-specific code in `win32/` directories + +### macOS +- Uses Cocoa framework +- Supports both x86_64 and aarch64 (Apple Silicon) +- Platform-specific code in `cocoa/` directories + +## Resources + +- **Main README**: [`README.md`](../README.md) +- **Contributing Guide**: [`CONTRIBUTING.md`](../CONTRIBUTING.md) +- **GTK Development Guide**: [`docs/gtk-dev-guide.md`](../docs/gtk-dev-guide.md) +- **GitHub Discussions**: Use for questions and general discussions +- **GitHub Issues**: Use for bug reports and feature requests + +## Tips for Copilot + +- When generating SWT code, always include proper resource disposal +- Remember that SWT is not thread-safe - UI operations need Display.syncExec/asyncExec +- Platform-specific code should go in the appropriate platform directory +- When adding native methods, declare them in `OS.java` first +- Follow existing code patterns in the repository for consistency +- Use snippets in `examples/org.eclipse.swt.snippets/` as reference examples +- Consider cross-platform compatibility when making changes diff --git a/.github/instructions/GTK.instructions.md b/.github/instructions/GTK.instructions.md new file mode 100644 index 00000000000..9192f68c909 --- /dev/null +++ b/.github/instructions/GTK.instructions.md @@ -0,0 +1,7 @@ +--- +applyTo: "bundles/org.eclipse.swt/Eclipse SWT PI/gtk/library/*.c,bundles/org.eclipse.swt/Eclipse SWT PI/gtk/library/*.h" +--- + +- Always carefully investigate exsiting GTK functions the gtk-dev files are installed in the system +- The GTK docs can be found here https://www.gtk.org/docs/ +- Be carefull between the difference of GTK3 and GTK4 we need to check for specific versions in some places already diff --git a/bundles/org.eclipse.swt.tools/JNI Generation/org/eclipse/swt/tools/internal/JNIGeneratorCLI.java b/bundles/org.eclipse.swt.tools/JNI Generation/org/eclipse/swt/tools/internal/JNIGeneratorCLI.java new file mode 100644 index 00000000000..8c9c6ca694f --- /dev/null +++ b/bundles/org.eclipse.swt.tools/JNI Generation/org/eclipse/swt/tools/internal/JNIGeneratorCLI.java @@ -0,0 +1,101 @@ +/******************************************************************************* + * Copyright (c) 2025 Eclipse Contributors and others. + * + * This program and the accompanying materials + * are made available under the terms of the Eclipse Public License 2.0 + * which accompanies this distribution, and is available at + * https://www.eclipse.org/legal/epl-2.0/ + * + * SPDX-License-Identifier: EPL-2.0 + * + * Contributors: + * Initial implementation for CLI support + *******************************************************************************/ +package org.eclipse.swt.tools.internal; + +/** + * Command-line wrapper for JNIGeneratorApp that properly handles arguments. + * This class provides a more robust CLI interface than the original main method. + */ +public class JNIGeneratorCLI { + + public static void main(String[] args) { + if (args.length > 0 && (args[0].equals("-h") || args[0].equals("--help") || args[0].equals("help"))) { + printUsage(); + return; + } + + JNIGeneratorApp gen = new JNIGeneratorApp(); + + // Handle "all" or "*" to generate for all platforms + if (args.length == 1 && (args[0].equals("*") || args[0].equals("all"))) { + gen.generateAll(); + return; + } + + // Parse command line arguments + String mainClassName = null; + String outputDir = null; + String classesDir = null; + + if (args.length > 0) { + mainClassName = args[0]; + } + if (args.length > 1) { + outputDir = args[1]; + } + if (args.length > 2) { + classesDir = args[2]; + } + + // Validate required arguments + if (mainClassName == null || outputDir == null) { + System.err.println("Error: mainClassName and outputDir are required."); + System.err.println(); + printUsage(); + System.exit(1); + } + + // Set up the generator with proper argument order + // Important: set output dir and classes dir BEFORE main class name + gen.setOutputDir(outputDir); + if (classesDir != null) { + gen.setClassesDir(classesDir); + } + + // Now set the main class name - this will work because outputDir is already set + gen.setMainClassName(mainClassName, outputDir, classesDir); + + // Generate the JNI code + gen.generate(); + } + + private static void printUsage() { + System.out.println("JNI Generator - Generates C/JNI code from annotated Java classes"); + System.out.println(); + System.out.println("Usage:"); + System.out.println(" java -jar org.eclipse.swt.tools--jar-with-dependencies.jar [classesDir]"); + System.out.println(" java -jar org.eclipse.swt.tools--jar-with-dependencies.jar all"); + System.out.println(" java -jar org.eclipse.swt.tools--jar-with-dependencies.jar --help"); + System.out.println(); + System.out.println("Arguments:"); + System.out.println(" mainClassName - Fully qualified name of the main OS class"); + System.out.println(" (e.g., org.eclipse.swt.internal.gtk.OS)"); + System.out.println(" outputDir - Directory where generated C files will be written"); + System.out.println(" (must end with / or \\)"); + System.out.println(" classesDir - Optional: Directory containing Java source files"); + System.out.println(" (defaults to parent of outputDir)"); + System.out.println(" all | * - Generate for all platforms defined in metadata"); + System.out.println(); + System.out.println("Examples:"); + System.out.println(" # Generate GTK bindings to /path/to/library/"); + System.out.println(" java -jar swt-tools.jar org.eclipse.swt.internal.gtk.OS /path/to/library/"); + System.out.println(); + System.out.println(" # Generate with explicit source directory"); + System.out.println(" java -jar swt-tools.jar org.eclipse.swt.internal.gtk.OS \\"); + System.out.println(" /path/to/library/ /path/to/sources/"); + System.out.println(); + System.out.println(" # Generate for all configured platforms"); + System.out.println(" java -jar swt-tools.jar all"); + } +} diff --git a/bundles/org.eclipse.swt.tools/README.md b/bundles/org.eclipse.swt.tools/README.md new file mode 100644 index 00000000000..1d3a7d6670b --- /dev/null +++ b/bundles/org.eclipse.swt.tools/README.md @@ -0,0 +1,138 @@ +# SWT Tools + +This bundle provides various development tools for Eclipse SWT (Standard Widget Toolkit). + +## Available Tools + +### JNI Generator + +The JNI Generator is the primary tool in this bundle. It automatically generates native C/JNI code from annotated Java classes, significantly reducing the manual effort required to maintain JNI bindings. + +#### What it does + +The JNI Generator: +- Scans Java source files for native methods and annotated classes +- Generates corresponding C header files (`*.h`) +- Generates C implementation files (`*.c`) with JNI wrapper code +- Generates structs header and implementation files for data structures +- Generates statistics tracking code for native method calls +- Updates metadata files used for code generation + +#### Location + +The JNI Generator source code is located in: +``` +bundles/org.eclipse.swt.tools/JNI Generation/org/eclipse/swt/tools/internal/ +``` + +Key classes: +- `JNIGeneratorApp.java` - Main entry point with CLI support +- `JNIGenerator.java` - Base generator class +- `NativesGenerator.java` - Generates native method wrappers +- `StructsGenerator.java` - Generates struct accessors +- `MetaDataGenerator.java` - Generates metadata files +- `StatsGenerator.java` - Generates statistics tracking code + +#### Usage in Eclipse IDE + +The JNI Generator is integrated into Eclipse as a builder: +1. Configure the builder in your Eclipse project +2. The generator runs automatically when Java source files change +3. It regenerates the native code based on annotations in the Java code + +#### Command Line Usage + +You can run the JNI Generator from the command line using the provided fat jar: + +```bash +# Display help +java -jar org.eclipse.swt.tools--jar-with-dependencies.jar --help + +# Generate for specific main class +java -jar org.eclipse.swt.tools--jar-with-dependencies.jar + +# Generate all configured platforms +java -jar org.eclipse.swt.tools--jar-with-dependencies.jar all +``` + +**Parameters:** +- `mainClassName` - Fully qualified name of the main OS class (e.g., `org.eclipse.swt.internal.gtk.OS`) +- `outputDir` - Directory where generated C files will be written (must end with `/` or `\`) +- `classesDir` - Directory containing Java source files (required for finding the source to parse) +- `all` or `*` - Generate for all platforms defined in metadata + +**Example:** +```bash +# Generate GTK bindings +java -jar org.eclipse.swt.tools-3.110.900-SNAPSHOT-jar-with-dependencies.jar \ + org.eclipse.swt.internal.gtk.OS \ + /path/to/output/ \ + /path/to/swt/sources/Eclipse\ SWT\ PI/gtk/ + +# This will generate: +# - os.c (JNI native method implementations) +# - os_structs.h and os_structs.c (structure accessors) +# - os_stats.h and os_stats.c (statistics tracking) +``` + +**Note:** The generator requires access to the Java source files (not just compiled classes) because it uses the Eclipse JDT AST parser to analyze annotations and generate appropriate C code. + +#### Building the Fat Jar + +To build the standalone JAR with all dependencies: + +```bash +cd bundles/org.eclipse.swt.tools +mvn clean package +``` + +The fat jar will be created at: +``` +target/org.eclipse.swt.tools--jar-with-dependencies.jar +``` + +#### How it Works + +1. **Source Scanning**: The generator reads Java source files using the Eclipse JDT Abstract Syntax Tree (AST) parser +2. **Metadata Processing**: It reads metadata from `.properties` files that contain generation directives and custom mappings +3. **Code Generation**: Based on annotations and metadata, it generates: + - Native method signatures in C + - JNI function implementations + - Structure field accessors + - Type conversions between Java and C +4. **File Output**: Generated files are written to the specified output directory, typically the platform-specific `library/` folder + +#### Annotations and Metadata + +The generator uses special annotations in Java source files: +- Method flags (e.g., `@flags=no_gen` to skip generation) +- Parameter mappings (e.g., array types, buffer types) +- Custom C code snippets +- Structure field mappings + +Metadata is stored in `.properties` files in the same package as the Java sources. + +### Other Tools + +- **Mac Generator**: Tools for generating macOS-specific bindings (located in `Mac Generation/`) +- **Icon Exe**: Windows icon embedding tools (located in `Icon Exe/`) +- **JavadocBasher**: Javadoc processing utilities (located in `JavadocBasher/`) + +## Dependencies + +The JNI Generator requires: +- Java 17 or later +- Eclipse JDT Core (for AST parsing) +- SWT library (for platform detection) + +## Development + +This is an Eclipse plugin bundle and can be developed using: +- Eclipse IDE with Plugin Development Environment (PDE) +- Maven with Tycho for command-line builds + +## License + +This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-2.0/ + +SPDX-License-Identifier: EPL-2.0 diff --git a/bundles/org.eclipse.swt.tools/pom.xml b/bundles/org.eclipse.swt.tools/pom.xml new file mode 100644 index 00000000000..dc213247df7 --- /dev/null +++ b/bundles/org.eclipse.swt.tools/pom.xml @@ -0,0 +1,156 @@ + + + + + 4.0.0 + + org.eclipse.platform + org.eclipse.swt.tools + 3.110.900-SNAPSHOT + jar + + SWT Tools + Eclipse SWT development tools including JNI Generator for command-line use + + + UTF-8 + 17 + 17 + + + + + + org.eclipse.jdt + org.eclipse.jdt.core + 3.38.0 + + + + + org.eclipse.platform + org.eclipse.core.runtime + 3.31.100 + + + + + org.eclipse.platform + org.eclipse.core.resources + 3.20.100 + + + + + org.eclipse.platform + org.eclipse.swt.gtk.linux.x86_64 + 3.126.0 + true + + + + + org.eclipse.platform + org.eclipse.ui + 3.205.100 + + + + + org.eclipse.platform + org.eclipse.jface.text + 3.25.0 + + + + + + . + + + . + + **/*.properties + META-INF/** + plugin.xml + about.html + + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.13.0 + + + + src/**/*.java + JNI Generation/**/*.java + Mac Generation/**/*.java + Icon Exe/**/*.java + JavadocBasher/**/*.java + + + + + + + org.apache.maven.plugins + maven-assembly-plugin + 3.7.1 + + + make-assembly + package + + single + + + + + + src/assembly/jar-with-dependencies.xml + + + + org.eclipse.swt.tools.internal.JNIGeneratorCLI + + + + + + + + + + eclipse-releases + https://repo.eclipse.org/content/repositories/releases/ + + + eclipse-snapshots + https://repo.eclipse.org/content/repositories/snapshots/ + + true + + + + + diff --git a/bundles/org.eclipse.swt.tools/src/assembly/jar-with-dependencies.xml b/bundles/org.eclipse.swt.tools/src/assembly/jar-with-dependencies.xml new file mode 100644 index 00000000000..686cd9f6929 --- /dev/null +++ b/bundles/org.eclipse.swt.tools/src/assembly/jar-with-dependencies.xml @@ -0,0 +1,17 @@ + + jar-with-dependencies + + jar + + false + + + / + true + true + runtime + + +