Skip to content

Commit b7bd2fc

Browse files
Copilotlaeubi
Copilot
authored and
laeubi
committed
Setup Repository for GitHub Copilot
Currently the Repository is not setup for copilot and could make it quite hard for the tool to give useful results because of the special setup. This now is a first attempt to make it more valuable for that case let it be helping with analysis of core dumps or migrating GTK4 by improve the setup for at least the GTK case: - creating general copilot instructions file - creating a specialized GTK instructions file - adding workflow setup that prepares the environment - add a document to track current GTK4 deprecation warnings
1 parent 4722846 commit b7bd2fc

File tree

5 files changed

+954
-0
lines changed

5 files changed

+954
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# GitHub Copilot Instructions for Eclipse Platform SWT
2+
3+
## Project Overview
4+
5+
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.
6+
7+
## Architecture
8+
9+
SWT consists of two main parts:
10+
1. **Java code** - Platform-independent widget implementations and APIs
11+
2. **Native code (C)** - Platform-specific implementations using native windowing systems
12+
13+
### Platform Support
14+
- **Linux**: GTK3 (stable) and GTK4 (experimental)
15+
- **Windows**: Win32 API
16+
- **macOS**: Cocoa
17+
18+
### Key Components
19+
- `bundles/org.eclipse.swt` - Main SWT bundle with Java and native code
20+
- `bundles/org.eclipse.swt.svg` - SVG support
21+
- `bundles/org.eclipse.swt.tools` - Build and development tools
22+
- `binaries/` - Platform-specific binary fragments
23+
- `examples/` - Example code and snippets
24+
- `tests/` - JUnit tests
25+
26+
## Build System
27+
28+
### Technology Stack
29+
- **Build Tool**: Maven with Tycho plugin
30+
- **Java Version**: Java 17 (compiler target), Java 21 (build/runtime in CI)
31+
- **Supported Architectures**: x86_64, aarch64, loongarch64, ppc64le, riscv64
32+
33+
### Build Commands
34+
```bash
35+
# Build the entire project
36+
mvn clean verify
37+
38+
# Build specific platform binary
39+
mvn clean verify -Dnative=gtk.linux.x86_64
40+
41+
# Skip tests
42+
mvn clean verify -DskipTests
43+
```
44+
45+
### Building Natives
46+
To rebuild native libraries:
47+
1. Ensure the appropriate binary project is imported in your workspace (e.g., `binaries/org.eclipse.swt.gtk.linux.x86_64`)
48+
2. Native build scripts are platform-specific and located in the binary fragments
49+
3. For GTK on Linux: See `docs/gtk-dev-guide.md` for detailed instructions
50+
51+
## Coding Standards
52+
53+
### Java Code
54+
- **Indentation**: Tabs (as per Eclipse project conventions)
55+
- **Line Length**: Keep lines reasonably short, no strict limit
56+
- **Naming**: Follow standard Java conventions (camelCase for methods/variables, PascalCase for classes)
57+
- **Comments**: Use JavaDoc for public APIs; inline comments where needed for clarity
58+
- **Assertions**: Use assertions for runtime checks (enabled in tests, disabled in production)
59+
60+
### Native Code (C)
61+
- **Platform-specific**: Code goes in platform folders (gtk/, win32/, cocoa/)
62+
- **JNI**: Communication between Java and native code uses JNI
63+
- **OS.java**: Central file for native method declarations
64+
- Do not commit binaries! They will be build and comitted by the CI.
65+
66+
### Code Organization
67+
- Platform-independent code: `bundles/org.eclipse.swt/Eclipse SWT/common/`
68+
- Platform-specific code: `bundles/org.eclipse.swt/Eclipse SWT/{gtk,win32,cocoa}/`
69+
- Emulated widgets: `bundles/org.eclipse.swt/Eclipse SWT/emulated/`
70+
71+
## Testing
72+
73+
### Running Tests
74+
```bash
75+
# Run all tests
76+
mvn clean verify
77+
78+
# Run specific test class
79+
mvn test -Dtest=ClassName
80+
```
81+
82+
### Test Location
83+
- Main tests: `tests/org.eclipse.swt.tests/`
84+
- Tests automatically run with assertions enabled
85+
86+
### Writing Tests
87+
- Follow existing test patterns in the repository
88+
- Platform-specific tests should be in appropriate fragments
89+
- Use JUnit for all tests
90+
91+
## Development Workflow
92+
93+
### Making Changes
94+
95+
1. **Java-only changes**: Can be tested without rebuilding natives
96+
2. **Native changes**: Require rebuilding the platform-specific binary fragment
97+
3. **Cross-platform changes**: Test on all affected platforms
98+
99+
### Pull Request Guidelines
100+
- Sign the Eclipse Foundation Contributor License Agreement (CLA)
101+
- Ensure all tests pass
102+
- Follow the contribution guidelines in CONTRIBUTING.md
103+
- Reference related GitHub issues
104+
105+
### CI/CD
106+
- GitHub Actions runs builds on Linux, Windows, and macOS
107+
- Matrix builds test with Java 21 on all platforms
108+
- All tests must pass before merge
109+
110+
## Important Files and Patterns
111+
112+
### Key Files
113+
- `OS.java` - Central native method declarations for platform integration
114+
- `Display.java` - Main event loop and display management
115+
- `Widget.java` - Base class for all widgets
116+
- `Control.java` - Base class for all controls
117+
118+
### Common Patterns
119+
- **Resource Management**: Always dispose of SWT resources (Display, Shell, Image, etc.)
120+
- **Threading**: UI operations must run on the UI thread (use `Display.asyncExec()` or `Display.syncExec()`)
121+
- **Event Handling**: Use listeners (typed or untyped) for event handling
122+
- **Layout Management**: Use layout managers (GridLayout, FillLayout, etc.) instead of absolute positioning
123+
124+
## Platform-Specific Considerations
125+
126+
### GTK (Linux)
127+
- Communication from Java to C happens through `OS.java`
128+
- GTK3 is stable; GTK4 is experimental
129+
- Can be toggled using `SWT_GTK4` environment variable
130+
- See `docs/gtk-dev-guide.md` for comprehensive GTK development guide
131+
132+
### Windows
133+
- Uses Win32 API
134+
- WebView2 support available (see `Readme.WebView2.md`)
135+
- Platform-specific code in `win32/` directories
136+
137+
### macOS
138+
- Uses Cocoa framework
139+
- Supports both x86_64 and aarch64 (Apple Silicon)
140+
- Platform-specific code in `cocoa/` directories
141+
142+
## Resources
143+
144+
- **Main README**: [`README.md`](../README.md)
145+
- **Contributing Guide**: [`CONTRIBUTING.md`](../CONTRIBUTING.md)
146+
- **GTK Development Guide**: [`docs/gtk-dev-guide.md`](../docs/gtk-dev-guide.md)
147+
- **GitHub Discussions**: Use for questions and general discussions
148+
- **GitHub Issues**: Use for bug reports and feature requests
149+
150+
## Tips for Copilot
151+
152+
- When generating SWT code, always include proper resource disposal
153+
- Remember that SWT is not thread-safe - UI operations need Display.syncExec/asyncExec
154+
- Platform-specific code should go in the appropriate platform directory
155+
- When adding native methods, declare them in `OS.java` first
156+
- Follow existing code patterns in the repository for consistency
157+
- Use snippets in `examples/org.eclipse.swt.snippets/` as reference examples
158+
- Consider cross-platform compatibility when making changes

‎.github/instructions/GTK.instructions.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
applyTo: "bundles/org.eclipse.swt/Eclipse SWT PI/gtk/library/*.c,bundles/org.eclipse.swt/Eclipse SWT PI/gtk/library/*.h"
3+
---
4+
5+
- Due to the copilot environment setup in copilot-setup-steps.yml we always use x86_64 architecture
6+
- Always carefully investigate exsiting GTK functions the gtk-dev files are installed in the system
7+
- The GTK docs can be found here https://www.gtk.org/docs/
8+
- Be carefull between the difference of GTK3 and GTK4 we need to check for specific versions in some places already
9+
- The GTK3 > GTK4 migration guide can be found here https://docs.gtk.org/gtk4/migrating-3to4.html
10+
- You will find a shell script ./build_gtk.sh that must be used to compile the code for testing changes

‎.github/workflows/copilot-setup-steps.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: "Copilot Setup Steps"
2+
3+
# Automatically run the setup steps when they are changed to allow for easy validation, and
4+
# allow manual testing through the repository's "Actions" tab
5+
on:
6+
workflow_dispatch:
7+
pull_request:
8+
paths:
9+
- .github/workflows/copilot-setup-steps.yml
10+
11+
jobs:
12+
# The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
13+
copilot-setup-steps:
14+
runs-on: ubuntu-latest
15+
permissions:
16+
contents: read
17+
steps:
18+
- name: Checkout code
19+
uses: actions/checkout@v4
20+
with:
21+
lfs: false
22+
23+
- name: Set up JDK
24+
uses: actions/setup-java@v4
25+
with:
26+
java-version: '21'
27+
distribution: 'temurin'
28+
cache: 'maven'
29+
30+
- name: Set up Maven
31+
uses: stCarolas/setup-maven@v5
32+
with:
33+
maven-version: '3.9.11'
34+
- name: Prepare Linux Build
35+
run: |
36+
sudo apt-get update -qq
37+
sudo apt-get install -qq -y libgtk-3-dev libgtk-4-dev freeglut3-dev webkit2gtk-driver
38+
mkdir -p /home/runner/build/gtk && mkdir -p /home/runner/build/tmp
39+
40+
echo "cd $GITHUB_WORKSPACE/bundles/org.eclipse.swt && java -Dws=gtk -Darch=x86_64 build-scripts/CollectSources.java -nativeSources '/home/runner/build/gtk'" >> $GITHUB_WORKSPACE/build_gtk.sh
41+
echo "cd /home/runner/build/gtk && SWT_JAVA_HOME=${JAVA_HOME} MODEL=x86_64 OUTPUT_DIR=/home/runner/build/tmp ./build.sh install clean" >> $GITHUB_WORKSPACE/build_gtk.sh
42+
echo "cd $GITHUB_WORKSPACE" >> $GITHUB_WORKSPACE/build_gtk.sh
43+
chmod +x $GITHUB_WORKSPACE/build_gtk.sh
44+

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ pom.tycho
99

1010
/binaries/org.eclipse.swt.*/src/
1111
tmpdir/
12+
‎build_gtk.sh

0 commit comments

Comments
 (0)