From Yocto Project
Jump to: navigation, search


Cookbook guide to Making an Eclipse Debug Capable Image

Suppose you are building images and would like to be able to use Eclipse and the Yocto Eclipse plugin to develop/debug a C/C++ application on either a remote hardware target or on qemu. This cookbook will explain the small number of steps needed to accomplish this.
So that the commands are specific and can be cut and pasted to try, we will assume the following:

  • Target Image-> core-image-sato-sdk
    • see section#Why SDK Image for why you have to build the sdk image and how to work around it if you really don't want to.
  • Target Machine -> qemux86

Making a Suitable Qemux86 Image

  • We need to build a core-image-sato-sdk that has the pieces needed by Eclipse, so we add/change the following in our conf/local.conf:
    • We add the following to EXTRA_IMAGE_FEATURES in conf/local.conf
      • EXTRA_IMAGE_FEATURES += " eclipse-debug "
        • This adds gdbserver,tcf-agent (for Target Communication Framework), and openssh-sftp-server)
      • EXTRA_IMAGE_FEATURES += " tools-sdk "
        • This adds the build requirements on the target rootfs. This is needed since the Yocto Eclipse plugin is assuming that the qemu rootfs and the sysroot are synonymous.
      • EXTRA_IMAGE_FEATURES += " ssh-server-openssh "
        • This defaults to the openssl ssh server rather than dropbear. You can use either so this line can be omitted since the sftp server works with either.
    • Execute: $bitbake core-image-sato
      • This makes a rootfs in tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2
  • We need to build the toolchain eclipse will use
    • Execute $bitbake core-image-sato -c populate_sdk
      • This makes sdk stuff such as the toolchains eclipse will use to build,
  • We need to build a version of qemu that can run natively on our workstation as well as a userspace nfs daemon.
    • Execute $bitbake meta-ide-support
  • We need an extracted rootfs that can be used by the userspace nfs daemon to boot qemu.
    • Execute $mkdir MY_QEMU_ROOTFS
      • Execute $runqemu-extract-sdk tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 MY_QEMU_ROOTFS
        • This will result in a fully extracted rootfs in MY_QEMU_ROOTFS and a set of permissions maintained by pseudo (a yocto tool similar to but more functional than fakeroot) for the rootfs in MY_QEMU_ROOTFS.pseudo_state

Running Eclipse Against the Built Qemux86 Image

This Cookbook assumes you have already installed the Eclipse Poky plugin following the directions in Assuming that is true, you can

Set up the Configuration For the Built Image

  • Goto Windows->Preferences->Yocto Project SDK
    • Select Build System Derived Toolchain
    • enter Toolchain Root Location: <build dir>
      • this is where you have been running bitbake core-image-sato, bitbake etc.
    • enter Sysroot Location: <path>/MY_QEMU_ROOTFS
      • this is where you extracted the core-image-sato-qemux86.tar.bz2 to by running runqemu-extract-sdk
    • enter Qemu/Kernel: <path>/tmp/deploy/images/qemux86/bzImage-qemux86.bin
      • this is the kernel we built
    • You should now see i586-poky-linux in the Target Architecture dropdown list.
    • hit apply and ok

Alternatively, Downloading what we need for Qemux86

Sometimes, you may not want to build everything yourself but just want to download what you need. These instructions will target the Yocto 2.1 release, but you should be able to translate it into other releases pretty easily.

$chmod a+x 

This will put the toolchain in /opt/poky/2.1 by default.

  • source the toolchain environment file
 $source environment-setup-i586-poky-linux 
  • extract the image you downloaded so that Qemu can use it
 $runqemu-extract-sdk core-image-sato-sdk-qemux86.tar.bz2  MY_QEMU_ROOTFS 

Running Eclipse Against the Downloaded Image

This Cookbook assumes you have already installed the Eclipse Poky plugin following the directions in Assuming that is true, you can

Set up the Configuration For the Downloaded Image

  • Goto Windows->Preferences->Yocto Project SDK
    • Select Standalone pre built toolchain
    • enter Toolchain Root Location: /opt/poky/2.1
    • enter Sysroot Location: <path>/MY_QEMU_ROOTFS
      • this is where you extracted the core-image-sato-qemux86.tar.bz2 to by running runqemu-extract-sdk
    • enter Qemu/Kernel: bzImage-qemux86.bin
      • this is the kernel you downloaded
    • You should now see i586-poky-linux in the Target Architecture dropdown list.
    • hit apply and ok

Run Qemu

  • goto Run->External Tools-> External Tools Configurations... and select qemu_i586-poky-linux (in our example; in general it will be architecture-distro-os)
    • click Run - this will bring up a Qemu instance.

Put the binary on the Qemu instance and debug it

  • goto Run->Debug Configurations... and select your project (looks like hello_gdb_i586-poky-linux in our case if you named the project hello)
  • make a new connection - I prefer SSH so I'll show that here. TCF should also work.
    • Click New... on Connection line
    • put (probably, look at the end of the qemu xterm that launched and find ip=192.168.7.XX::192.168.7.XX-1 ) in the Host name
    • name it
    • click finish
Eclipse Oxygen and TCF
  • In Mars, TCF would appear as a connection type alongside ssh.
  • In Oxygen, this is no longer true. If you want to use tcf as the connection type you need to do the following:
    • At the bottom of the DEbug Configuration page, by default, you will be in "Using GDB (DSF) Automatic Remote Debugging Launcher" - Select other...
    • Click on "Select other..." and you can choose GDB (DSF) Automatic REmove Debugging via TCF/TE Launcher. This is the oxygen equivalent of a TCF connection.
    • If they cannot be selected, you may need to select the "Use configuration specific settings" checkbox at the top of the dialog box.
      • at this point, your connection will be of type tcf
    • I found the neon implementation of tcf to be buggy...
Back to Using the Connection whether it be ssh or tcf
  • Browse to where the prog will go. I tend to use /home/root.
    • Remote Absolute File Path for C/C++ Application -> click Browse...
    • Goto Root->/->home->root remember the user is root and the password is empty by default.
    • double click root
    • click ok
    • If the browse to Remote Absolute File Path for C/C++ Application hangs or errors out Check
      • qemu is running
      • you can ssh root@<address> from a terminal window
      • make sure that the proxies eclipse knows about in Window->Preferences->Network Connections is not "eating" the ssh connection traffic. On Oxygen, for instance, I need to switch the network connection to manual and add as a Proxy bypass host.
  • click Apply
  • click Debug and open the Debug Perspective.

Other Useful Info

Why SDK Image

The current poky-eclipse plugin mashes together 2 concepts that should have been disjoint: namely, the target sysroot and the rootfs image qemu will boot. Under Window->Preferences->Yocto Project SDK , you choose a sysroot location. Up above I told you to point this to the MY_QEMU_ROOTFS you extracted with runqemu-extract-sdk. This will work, but only if you have built the sdk image. If you built the core-image-sato instead, then the MY_QEMU_ROOTFS will be missing a lot of important development files like stdio.h...

How to Work around this

Let's say you build core-image-sato (this is a standin for your particular image that can't have the sdk parts tossed in for some reason). You can still use eclipse and qemu. You need to do the same things as above with the following changes:

  • Sysroot in Window->Preferences->Yocto Project SDK points to <builddir>/tmp/sysroots/qemux86-64. This will give the build system access to the development files it needs.
  • In the dialog for Run->External Tools-> External Tools Configurations... you will need to read the long Argument string in the big box. It will have something like -e "source env-setup-<sdkarch>; runqemu <kernel path> <rootfs path> Because the current plugin munges the sysroot and qemu image concepts, the <rootfs path> will incorrectly be pointing to your sysroot. Just delete the <rootfs path> and put in the ABSOLUTE path to the MY_QEMU_ROOTFS you extracted with the runqemu-extract-sdk tool. This way, you can build & debug the image even if it's not an sdk image.

Adding static tap devices

It is often easier to preconfigure several tap devices so that qemu can run and use them without needing to be root or use sudo. To do this, run runqemu-gen-tapdevs `id -u <username>` `id -g <username>` 4 `find ./tmp/sysroots -iname tunctl` as root. This will make the inet devices tap0,tap1,tap2,tap3. You can see them with ifconfig -a | grep tap . Typically, tap0 is and so when the first qemu is run it's address will be and will be that qemu instance's gateway. The runqemu-gen-tapdevs is located in bitbake/scripts.


Switching autotools C/C++ project from one toolchain/sysroot to another and build failing

Sometimes you will have an existing project and want to switch to a different toolchain or sysroot or machine (x86->x86-64 for instance). If you find that you are getting errors like install-sh not found it may mean that your autotools files have gotten out of sync. Here's how you can force them back. All of these are found by Right clicking on the project and going to Invoke Autotools->:

 Invoke Libtoolize  option = "--force"
 Invoke Aclocal
 Invoke Autoheader
 Invoke Automake  option = "--force-missing --add-missing"
 Invoke Autoconf

Then Right click on the project and select Reconfigure Project . You should now be able to build the project again.

Dealing with java.lang.NullPointerException

Eclipse upstream has some issues with *some* of the GTK3 libraries shipped with some of the distributions( If you are seeing a NullPointer Exception try adding the following to your eclipse.ini file:


Here's an in place snippet of a happy ini file:


Alternatively, you can set

$export SWT_GTK3=0

But this might affect other programs as well.

XWayland workaround with gtk3 (Fedora-25)

If you see bizarre screen layout of controls in Eclipse Neon, it is probably because the Neon (4.6.x) release of Eclipse is not fully compatible with straight Wayland.

Fedora-25 now has Wayland by default. To enable the XWayland backend:

export GDK_BACKEND=x11

This will still use gtk3, but will use the XWayland bridge rather than straight Wayland. This is expected to be fixed in the Oxygen (4.7) release of Eclipse to support straight Wayland.(

Thanks to Roland Grunber (Red Hat Linux Tools team) for pointing me in the right direction on #fedora-linux (freenode IRC).


How to know what version of gtk is being used in your session?

Help -> About -> Installation Details -> Configuration Tab

Look for something like:



How do you know you are running Wayland?

loginctl which should show you a list of sessions, one of which will be gdm, remember that session number.

loginctl show-session <session number from above> -p Type

Result should be:



Personal tools