Android + HXCPP – a Quickstart Guide

After having some success with making an Xcode template, I thought it would be relatively easy make something similar for eclipse and Android. However, there was nothing but pain for me when I tried, so instead I’ve decided to write this guide.

Prerequisites

There are quite a few prerequisites you need to organize before you can get things going. Android allows building from Windows, Mac and Linux. The procedures are quite similar, except that Windows requires some messing about with Cygwin binaries. The method described here avoids most of the Cygwin pain \- and the google make sytem pain \- by avoiding the google make sysem altogether.

  • Download and install the Android SDK. This is the Java tools and libraries required for building and debugging byte-code applications.
  • Download and install eclipse IDE. This is the IDE that runs the SDK – follow the instructions on the Android SDK page and install the Android plugins too.
  • Install the USB drivers for your device (if required). For my device (HTC Legend) I found the drivers on the phone itself by using it as a thumb drive.

You should now be in a position to build some sample (byte-code) applications for your device.

  • Download the Android Native Development Kit. This allows you to build binary code for your device. Now for HXCPP, it is very important to download the latest build provided at Crystax.net, which is a build done by a generous community member that corrects some of the glaring omissions of the official build, namely RTTI and exceptions. If it is all the same to you, extract it to c:/tools/android-ndk for Windows, and ~/tools/android-ndk for other systems, and this will make the remaining instructions easier.
  • Currenly on Windows, you need the svn version of HXCPP (slightly newer that 2.06.1) which has some include path fixes. See the instructions at http://code.google.com/p/hxcpp/ for getting the latest version.
  • Also on windows, you need the Cygwin dlls in your path. One way to do this is to install the whole Cygwin toolchain and put it in your path. The other way so to drop the two dlls from cygwin-extra.tgz into the ndk binary directory, ie c:/tools/android-ndk/build/prebuilt/windows/arm-eabi-4.4.0/bin.

Project structure

An android project consists several components that all work together.

  • Java Code. The Java code provided in the sample project comes from a couple of places. Because the project is graphics based, the copy NME Java code is included. If the version of NME increases, it may be desirable to update the NME code, either by copying the new code in, or instead linking to the NME code directly. Also, the HXCPP bootstrap Java code is included along with a small Activity wrapper file.
  • Native code. The shared object files provide native code for running on the device. These include the standard libraries, the NME library and the haxe code compiled with hxcpp.
  • AndroidManifest.xml. This controls how your application is deployed, and quite a few things can be done with this file. It is best to consult the Android documentation about what can be done here.
  • Resources & Assets. These can be useful if you want to add standard menus or other GUI elements to your application.

The basic workflow starts by making a change to your haxe source files. You then compile the haxe code to Android cpp, which is in turn is compiled to an android shared object. This .so file is then copied to the libs/armeabi directory in the project. Because eclipse does not recognize a change to the shared objects as a important update, it is then necessary to touch one of the Java files so that eclipse rebuilds the project. These steps are handled by the build_haxe batch/shell scripts provided with the project, so all you should have to do is change the code and run the script. Then, press the “play” button in eclipse(the first time you do this, you may need to specify Run-As Android Project) and your application should launch.

The haxe code included in the sample directory uses a fixed class name, AndroidMain, as the bootstrap point for building the haxe shared object, libAndroidMain.so. By fixing these names, the build script is simplified. I encourage you to put your main code for the application outside the provided project directory, and edit the AndroidMain.hx and build.hxml files to point to this external application code. This will help with cross-platform development, and keep the boiler-plate code separate from your precious source code.

Creating a New Project

I could not find a very nice way to make a project template, so this is what I’ve come up with. First, download and extract the example project, android-2.06.1.tgz. You may like to rename the parent directory from android-2.06 to something more meaningful at this stage.

At this point, you should be able to build the sample haxe code using the build-scripts provided. This requires your prerequisite installations to be good, so it is worth testing. If you have downloaded the android-ndk to a different location, you can edit the appropriate build script to reflect this. You will need the latest NME code from haxelib. Windows users may also need the svn version of HXCPP.

So that all worked? Congratulations, your system is set up for development.

Next, fire up eclipse, and create a “File – New Project..”, then select “Android Project”, then select “Create project from existing source”, and browse to your newly created directory. You will notice that down the bottom of the Dialog, the properties are filled out with names from the sample project – we will change these next. Once you select “Finish”, your project should be created, and ready to run on your device.

The project and package names are tied into Java and Android naming conventions, as well as the Android manifest, and can be difficult to budge. It is easiest to use the eclipse Refactor-Rename menu option to change the name from “MyActivity” to something more appropriate for you, say “CircleDisplay”. Then in the source tree under “src”, there is a file in com.company called “MyActivity.Java”. Select this, and use the menu option to change its name to “CircleDisplay” too. Similarly, select the “com.company” and change this to something else, in my case “com.gamehaxe” (select preview and agree to everything). There is one final change required – the refactor option misses a reference in the AndroidManifest.xml because it starts with a period. Double click this and in the “AndroidManifest.xml” tab, change the “.MyActivity” to “.CircleDisplay”.

It is important to rename these items because it effects how your application is ultimately stored in the device.

So now you should be good to go – press the play button and select “Android Project”.

There are quite a few things that can go wrong with so many things to install, so I’ve got my fingers crossed for you.

21 Replies to “Android + HXCPP – a Quickstart Guide”

  1. I have just make it gone on mac.demo goes fine on HTC Magic(G2)?nice work?

    I have add some java code to copy my image assets to my sdcard,so fopen can acces it.

    I’m now trying to move a simple game to android,but It seem that drawTile and copyPixel can’t be use now,it will show “E/libEGL called unimplemented OpenGL ES API”.

  2. oh sorry,I think drawtile and copyPixel is work on htc G2.
    The problem is on graphics.beginFill(),whatever color I set ,it always fill 0xffffff (ex:beginFill(0xff0000,0.5) equal beginFill(0xffffff,1?and it will cause a “E/libEGL called unimplemented OpenGL ES API” error.

    It work nice on sumsung i5700.

    but Timer.delay is not work both on i5700 and HTC G2.

    thanks for you all hard work!!!

  3. This may be a bit off topic, but is there a way to use an external swc for haXe cpp? More specifically can I get the Union Platform Reactor (unionplatform.com) to be able to compile properly with hxcpp. I’ve tried using stub reference (swf-lib compiler tag) which works fine in haXe flash9 but gives pointer errors when compiling.

    Thank you.

  4. I had a problem with receiving TouchEvent on Nexus One in my haxe nme sample, and had some time to dig the problem. It appears that cause of the problem is in the MainView.java method named onTouchEvent – sometimes it receives “touch begin” event and “touch move” but calls Runnable in the queueEvent() block only once for the second event and in the result the “touch begin” event is lost.
    I wrote a piece of code for making a queue in the onTouchEvent and then process multiple queued events in the queueEvent() and the problem was gone.
    Hope this helps somebody.

  5. Hello, i have just compiled the sample under archlinux for android 2.2 and run it with HTC Desire.

    However, to compile under linux, I had to add those lines to hxcpp/2,07,0/build-tool/BuildTool.hx (line 1001):
    ——————– cut here —————-
    else if ( (new EReg(“linux”,”i”)).match(os) )
    defines.set(“ANDROID_HOST”,”linux-x86″);
    ——————– cut here —————-
    and then recompile with haxe Compile.hxml within this directory.

    So please add those linux related fixes to the next hxcpp release.

    OTOH, I wonder how to easily get info from the device sensors (e.g. compass) and use it in haxe code. Any ideas?

  6. Hi,

    I’ve been trying to develop an application with the android template, but no dice. I’m on a mac OSX snow leopard, i’ve installed the NDK ( Crystax version ) to the ~/tools folder and setup everything else with eclipse. The already built sample works like a charm but when i try to rebuild the haxe code i get the following error:

    cc1plus: error: unrecognized command line option “-Wno-psabi”
    /usr/lib/haxe/lib/hxcpp/2,07,0//include/hxcpp.h:1: error: bad value (armv5te) for -march= switch
    /usr/lib/haxe/lib/hxcpp/2,07,0//include/hxcpp.h:1: error: bad value (xscale) for -mtune= switch
    Called from ? line 1
    Called from BuildTool.hx line 1114
    Called from BuildTool.hx line 501
    Called from a C function
    Called from BuildTool.hx line 530
    Called from BuildTool.hx line 647
    Called from BuildTool.hx line 675
    Called from BuildTool.hx line 153
    Uncaught exception – Error creating pch: 256 – build cancelled
    Invalid build – ignored

    The next thing i did is try using the google version ( currently r5 ) but again no succes everything compiles a-Ok,( also i’ve touched one of the java files just to make sure eclipse builds everything). Afterwards i tried to install it to a simulator. The simulator screen goes into launch state but as soon as the application starts deploying it exits without any error code just two lines of GC freed.

    I’m using the same haxe package for iphone development and that one works perfect :D, ( by the way excellent job 🙂 ). I’m a bit of a noob when it come to Macs so it’s clearly somethin i haven’t done … could you point me in the right direction.

    Thank you for this wonderful project 🙂
    Gabriel

  7. The new NDK 5b directory structure breaks the batch file and hxcpp android BuildTool.hx.

    Just wanted to give you a heads up.

    It looks like you can’t download 4b anymore.

  8. I was wondering if you are planning/going to support Maemo (or at least MeeGo) as build targets? Or are you staying with just iOS and Android?

  9. goshki,
    It is on my radar, but I have no plans at the moment. I’m spread pretty thin at the moment, so someone else would have to champion the port.
    Huge

  10. ”Victor says:
    November 20, 2010 at 12:16 pm
    I had a problem with receiving TouchEvent on Nexus One in my haxe nme sample, and had some time to dig the problem. It appears that cause of the problem is in the MainView.java method named onTouchEvent – sometimes it receives “touch begin” event and “touch move” but calls Runnable in the queueEvent() block only once for the second event and in the result the “touch begin” event is lost.
    I wrote a piece of code for making a queue in the onTouchEvent and then process multiple queued events in the queueEvent() and the problem was gone.
    Hope this helps somebody.“
    I met this problem on android too,some MouseEvent were lost and touch screen would make fps down a lot.Do you have any idea Hugh?

    1. Hi,
      I have been given a patch for this. The root of the problem is that I do not clone the event, and the OS recycles the pointer, changing what I think I have passed off. I hope to get this fixed properly soon.
      Hugh

  11. Hi,
    Great tutorial, working perfect. Except I can’t figure out how to load an external file. I’ve tried all the combinations but nothing seems to work. Say I put a jpg file in the asset directory of eclipse. Then, in Sample.hx, I do the following :
    nme.display.Loader l_Loader = new nme.display.Loader();
    l_Loader.contentLoaderInfo.addEventListener( Event.COMPLETE, OnDataLoaded );
    l_Loader.load( new URLRequest( “file:///android_asset/image.jpg” ));
    Lib.current.addChild(l_Loader);

    This displays nothing. Do you have any idea ?
    Thanks.

  12. Can i skip the eclipse part? Or at least can i use the textmate bundle for android? What i’m trying is to compile from command line because i’m totally lost and i want to understand what’s happening. I’ve installed the android sdk (i think, 2.2Gb), android-ndk, hxcpp from haxelib, nme from haxelib, your sampel project, and i get:

    cristi:android cristi$ ./build_haxe.sh
    haxelib run hxcpp Build.xml haxe -Dandroid -Dcpp -Dhaxe_207 -Dnme -Dtrue
    Creating hxcpp.h.gch…
    g++ -Iinclude -I/tools/android-ndk/build/platforms/android-5/arch-arm/usr/include -I/tools/android-ndk/build/prebuilt/darwin-x86/arm-eabi-4.4.0/arm-eabi/include/c++/4.4.0/ -I/tools/android-ndk/build/prebuilt/darwin-x86/arm-eabi-4.4.0/arm-eabi/include/c++/4.4.0/arm-eabi -I/tools/android-ndk/build/prebuilt/darwin-x86/arm-eabi-4.4.0/lib/gcc/arm-eabi/4.4.0/include -I/usr/lib/haxe/lib/hxcpp/2,07,0//include -Iinclude -fpic -fvisibility=hidden -ffunction-sections -funwind-tables -fstack-protector -fno-short-enums -D__ARM_ARCH_5__ -D__ARM_ARCH_5T__ -D__ARM_ARCH_5E__ -D__ARM_ARCH_5TE__ -Wno-psabi -march=armv5te -mtune=xscale -msoft-float -fomit-frame-pointer -fno-strict-aliasing -finline-limit=10000 -DANDROID -Wa,–noexecstack -O2 -DNDEBUG -c -frtti -o hxcpp.h.gch /usr/lib/haxe/lib/hxcpp/2,07,0//include/hxcpp.h
    cc1plus: error: unrecognized command line option “-Wno-psabi”
    /usr/lib/haxe/lib/hxcpp/2,07,0//include/hxcpp.h:1: error: bad value (armv5te) for -march= switch
    /usr/lib/haxe/lib/hxcpp/2,07,0//include/hxcpp.h:1: error: bad value (xscale) for -mtune= switch
    Called from ? line 1
    Called from BuildTool.hx line 1125
    Called from BuildTool.hx line 509
    Called from a C function
    Called from BuildTool.hx line 538
    Called from BuildTool.hx line 655
    Called from BuildTool.hx line 683
    Called from BuildTool.hx line 161
    Uncaught exception – Error creating pch: 256 – build cancelled
    Invalid build – ignored
    cristi:android cristi$

    1. Hi,
      It looks like your “g++” is finding a linux one, rather than the android one. The “path” commands should have sorted this out, but google move their tools around all the time.
      There is a new system in the SVN builds on nme, that avoids eclipse altogether (yay!) and is much simpler to get going. See http://gamehaxe.com/2011/04/05/nme-from-scratch/

Leave a Reply

Your email address will not be published. Required fields are marked *