Skip to content

AGENTS.md

Latest commit

 

History

History
213 lines (161 loc) · 8.03 KB

AGENTS.md

File metadata and controls

213 lines (161 loc) · 8.03 KB

AGENTS.md - Eclipse SWT Guide for AI Tools

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

Native binaries

This repository uses Git Large File Storage (LFS) to store precompiled native binaries. The .gitattributes file specifies which files are stored using LFS.

If Git LFS is not installed and configured the LFS pointer files are not resolved on checkout and the binaries have to be compiled locally. For that, see the Build Commands section below.

NOTE: For GitHub Copilot agent sessions Git LFS checkout is disabled.

Cross-compiling binaries for operating systems other than the one currently in use is not possible, just as testing code for other platforms is not possible. If you make changes to code (Java or native) for other platforms, the binaries cannot be rebuilt and the changes cannot be tested locally. Instead, rely on the GitHub PR workflows created for each platform to test the changes.

Build System

Technology Stack

  • Build Tool: Maven with Tycho plugin
  • Java Version: Java 21
  • Supported Architectures: x86_64, aarch64, loongarch64, ppc64le, riscv64

Build Commands

# Build the entire project
mvn clean verify

# Skip tests
mvn clean verify -DskipTests

Building native binaries

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.

CRITICAL: Never commit any built native binary files to git. These are built and committed by the CI. This includes:

  • Linux: libswt-*.so
  • MacOS: libswt-*.jnilib, libswt-*.dylib
  • Windows: swt-*.dll

See docs/*.md and bundles/org.eclipse.swt/Readme*.md files for detailed instructions.

Usually only the native binaries of the targeted platform can be built locally.

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
  • Never commit built binaries (*.so, *.dll, *.jnilib, *.dylib) — They will be built and committed by the CI.

Code Organization

  • Platform-independent code: bundles/org.eclipse.swt/Eclipse SWT/common/
  • Platform-specific code: bundles/org.eclipse.swt/Eclipse SWT/{gtk,win32,cocoa}/
  • JNI layer: bundles/org.eclipse.swt/Eclipse SWT PI/{gtk,win32,cocoa}/
  • Emulated widgets: bundles/org.eclipse.swt/Eclipse SWT/emulated/

OSGi Bundle Dependencies

SWT is an OSGi bundle. Check bundles/org.eclipse.swt/META-INF/MANIFEST.MF before using external classes. If needed, add packages to Import-Package or Require-Bundle.

Testing

Running Tests

# Run all tests
mvn clean verify

# Run specific test class (append `#testMethodName` for a single test)
mvn verify -pl :THE_BUNDLE_WITH_THE_ACTUAL_TEST -am -DskipNativeTests=false -Dsurefire.failIfNoSpecifiedTests=false -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

Critical Development Rules

Resource Disposal

YOU MUST DISPOSE: Image, GC, Cursor, Region, Path, Pattern Auto-disposed (no manual disposal needed): Color, Font (as of recent SWT versions) DO NOT DISPOSE: System colors/fonts, ImageRegistry images, Display/Shell (framework-managed)

Image image = new Image(display, 100, 100);
try {
    // Use image
} finally {
    image.dispose();
}

Threading

All SWT code must run on the Display thread!

display.asyncExec(() -> button.setText("Updated"));

Adding GTK Functions

  1. Add native method declaration to OS.java with JavaDoc annotations (@param cast=, @method flags=dynamic)
  2. Clean and rebuild org.eclipse.swt project (regenerates os.c)
  3. Rebuild natives: cd bundles/org.eclipse.swt/Eclipse SWT PI/gtk/library && export GTK_VERSION=3.0 && ./build.sh install

Tips for AI Tools

  • Always include proper resource disposal in generated code
  • Ensure UI operations use Display.syncExec/asyncExec
  • Platform-specific code goes in {gtk,win32,cocoa}/ directories
  • When adding native methods, declare in OS.java first
  • Never edit auto-generated files (os.c, os_stats.*)
  • Use snippets in examples/org.eclipse.swt.snippets/ as reference
  • Test cross-platform compatibility
  • Check MANIFEST.MF for OSGi dependencies