diff --git a/AGENTS.md b/AGENTS.md index 3b428236f82..77f3df037d4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,7 +61,10 @@ See `bundles/org.eclipse.swt/Readme.md#building-native-binaries` for instruction **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, i.e. files like `libswt-*.so`, `libswt-*.jnilib` or `swt-*.dll`. +**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. @@ -80,7 +83,7 @@ Usually only the native binaries of the targeted platform can be built locally. - **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 -- Do not commit binaries! They will be build and comitted by the CI. +- **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/` @@ -165,9 +168,9 @@ mvn verify -pl :THE_BUNDLE_WITH_THE_ACTUAL_TEST -am -DskipNativeTests=false -Dsu ## 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) +- **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 diff --git a/bundles/org.eclipse.swt.tools/gtk/readme.md b/bundles/org.eclipse.swt.tools/gtk/README.md similarity index 86% rename from bundles/org.eclipse.swt.tools/gtk/readme.md rename to bundles/org.eclipse.swt.tools/gtk/README.md index 5f8cfc85196..f2d18931dfe 100644 --- a/bundles/org.eclipse.swt.tools/gtk/readme.md +++ b/bundles/org.eclipse.swt.tools/gtk/README.md @@ -7,4 +7,3 @@ but only during development work. For example install_sysdeps.sh (on linux), is aimed at installing packages that are required to be able to build swt native glue code. -For more details, see the description inside each script. diff --git a/bundles/org.eclipse.swt.tools/gtk/clone_build_gtk_debug.sh b/bundles/org.eclipse.swt.tools/gtk/clone_build_gtk_debug.sh deleted file mode 100755 index cbb30021577..00000000000 --- a/bundles/org.eclipse.swt.tools/gtk/clone_build_gtk_debug.sh +++ /dev/null @@ -1,213 +0,0 @@ -#!/bin/bash - -# ABOUT THIS SCRIPT -# This script automatically clones, builds (rebuilgs) gtk '.so' libs, so that you can -# run snippets with compiled gtk sources and allows you to debug gtk part of swt snippets. -# -# This script does the following: -# *) If ~/git/gtk does not exist, it asks you if it should create it for you. -# *) Clones git sources if not already cloned. -# *) Configures gtk for debug and compiles gtk -# *) Creates ~/gnomeso/curr if it doesn't exist. (This is where .so files will be) -# *) Copies scattered '.so' files into folder above for use by eclipse snippets. -# *) Prints next steps to console. (See bottom of script). -# -# Author Leonidas@RedHat.com 2017-03Mar-30Thu - -# CONFIG -GIT_DIR=$HOME/git -GTK_SRC_DIR=$GIT_DIR/gtk -COMPILED_SO_DIR=$HOME/gnomeso/curr -# CONFIG END - -HELP_MSG=" -# Optional command line arguments:\n - -y - silently build gtk without asking about branch\n - --nocleanup - do not cleanup git repository. Useful when modifying gtk itself, e.g add printf's.\n - --noconfig - do not re-configure the project. Used with the above to make compile faster or custom configs.\n -e.g\n - clone_build_gtk_debug.sh # Clones and builds gtk for you.\n - clone_build_gtk_debug.sh -y --nocleanup --noconfig # For quick rebuilds when modifying gtk sources.\n -------------------\n\n -" - -func_echo_info () { - GREEN='\033[0;32m' - NC='\033[0m' # No Color - echo -e "${GREEN}${@}${NC}" -} - -func_echo_input () { - PURPLE='\033[0;35m' - NC='\033[0m' # No Color - echo -e "${PURPLE}${@}${NC}" -} - -func_echo_error () { - RED='\033[0;31m' - NC='\033[0m' # No Color -echo -e "${RED}*** ${@}${NC}" -} - -# Print help info to educate user -func_echo_info $HELP_MSG - -# Parse arguments -SILENT=false -NOCLEANUP=false # for when you make changes to gtk source code, e.g print statements etc.. -NOCONFIG=false # faster build speeds. -for arg in "$@"; do # loop over all input parameters - if [ "$arg" == "-y" ]; then - func_echo_info "Assuming 'y' for trivial operations" - SILENT=true - fi - if [ "$arg" == "--nocleanup" ]; then - func_echo_info "Will not clean up gtk sources" - NOCLEANUP=true - fi - if [ "$arg" == "--noconfig" ]; then - func_echo_info "Will not reconfigure" - NOCONFIG=true - fi - if [ "$arg" == "--help" ]; then - exit 0 # If help was asked, only help will be given. - fi -done - -# Check if git source directory exists. Offer to create it if it doesn't. -if [ ! -d "$GIT_DIR" ]; then - func_echo_input "$GIT_DIR git directory for sources does not exist. Create it?" - read -p "[y/n]: " - if [ "$REPLY" == y ]; then - mkdir "$GIT_DIR" - else - func_echo_error "Cannot continue without git folder for sources" - exit 1 # fail - fi -fi - -# Check if gtk source repository is present. If not, offer to clone it. -if [ ! -d "$GTK_SRC_DIR/.git" ]; then - func_echo_input "$HOME/git/gtk does not exist. Should I clone gtk git repository?" - read -p "[y/n]: " - if [ "$REPLY" == y ]; then - cd "$GIT_DIR" - git clone https://github.com/GNOME/gtk.git - else - func_echo_error "Cannot continue without gtk src. If you have gtk source in another place, configure this script" - exit 1 #fail - fi -fi - -# Suggest to the user to checkout a suitable branch. -cd "$GTK_SRC_DIR" -func_echo_info "You are in: $(pwd)" -if [ "$SILENT" == "false" ]; then - func_echo_input "Currently gtk is on branch:" - git branch - func_echo_input "Its recommended to checkout a version of GTK that -is found on your system, because 'master' usually requires very new upstream libraries. -To find out which version of Gtk3 is on your system, you can check your package manager. Ex on fedora: -sudo dnf list installed | grep '^gtk3\.' -To checkout a particular gtk branch: - cd $GTK_SRC_DIR - git branch -r | grep gtk-3 - git checkout origin/gtk-3-22 -Shall I continue (y)? (You can checkout the required branch in another terminal tab. -(To avoid seeing this message, try running this script with '-y'" - - read -p "[y/n]: " - if [ ! "$REPLY" == y ]; then - func_echo_error "Please run this script again after checking out a version" - exit 1 # failure - fi -fi - -# Clean up old gtk bits. -cd "$GTK_SRC_DIR" -if [ "$NOCLEANUP" == false ]; then - func_echo_info "Cleanup old gtk build files. - This is needed if switching between gtk version to avoid compilation issues." - git clean -xdf # remove build files. - git reset --hard # undo changes to existing source files. -else - func_echo_info "No cleanup" -fi - -# Configure gtk sources for build. Assume debug support by default. (No use for production gtk?) -func_echo_info "Configuring gtk with debug support" -GEN_COMPILE_ERROR_MSG="Autogen failed. Check that you have required packages. Try ./install_sysdeps.sh or checkout earlier gtk branch" -if [ "$NOCONFIG" == false ]; then - ./autogen.sh --enable-debug=yes # for more options, see: https://developer.gnome.org/gtk3/stable/gtk-building.html - if [ "$?" ne 0 ]; then - func_echo_error $GEN_COMPILE_ERROR_MSG - exit 1 #failed - fi -fi - -# Build gtk with some extra debug flags (enable macro expansion, turn off optimization..) -# and enable multi-threading for faster build. -func_echo_info "GTK build starting..." -make CFLAGS="-g3 -ggdb3 -O0" -j8 -if [ "$?" -ne 0 ]; then - func_echo_error $GEN_COMPILE_ERROR_MSG - exit 1 $failed -fi - - -# We need to move the scattered compiled 'so' files into one place. -# Check if SO dir exists: -if [ ! -d "$COMPILED_SO_DIR" ]; then - func_echo_info "$COMPILED_SO_DIR does not exist. Creating it. It will contain compiled .so libs" - mkdir -p "$COMPILED_SO_DIR" - # add a readme. - echo "This folder contains '.so' dynamic library files build by swt/gtk build scripts, intended to be -used for running eclipse snippets with env vars: 'LD_LIBRARY_PATH=$COMPILED_SO_DIR'" > $COMPILED_SO_DIR/readme.md -fi - -# copy compiled .so files into $COMPILED_SO_DIR -func_echo_info "Copying compiled '.so' files into $COMPILED_SO_DIR" - -cp -v $(find . | grep "\.so") $COMPILED_SO_DIR - -# Print next step instructions. -func_echo_info " ------------------ -SUCCESS - -Gtk3 libs have been created. For a snippet/child eclipse to use the .so files, set environmental variable: -LD_LIBRARY_PATH=$COMPILED_SO_DIR - -To tell if the running snippet uses the loaded libs, you can inspect which libraries are mapped:\n -/proc/PID/maps | grep gnomeso -see: http://stackoverflow.com/questions/2184775/getting-a-list-of-used-libraries-by-a-running-process-unix -You can use 'jps' command to find PID of a SWT snippet. I combine things into a command like: -cat /proc/$\(jps | grep -i NAME_OF_YOUR_SNIPPT | cut -f1 -d' ')/maps | grep gnomeso -Output should list 'libgdk-3.so.0' and 'libgtk-3.so.0'. - -Also the gtk version in gtk inspector (ctrl+shift+i) will probably be a bit different (3.22.10 vs 3.22.11). -Note, GTKInspector has to be enabled first thou. -see: https://wiki.gnome.org/Projects/GTK+/Inspector - -To debug gtk from a java snippet: -0) You should setup Eclipse CDT with Standalone debugger. -1) In Eclipse, create a C makefile/library project in some folder. (not in $GTK_SRC_DIR) - In project settings, C/C++ General -> Paths and Symdols -> Source location, - link folder to $GTK_SRC_DIR. Allow C++ indexer to run. - (The reason for not creating project in $GTK_SRC_DIR is that this script cleans up - the folder and removes the .project with it.) -2) Set a breakpoint somewhere in gtk. I recommend: - gtkmain.c:gtk_main_do_event(..) - because that get's ran when you do the main event loop. -3) Set a java breakpoint at the first line of 'main' in your java app. -4) Start snippet in debug mode (with LD_LIBRARY_PATH set), wait for it to break at java break point. -5) Get pid of your new child snippet via 'jps' terminal command -6) In Eclipse's 'Quick access' (ctrl+3), execute 'Debug Attached Executable'. - (If this option is missing, you probably didn't install 'CDT Standalone Debugger') -7) Search for 'java', and connect to the java process with the given pid. -8) In the debug view, hit continue on java and the C stacktraces till your code reaches gtk_main_do_event(). - -In case things don't work, try 'gdb -p PID', it often tells you that you need to install some debug packages. - -Tip: -- You can move ~/gnomeso/curr to something like ~/gnomeso/GTK-3-xx to keep different versions of gtk." diff --git a/bundles/org.eclipse.swt.tools/gtk/install_sysdeps.sh b/bundles/org.eclipse.swt.tools/gtk/install_sysdeps.sh index 6702dec2eeb..f6d933f6735 100755 --- a/bundles/org.eclipse.swt.tools/gtk/install_sysdeps.sh +++ b/bundles/org.eclipse.swt.tools/gtk/install_sysdeps.sh @@ -8,56 +8,45 @@ # 2) Add a case to the case statement below. # 3) Add a function to handle your distribution. +GREEN='\033[0;32m' +RED='\033[0;31m' +NC='\033[0m' # No Color func_echo_plus () { # Echo function that prints output in green to distinguish it from sub-shell output. - GREEN='\033[0;32m' - NC='\033[0m' # No Color echo -e "${GREEN}${@}${NC}" } func_echo_error () { # As above, but in red. Also pre-appends '***' to output. - RED='\033[0;31m' - NC='\033[0m' # No Color -echo -e "${RED}*** ${@}${NC}" + echo -e "${RED}*** ${@}${NC}" } func_configure_fedora () { - FEDORA_VERSION=$(cat /etc/system-release | cut -f3 -d" ") - if [ "$FEDORA_VERSION" -lt "21" ]; then - INSTALL_CMD="yum" - else - INSTALL_CMD="dnf" - fi - func_echo_plus "Installing C Development Tools" - set -x - sudo $INSTALL_CMD -y groups install "C Development Tools and Libraries" - - func_echo_plus "Installing Java 11 development packages that include jni.h for JNI bindings." - sudo $INSTALL_CMD -y install java-11-openjdk-devel.x86_64 + sudo dnf -y groups install "C Development Tools and Libraries" - func_echo_plus "Installing Gtk3 development packages" - sudo $INSTALL_CMD -y install gtk3-devel + func_echo_plus "Installing Java development packages that include jni.h for JNI bindings." + sudo dnf -y install java-25-openjdk-devel - func_echo_plus "Installing X11 Development libraries. Someday when wayland takes over these will not be needed..." - # Deals with error: "#include , #include " build errors) - sudo $INSTALL_CMD -y install libXt-devel + func_echo_plus "Installing Gtk development packages" + sudo dnf -y install gtk3-devel gtk4-devel func_echo_plus "Install Mesa (OpenGL headers)" # Deals with error: "/usr/bin/ld: cannot find -lGLU collect2: error: ld returned 1 exit status" - sudo $INSTALL_CMD -y install mesa-libGLU-devel + sudo dnf -y install mesa-libGLU-devel func_echo_plus "Done" } -LINUX_DISTRO=$(cat /etc/system-release | cut -f1 -d" ") -if [ "$LINUX_DISTRO" = "" ]; then - func_echo_error "Error, could not identify your distribution" - exit +if [ -f /etc/os-release ]; then + . /etc/os-release + LINUX_DISTRO="$ID" +else + echo "Error: cannot identify distribution" + exit 1 fi DISTRO_NOT_KNOWN_MSG=" @@ -66,14 +55,13 @@ Consider updating this script for your distribution. In general, You should install the following packages: - C Development tools (usually comes in a 'group install') - java-*-openjdk-devel (depending on current version of java) - - gtk3-devel - - libXt-devel + - gtk3-devel and gtk4-devel - mesa-libGLU-devel " case "$LINUX_DISTRO" in -"Fedora") +"fedora") func_echo_plus "Fedora found. Installing packages..." func_configure_fedora ;; @@ -85,10 +73,3 @@ case "$LINUX_DISTRO" in ;; esac - -# check if .classpath exists in swt project. -if [ -a "../org.eclipse.swt/.classpath" ]; then - func_echo_plus ".classpath found, you are good to go"; -else - func_echo_error "Warning: ../org.eclipse.swt/.classpath not found. Normally you rename ../org.eclipse.swt/.classpath_gtk to ../*/.classpath manually" -fi diff --git a/bundles/org.eclipse.swt.tools/gtk/rebuild_swt_natives_wrapper.sh b/bundles/org.eclipse.swt.tools/gtk/rebuild_swt_natives_wrapper.sh deleted file mode 100755 index 9a903bbf357..00000000000 --- a/bundles/org.eclipse.swt.tools/gtk/rebuild_swt_natives_wrapper.sh +++ /dev/null @@ -1,42 +0,0 @@ -#!/bin/bash - -# This is a wrapper script that you can put into your path and give it a short name: e.g: ~/bin/swtb -# It will make a local copy of the rebuild_swt_natives script (if the one from the repo is newer) -# and execute it. - -# The idea is that if you checkout an old SWT codebase that didn't have rebuild_swt_natives, -# you could still rebuild swt bindings by running the local copy via this script. - -# Instructions: -# Move this script: -# cp ./rebuild_swt_natives_wrapper.sh ~/bin/swtb -# Run it at least once: -# ~/bin/swtb -# Re-run it when needed via 'swtb' - -REBUILD_SCRIPT="$HOME/git/eclipse.platform.swt/bundles/org.eclipse.swt.tools/gtk/rebuild_swt_natives.sh" - -if [ -e "${REBUILD_SCRIPT}" ]; then - # make a local copy so it's available if you checkout an old SWT code base. - TEMP_COPY="./rebuild_swt_natives.sh_temp" - if [ ! -e "$TEMP_COPY" ]; then - echo "Making local copy of rebuild_swt_natives, so that it can be used by older swt checkouts" - cp "$REBUILD_SCRIPT" "$TEMP_COPY" - fi - - # Update local copy if it's out of date. - if [ "$REBUILD_SCRIPT" -nt "$TEMP_COPY" ]; then - echo "Found new version of script. Updating local copy" - cp "$REBUILD_SCRIPT" "$TEMP_COPY" - fi - $REBUILD_SCRIPT -else - if [ -e "$TEMP_COPY" ]; then - echo "Original not available. Running local copy" - $TEMP_COPY - else - echo "ERROR: could not find rebuld script for initial run: $REBUILD_SCRIPT and no local copy available either" - exit 1; #fail - fi -fi - diff --git a/docs/gtk-dev-guide.md b/docs/gtk-dev-guide.md index d5f751d8b15..e3a7baad2a4 100644 --- a/docs/gtk-dev-guide.md +++ b/docs/gtk-dev-guide.md @@ -107,21 +107,9 @@ Check out the repository holding the SWT sources and binaries. I usually do this git@github.com:eclipse-platform/eclipse.platform.swt.git -Subsequently import all projects from the SWT source repository. -From the binary repository, import only: org.eclipse.swt.gtk.linux.x86_64 +Note: Native binaries are stored in the same repository using Git LFS, under `binaries/`. Make sure Git LFS is installed (`git lfs install`) before cloning, otherwise LFS pointer files won't be resolved. -**Modify the .classpath files** - -At first you might get many many errors. You first have to tell the project, that you are on Linux/GTK for things to compile/run properly. Specifically for GTK, you must do the following: -* Open the 'Navigator' view (not package explorer) -* Under 'org.eclipse.swt' look for the .classpath files -* Rename .classpath_gtk to .classpath -* Clean up projects (in Eclipse, Project -> Clean) -* Now run a test snippet or ControlExample.java, it should work without the compilation errors - -If '.classpath_gtk' is missing from navigator, you probably have a broken workspace. Make a new one. This sometimes happens when upgrading from older versions of eclipse. - -Edit the org.eclipse.swt.examples project and add the org.eclipse.swt project as dependent. Now you should be able to run the 'ControlExample.java' +Subsequently import all projects from the SWT repository, including: org.eclipse.swt.gtk.linux.x86_64 from the `binaries/` folder. **Configure git for review** @@ -133,7 +121,7 @@ For general contribution guidelines, see: https://github.com/eclipse-platform/.g **About** -You checked out two SWT repos: SWT and SWT binaries. The SWT binaries contain ready-build SO files to be used with built with the SWT source code. Sometimes you need to add native GTK functions to OS.java, allowing you to use those new functions in the SWT (Java) source code. After any changes to OS.java, you need to rebuild the GTK .SO bindings. Otherwise SWT will complain about "unsatisfied link errors" between the SWT source code and the binaries. +The SWT repository contains both source code and precompiled native binaries (stored via Git LFS in the `binaries/` folder). Sometimes you need to add native GTK functions to OS.java, allowing you to use those new functions in the SWT (Java) source code. After any changes to OS.java, you need to rebuild the GTK .SO bindings. Otherwise SWT will complain about "unsatisfied link errors" between the SWT source code and the binaries. **Prerequisites** @@ -161,11 +149,11 @@ Navigate to folder containing script 1 and execute the script as following: ./build.sh -gtk3 install (or -gtk4 if building for gtk4) -This will clean up old object files, build gtk3 and gtk4 and copy them to the binary git repository. Build.sh has additional parameters, to find out more: +This will clean up old object files, build gtk3 and gtk4 and copy them to the `binaries/` folder in the repository. Build.sh has additional parameters, to find out more: ./build.sh --help -Note, the script doesn't clean the binary repository. Consider using the following to fully automate cleanup and rebuild: +Note, the script doesn't clean the binaries folder. Consider using the following to fully automate cleanup and rebuild: #!/bin/bash echo "Clean up of bindings" @@ -221,7 +209,7 @@ After building the native libraries, you can verify they work correctly by: If you encounter "UnsatisfiedLinkError" exceptions, it means the native libraries weren't built correctly or aren't being found. Double-check that: - The build completed successfully without errors -- The .so files were copied to the binary repository +- The .so files were copied to the `binaries/` folder in the repository - Your Eclipse workspace is using the correct .so files **References**