Android NDK + Eclipse + Windows = Headache!

Whew! Just spent an “interesting” hour or two trying to get some native android code working under Eclipse on Windows… Although this isn’t the first time I’ve used the NDK, it’s the first time I’ve tried to get it working with Eclipse on the Windows (+Cygwin) platform. To borrow an unrelated phrase from elsewhere, it’s been emotional – I’m guessing the problems I’ve had are a combination of my lack of knowledge of Windows, and Windows lack of knowledge of, well, anything really.

No flames necessary, by the way. My position on Windows as a development platform are well known around these parts, and I don’t think there’s really any need to go into all that again. But Windows is what I have to hand at the moment, so it’s what I must work with.

The background is that I had an existing Android project that had some cross-compiled code (actually, the Quake III engine) that required a bit of work. The engine itself is a separate (non-Android) project, so I started by grabbing the source from subversion, and did the cross compile using the latest NDK (r8b). This went without a hitch once I’d updated a few things in the Makefile to adjust for the local setup.

Cool“, thought I. “Now to get going on the Android side of things, where I actually need to make changes”.

The way this project is set up is fairly convoluted, but it works. The android side of things has a bit of C that exposes the game engine to Java via JNI. The engine itself is (as mentioned above) cross-compiled separately, and there’s a simple Ant build that takes care of copying in the required shared libraries during the build.

To cut a long story short, it didn’t work. I checked the project out, and Eclipse couldn’t resolve the platform includes. I checked it out as a new (basic Android) project. Still no includes. I checked it out as a new C++ project, and manually added the appropriate nature and settings for an ADT project (Yes, I was getting desperate). Predictably enough, still no dice. I deleted the whole thing. I checked it out from a terminal and fiddled with various things. I shouted a bit. I went away and watched TV for a while (“A touch of cloth“, a new spoof detective show on Sky 1, by the way, is hilarious!). I googled incessantly. I checked paths, and re-checked them. Still, Eclipse couldn’t find the includes.

The maddening thing in all this was that the ndk-build command was working fine, and building the JNI glue without any problems. Even during the Eclipse build, it was fine. But I couldn’t actually deploy the app from within Eclipse because the IDE itself couldn’t see the includes, and so wouldn’t let me launch the app because it contained “errors”. Googling had turned up quite a few people with similar problems, but none of the proffered solutions worked for me. The include paths in the Eclipse C/C++ build properties were obviously correct, but still, no includes. I added more paths. I changed what I could. I created a brand-new project with a basic JNI test as a sanity check. And guess what? That’s right. No includes.

Eventually, I decided that there must be some kind of problem with the Android tool chain provided by the ADT. In every case so far I’d gone the “right-click -> Android Tools -> Add native support” route, so I decided to get back to basics and do things manually. For anyone else who encounters similar problems, these are the steps I took:

  • I closed the project in eclipse, and deleted .cproject from a terminal.
  • I re-opened the project in the C/C++ perspective.
  • I went to File->New->Convert to a C/C++ project (Adds C/C++ Nature).
  • I selected “Makefile project“, and “–Other toolchain–” (obviously I tried the “Android GCC” option but ended up with the same problems).
  • I then fired up the Project Properties, and went into the Builders page. Here, I unchecked “Use default build command” and entered the following instead: bash -c 'c:/opt/android-ndk-r8b/ndk-build':Eclipse Builders Properties
  • I then switched to the “Behaviour” tab in this same dialog, and removed the ‘all’ argument to the incremental build command, and completely disabled the “clean” behaviour since I didn’t need it when using ndk-build manually:Eclipse Builders "Behaviour" dialog
  • Finally, I manually entered the include path into the “C/C++ General/Paths and Symbols” settings. In my case, the path I added was “NDK_HOME\platforms\android-14\arch-arm\usr\include“. I made sure that both the “Add to all configurations” and “Add to all languages” checkboxes were checked (I’m on Eclipse Juno, these checkboxes may not show up in earlier versions). So that the include paths ended up looking like:Eclipse include paths dialog
  • I applied these settings, and okayed the dialog.
  • Finally, for good measure, I closed the project, re-opened it, and ran a clean followed by a build, and all was good!

So that was it. The includes were all showing up (I actually had to prove this to myself by Ctrl+Clicking on an #include <jni.h> line!), and I could happily deploy and run the project from Eclipse. ndk-build was running (as it always had) but there were no more complaints from Eclipse. Needless to say, I’m happy. I can now get on with the actual work I set out to do in the first place.

I’m still not convinced this is a bug, so I haven’t filed any reports anywhere. But when I get chance to run down exactly what’s going on here in more depth I will either realise where I went wrong in the first place, or I’ll file bugs appropriately.

Final note: If you’re having similar problems, and decide to follow the steps I took, keep in mind that depending on your project you may need additional include paths, to ensure Eclipse can see the platform-specific headers from the NDK. In my case this wasn’t necessary, but if it is for you then just take a look at the standard paths in an NDK project, and copy them across as necessary.

Advertisements

Deelang – First file release available to download

After a few months in Subversion, with a few folks playing with the code and seeing what use they can make of it, the first file release of Deelang is now available from the project’s downloads page. This release is still a very early public release (as denoted by the 0.18 version number) but is already mostly functional (with the notable exception of first-class regular expressions, which may never make it in anyway) and ready for testing.

Like most of our Android stuff, Deelang started life as internal code for a (closed source) third-party app, that ended up being deemed “possibly generally-useful enough” for open-source. So, at the moment, it mostly does the things we needed it to do when it was written. And, as with ORMDroid, the intention here isn’t to just dump the code into Google Code and forget about it – I intent to keep developing these things. What I really need is for folks to pick up the code, start using it, and either come back to me and tell me what cool new things they want to see it do, or (even better!) send over a patch with the aforementioned cool new things.

In case you’ve read this far in the hope of finding out what the heck Deelang is, the project page summary puts it thus:

Deelang is a lightweight, embeddable, dynamically-typed scripting language for Java that is intended for use in user-scriptable applications in limited resource environments, and especially for Android devices.

Basically it’s a very simple scripting environment that allows you to provide some manner of customization to your users, or to others deploying your apps. You define an API (it comes with almost none, beyond a basic object hierarchy for ‘primitives’) for code to run against, and Deelang provides a compiler, and a virtual machine in which to run scripts against this API. To quote (again) from the project site on google, it allows you/your users/someone else to write scripts like:

pic = Camera.take_picture()
pic.save_to_media()

Facebook.share(pic) {
caption = "I just took this picture!"
  album = "Random pics I took"
} or {
  post_status("took a pic but couldn't upload it :(")
}

(Obviously, assuming you provide the appropriate Camera and Facebook implementations). These scripts can then be compiled and run on the fly, or compiled and cached for later, perhaps to run in response to some broadcast intent or whatever.

So anyway, if you have a minute, grab the code and take a look, have a look at the (sparse) wiki, see if Deelang might be useful in your own projects, and if you think of a killer feature that you could really, really use, get in touch via the comments and we’ll talk…

ORMDroid: Bugfixes + Sample App = Happiness!

So a few people have taken a look at ORMDroid since my previous blogs, and the feedback I’m getting most often is along the lines of “Sure, there’s some simple example snippets, but I want a complete, compilable, runnable example!” With this in mind, I’ve thrown together a very basic Android app that uses ORMDroid as it’s persistence framework. Like ORMDroid itself, it’s only in SVN for the moment, but you can browse the code online in the Google Code repository (Edit: Moved to Github), or check it out to build locally:

# git clone https://github.com/roscopeco/ormdroid-example.git

The sample app is a very simple address-book-type app that has a list of people and departments, with each person belonging to a department. It supports the basic CRUD operations, and gives a basic working example of ORMDroid in action.

A few things to note about the sample app:

  • It’s not pretty – It’s targeted at API 8 (ORMDroid’s minimum API level) and doesn’t have any kind of fancy UI, in order to keep the code simple. In fact, the UI is singularly awful (especially on newer devices), but that’s not the point!
  • It’s not clever – It just shows ORMDroid in use – it doesn’t necessarily exemplify best practices, and it has almost zero error handling. Over time it will be updated to at least check the best-practice box.
  • But it’s a start! If nothing else, it gives a template project off which you can base your own.

The second point above probably requires a bit of expansion. We all know that to make robust apps we need to be making reasonable checks for unexpected conditions, so we’ll just gloss over the error-handling aspect. But in terms of best practices, the sample app does all kinds of evil things, like blithely loading arbitrary object graphs into ArrayAdapters. On the UI thread no less. This is obviously not the kind of behaviour we want to endorse.

In fact, the whole point here is clarity – to allow you to see exactly what’s going on in the code with the minimum of fuss and boilerplate framework code. We’re trying to make it easy for you to look at a method and see exactly where the ORMDroid calls are happening, without having to wade through any number of AsyncTasks, adapters, and all that other stuff.

In the future, there will be more sample code (maybe as extensions to the current sample, or maybe as additional samples) that will serve to show how things should be done. For now though, take this code more as an example simply that things can be done.

A few bugfixes

While putting together the sample app, I found a few bugs in ORMDroid that are now fixed in SVN. If you’ve tried ORMDroid and experienced any of the following issues, you should grab a fresh copy:

  • Problems with models with only one field.
  • Problems when using ORMDroidApplication as your main Application class.
  • Problems with debugging SQL executed from EntityMapping.
  • Problems with executeMulti not ensuring the schema existed.
  • Problems with Query operators (lt, gt, and, or, etc).

Of course, if you’ve been experienced issues other than these, then you should get in touch and let us know!

Git on Dropbox

People have been doing this for ages, but I’m a bit late to the Dropbox (if you don’t have it yet, here’s my referral link) party and have only been using it for a little while (only since I got a One X which had a tie-in deal going with HTC Sense and Dropbox) so it was nice to stumble across this blog article today while looking around for a free way to host private git repositories off-site.

The long and the short of it is that you create a remote repo in your dropbox directory, and then it just follows you everywhere you go. I have to say, I love how easy git makes all this. We’re still using Subversion for “the work stuff” but the day can’t be far off when we migrate over to git…

ORMDroid on Google Code

Further to my previous post, I spent a bit of time today getting the ORMDroid project set up on Google Code (Edit: Moved to Github), including adding a bit of sample code to get you going with the library. I’m also working on extracting a simple sample project that will also go in the repository, which will serve as a proof of concept, a working example, and a functional testbed all in one.

Getting up and running with ORMDroid is really simple. Firstly, you need to add a single XML tag to your AndroidManifest.xml (it should be a child of the Application tag):

<meta-data
    android:name="ormdroid.database.name"
    android:value="your_database_name" />

Next, you need to initialize the framework somewhere. Application.onCreate() is the logical choice if you’re using a custom Application class (configured in your manifest – see Google’s JavaDocs if you want to go this route), but  you can happily call this from pretty much anywhere – even your activity’s onCreate() – since there’s actually no penalty for calling the initialize method multiple times.

ORMDroidApplication.initialize(someContext);

Side note: Currently, ORMDroidApplication is itself a subclass of android.app.Application, so you could go down the route of setting it directly as your application class, or subclassing it with your custom behaviour, and have the initialization handled transparently for you. However, this isn’t the recommended way, and it’s possible this facility will be removed in future versions.

With the framework initialized, you can start loading and saving your models! These are just plain Java POJOs that subclass the ORMDroid Entity class. If you’re happy with the default table and column names provided by the framework, these can be as simple as:

package com.example.myapp;

import com.roscopeco.ormdroid.Entity;

public class Person extends Entity {
  public int id;
  public String name;
  public String telephone;
}

Working with the Person class is now as simple as:

Person p = Entity.query(Person.class).where("id").eq("1").execute();
p.telephone = "555-1234";  // for example...
p.save();

And that’s it. No, really, it’s that simple. You don’t have to worry about setting up the database, ensuring tables are created, transaction management, or any of that other stuff. Of course, you can handle the database yourself if you really want to, but ORMDroid is more than happy to take care of it for you if you’ll let it.

The entity class in the example above will be stored in the following table:

CREATE TABLE comexamplemyappPerson (id INTEGER PRIMARY KEY AUTOINCREMENT, name VARCHAR, phone VARCHAR);

If you aren’t happy with this default mapping, you can use the Table and Column annotations to customize things, e.g:

package com.example.myapp;

import com.roscopeco.ormdroid.Entity;
import com.roscopeco.ormdroid.Table;
import com.roscopeco.ormdroid.Column;

@Table(name="people")
public class Person extends Entity {
  @Column(name="person_id", primaryKey=true)
  public int id;

  @Column(name="fullname")
  public String name;

  public String telephone;
}

A couple of things to note here are that the primaryKey parameter is actually redundant, since id would be used as a primary key in the absence of another field that has primaryKey=true, and that, and that you don’t have to annotate all the columns – only those you want to change the default mapping for.

And that’s it. You’re up and running with ORMDroid! Obviously this example code is very simple, and misses out probably the most important point with using an ORM framework – relationships. You can play with this yourself though – create another entity class, and give it a Person field. By default, whenever you persist your new class the related Person will be persisted as well. One-to-one relationships are already supported, and it’s easy to add helper methods to support many relationships using the query facilities provided by Entity. We’ll take a detailed look at relationships at a later date (this post is already long enough), but for now take a look at the code and I guarantee you’ll pick it up in no time anyway.

Introducing ORMDroid

Another year, another blog…

Actually, I’ve been out of the blogging cycle for a year or two now, as I’ve just been too busy with work to really dedicate any time to open source and my own projects, but a recent (positive!) change in my  work schedule means I’m now back and able to invest some time again.

Over the past couple of years I’ve been furiously developing solutions for a variety of clients, and in that time I’ve amassed a few different chunks of code that stand alone well enough, and are potentially generally useful enough, to be open sourced. Now I finally have some time, I’m going to start getting them out there, and hopefully get enough interest to get other developers involved.

So the first project, provisionally named ORMDroid, is an Object Relational Mapping framework for the Android platform. It grew (and is still growing) out of a quick (and very basic) solution that was created for a bespoke app a while ago and is still very simple – over time we’ve added features we’ve needed, and no more (well, not much more).

Why write an Android ORM framework? Well, at the time ORM on Android wasn’t served all that well. The two main solutions didn’t fit our needs – ORMLite just isn’t, well, lite enough, and ActiveAndroid‘s licensing doesn’t fit in with our ethos. Plus, for what we actually needed at the time it was fairly simple to hammer together a solution, which has grown since then through various iterations into the ORMDroid framework we’re using (and now open-sourcing) today.

The name may change soon (ORMDroid is just an internal name, and it turns out there’s already a project on Google code called ORMDroid, although it’s currently empty) and the API is certain to change, but right now it’s capable of managing very simple persistence mapping automatically for you. We’ve found it to be quite capable, and especially useful for getting database driven apps up and running quickly when the client just won’t wait!

The project has just found it’s way onto Google code (it’s at http://code.google.com/p/orm-droid/) and is currently source-only, but if you’re interested in ORM on the android platform come on over and take a look at the code (We’re using subversion as it’s fits with what we use in the lab). It’d be great to get any feedback, and even better to get some people involved.

Project page: http://code.google.com/p/orm-droid/
S
ource browser: http://code.google.com/p/orm-droid/source/browse/