Revision as of 14:21, 6 August 2015

About

The gtk specific code of Equinox handles the splash screen and workspace file chooser.

Location

 ./features/org.eclipse.equinox.executable.feature/library/gtk

Importing related projects

At first, a lot of gtk structures/functions/variable will not be found and will be underlined red.

Import related projects: gtk+(gtk/gdk) / glib / gtk-pixbuf / pixman / cario projects. (See git links)

Now open the equinox project properties, under C/C++ include paths, add the projects from your workspace.

Then rightclick on the projects, under 'Index' click on 'rebuild'. Now most symbols should be recognized. It should look something like this:

Imported symbols

There might still be a few symbols that can't be identified. Often it is the TRUE/FALSE macro or some distant structs like Gerror or macros that are injected at compile time. Those are usually caused by the indexer not being able to find them because they're only included at compile time. I usually ignore them, but if they really bother you can add the relevant include statements (e.g #include <glib/gerror.h>)

Building Eclipse executable

inside the gtk folder, run:

 sh build.sh 

To start a build. It will produce an executable 'eclipse'.

When you first launch make, it may complain about missing java:

 ../eclipseJNI.h:15:17: fatal error: jni.h: No such file or directory

In this case, you need to specify your java path. Usually this can be done via:

 export JAVA_HOME=/usr/lib/jvm/java/
 sh build.sh   #then run your bulid.

Once build, you should see the following file in the gtk directory:

 eclipse
 eclipse_xyzz.so    #where xyzz is something like 1613

Running compiled units

To test what you've build, you need to find a regular eclipse and replace it's files with those that you compiled.

Replace files:

1) Download some build of eclipse: Eclipse Download site

2) Navigate to /eclipse folder that should contain your 'eclipse' executable. Rename the original executable to 'eclipseOLD' and copy your newly compiled one into it.

3) For the 'so' file, in the downloaded eclipse, navigate to the plugin folder, into the equinox launcher gtk folder. It should be something like:

  ~/Downloads/eclipse-SDK-N20150719-2000-linux-gtk-x86_64/eclipse/plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.1.300.N20150719-2000

You can also find it via:

  find . | grep "eclipse_.*so"

Inside it, you should find an so like: eclipse_1632.so . Move the file, or rename it such that it doesn't contain an 'so' (e.g eclipse_old_1632). (eclipse will load the first found 'so' file, and it might confuse them if both are present). Now move your newly compiled eclipse_1632.so into that folder.

I automate these steps via a script:

 #!/bin/bash
 cp ./eclipse "/home/lufimtse/Downloads/eclipse-SDK-N20150719-2000-linux-gtk-x86_64/eclipse/eclipse"
 cp ./eclipse_1613.so "/home/lufimtse/Downloads/eclipse-SDK-N20150719-2000-linux-gtk-x86_64/eclipse/plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.1.300.N20150719-2000/eclipse_1613.so"

Verify:

To make sure that eclipse launches with the files that you've actually replaced:

1) I personally put some print statement into the code, so when I run it, it is printed.

  eclipseGtkInit.c: 
     int loadGtk() {
     puts("Hello World\n");

2) Alternatively, launch eclipse and note the pid:

  ./eclipse & echo $!

Or use jps after it is launched.

3) Navigate to /proc/PID/

4) execute

  cat maps | grep eclipse_

This should list the eclipse_xyzz.so file that you copied to the plugin folder.

Debugging compiled code

Compile for debug

Inside the gtk folder, edit make_linux.mak. Change the CFLAGS to compile to a debug build.

From:

 CFLAGS = ${M_ARCH} -g -s -Wall\

To:

 CFLAGS = ${M_ARCH} -ggdb3 -O0 -Wall\

Note:

• O0 turns off optimizations
• for ggdb3 info see this post.) As a note, having both '-g' '-ggdb3' will make it fall back to just '-g'. In which case you won't be able to debug compile macros and debugging in general will behave in a weird way like making unpredictable jumps.

Rest is business as usual.

Debug via gdb

Before debugging in Eclipse, I often get regular gdb debugging going. This often helps to identify missing debug symbols.

Start eclipse from gdb:

  gdb ./eclipse
  b loadGtk
  start
  c

Now you should be at the 'loadGtk' function inside Gtk.

Debug via Eclipse

Under debug configurations:

• create a new "C/C++ Application"
• Select your launcher project from your workspace
• browse to where you copied the compiled 'eclipse' executable
• disable auto-build, (you'll be compiling manually)
• click on 'debug'
• The debugger should stop at the main method. You can now set breakpoints (e.g ../gtk/eclipseGtkInit.c:loadGtk()) and it should break at those methods.

Code notes

Dynamic library loading

Note, a lot of libraries (gtk/pixbuff/X11) are loaded dynamically:

  gdkLib = dlopen(GDK3_LIB, DLFLAGS);

Their symbols are then loaded via FN_TABLES. See eclipseGtkInit.c and eclipseGtk.h.

In the interest of portability, there should not be hard dependencies to gui libraries in the launcher.

SWT_GTK3 variable

The SWT_GTK3 environmental variable determines if the Equinox launcher is launched in Gtk3 or Gtk2.

However, if you set this value in the Eclipse run time configuration under Environmental variables, this will have no effect.

Instead, edit the eclipse.ini which is located in :

• for Downloaded Eclipse, it is next to the executable eclipse file
• for Eclipse installed from repository, it is in /etc/eclipse.ini

and set the property accordingly:

 --launcher.GTK_version
 3