Barry McIntosh (CombThins)
1 September 2003
To comment, ask me a question, or add new information, please contact me.

 

Introduction
Before You Start
Stuff You Need
Installing
Setting up a Rockbox Project
Building
Running and Debugging Simulators
Known Issues

Introduction

Eclipse is an IDE, initially developed for Java development, but can be used for C and C++ when the appropriate plugin is installed.

Here I describe the steps I took to get Rockbox working in Eclipse. I make no claim that the instructions are 100% accurate or complete. It took a while to get everything working, there was a bit of trial-and-error in some areas, and I wrote these notes from memory after most of the work was done. It is also possible that something about your PC setup makes the process a little different for you.

So please treat these notes as guidance only, be prepared for some investigation if things don't go exactly to plan.

Finally, I have only tried this on Windows with Eclipse 2.1. I think that roughly the same route will work on other platforms, but some details will undoubtedly need to be changed.

Let me know of any errors or additional information you find out.

To the best of my knowledge everything I suggest you use is available for free, but it is your own responsibility to check license conditions etc.

Before You Start

I'm assuming that you are familiar with the Rockbox build environment, and that you have target builds and simulator builds building working using the command-line tools. If not, I suggest you go back to the main Rockbox site and get to that stage first.

Also the downloads are pretty big (Eclipse is around 65 Mbytes if you go for the full SDK version).

Stuff You Need

Java Runtime Environment

If you've not already got a recent Java runtime environment, go to java.sun.com and get a J2SE (Java 2 Standard Edition) JRE (Java Runtime Environment). If you also think you might use Eclipse for Java development I suggest you get the J2SE SDK instead, but it is a much bigger download. I used version 1.4.1_01 of the SDK; you may want to check the latest Eclipse recomendations for what version to use.

Note that you are not looking for J2EE, or J2ME - they are totally different things!

Eclipse

This is the main IDE. Get it from www.eclipse.org. I used version 2.1.0, but the latest stable released version should generally do; you may want to check any recommendations on CDT with regard to the version of Eclipse you will require.

There are various flavours available - I used the SDK, but there is also a runtime only package, which is a smaller download.

CDT for Eclipse

This is the C/C++ plugin for Eclipse. I've got version 1.1.0. Get it or a later version from www.eclipse.org/cdt.

Some of the downloads are quite big, so get them going now!

Installing

Just follow the instructions that come with each package really.

The Java runtime is usually a standard installer.

The Eclipse installation usually consists of just unzipping the package to C:\Programs\Eclipse or similar, and making your own shortcuts to Eclipse.exe on desktop, menus or whatever you fancy. Check it's basically working before installing CDT.

The CDT Eclipse plugin installation consists of just unzipping the package such that the plugin appears alongside others in your eclipse/plugin directory. Then when you start Eclipse, go to Window->Preferences, and you should see a C/C++ entry on the configuration tree.

Have a look around Eclipse. First thing you will notice is that the documentation is a bit sparse in places - but believe me, it's a lot better than it was a year ago. You have "Perspectives" (Windows->Open Perspective) which you open, then they appear as buttons on the left, making it easy to switch between the combinations of windows for different tasks. The perspectives you are likely to use are C/C++ Development and Debug. Each window or tab is a "View", and you can add views (Windows->Show View) close them or drag them around as you like.

Setting up a Rockbox Project

Open the C/C++ Development Perspective.

Do File->New->Project to get the new project wizard. Select to make a Standard Make C Project, give it a name, and select not to use the default location; instead enter your Rockbox build area directory (the one with apps, uisimulator, firmware etc. in it). On the last page of the wizard, on the Build Settings tab, enter a non-default make command of make −f uisimulator/win32/Makefile.eclipse

You should get a project showing your rockbox build hierarchy.

Before building the project, download  EclipseBuildExtras.zip, which has some additional files.

Put run-make.sh in your Cygwin rockbox/bin directory (or anywhere else that Cygwin will find it on the path).

Put Makefile.eclipse in uisimulator/win32 (or anywhere else to match the path in the make command set for the Eclipse project).

Edit uisimulator/win32/Makefile.eclipse, editing the variables at the top to match your Rockbox build directory names.

Building

Right-click the project and select Build. If you've done the setup correctly, the build will run, building simulator and target executables. In your project you should see Archive and Binaries items, which display all the recognised object, library and executable files. I had to exit Eclipse and restart it to get them to appear the first time.

You can add additional targets to the right-click menu to build any other targets in your Makefile.eclipse.

See below for some minor issues regarding building in after a clean build.

Running and Debugging Simulators

Use Run->Run... or use toolbar pulldown to create a new C/C++ Local setup. When browsing for the program to run you might have to do a bit of trial and error, as both your player and recorder executables have the same name.

Select Run->Debug... or use toolbar pulldown to run in the debugger. To set a breakpoint right-click on the grey bar at the left of the source editor window. Other than that it is easy to find your way around the debugger.

Known Issues

On the first build in Eclipse after a Make clean, the C/C++ Projects view will show some files as having problems due to missing headers. This is because the current rockbox build scripts produce some errors on a clean build (calculating dependencies), even though the build overall is successful. Just do a complete build (which will actually build nothing, so is very quick) and the errors should go away. I think some small changes in the main makefiles can solve this issue, and will update here when I have it done.