Saturday, 16 January 2016

Eclipse Part 2 - Host Debugging with the Runtime Environment

Using the Eclipse Run Time Environment

As a followup to my post about compiling on Eclipse I had a quick look at how to use the Eclipse runtime environment. This his handy for debugging host code running on the ARM chip.

I am currently using the 2015.1 Ubuntu version running on a Parallella server. The OpenCL version is 1.6.2. If you want some source code to practice on, use the mandelbrot example from the first Eclipse post.


For this post I'm assuming that you have a program in Eclipse that has successfully compiled. The steps in the first Eclipse post are still correct for the 2015.1 version of Ubuntu.

I'm still using the JIT compiler because I have not yet figured out a way of using two different compilers in Eclipse. Code::Blocks lets you create different compile targets using different compilers and then combine the results at link time. If there are any gurus out there who know how to do this using Eclipse then please let me know.

Setting Up

The most important thing you need to do before you can run a program is to set up your environment. Eclipse has a runtime environment but it does not pick up critical bits that you need to use the JIT compiler and run your OpenCL application.

Here is what you need to do with a few other bits thrown in:

Choose Properties from the Project menu giving you this dialog:

Click the "Run/Debug Setting" entry on the list and you will see a default Launch configuration. Click Edit to show:

This dialog controls what and how your application is launched from within Eclipse.

The Name: defaults to you project name but in this box it refers to a specific launch configuration. You can have as many as you like to test out different combinations of settings.

I usually leave the other fields as they are because I'm using it to debug and that's what you get as a default. I might disable auto build if it gets annoying.

To get the program running you need the Environment tab.

This is where you set your environment variables. The minimum you will need are LD_LIBRARY_PATH and PATH. 

To add a new variable click the New... button. 

LD_LIBRARY_PATH you can copy from your environment and paste into the New... box as is. 

Do the same with PATH but add :/bin to the end of it. Oddly this is not on your path and is not in Eclipse either and without it, basic stuff like the cp command (needed by the JIT compiler) will not work.

If your program needs any other environment variables include them here also (except PWD - see below).

While we are here, have a look at the Arguments tab:

If your program uses command line arguments type them in the box exactly as you would on the command line. They will appear in argv as per normal.

If you want to change the working directory, un-click the Use Default box and type the directory you want in the text box. This stands in for the PWD variable. Note that Eclipse will not know what $HOME is unless you have included it as an environment variable in the Environment tab.


Now that you have set the environment you can run your program from the tool bar:

The green Play icon has a small downwards pointing arrow next to it. Your run time configurations will appear on the on the top of the list. Click the one you want to use or just press the icon if you only have one.

This will run your program using the console sub-window for text output.


Notice the little insect on the tool bar next to the play button. This launches a debug session which uses the same configurations that you defined previously except it takes notice of break points. Set break points using the Run menu:

Press the creepy-crawly button to launch the debug session. This will pop up a perspective switch warning:

Just press "Remember my decision" and Yes never to be annoyed by this again.

Then you will see the full glory of the debug window:

There is more here then this short tutorial can cover and I cannot say that I'm in any way an expert. Underlying the fancy windows is gdb which I find annoying and so I know the minimum I need to know to figure out what is going wrong.

The usual navigation buttons are next to the Resume button and the in-scope variables are in the top right window. For some reason, variables are often "optimized out" which is frustrating.


I still have not made any progress with kernel debugging on the Epiphany. If I do, I'll let you know.

For now, have fun and write brilliant code.