Unreal Engine 4.1 Git Plugin alpha

So at last I’ve started implementing an open source C++ Git Source Control Plugin (Github) for Unreal Engine 4.1.

For know it is barely a Windows only “pre-alpha v0.0” version. It does only provide overlay icons to show status of your project content assets.

But it’s a start, and it will soon become more useful, I’ll keep you informed on the forums.

Edit 2014/05/17: UE4 Git Plugin alpha v0.1 released, with history log, revert, add and delete. Still no diff (next step) nor commit.

Edit 2014/05/20: UE4 Git Plugin alpha v0.2 released, with diff fully working. Still no commit (next/last big step) but know really useful for anyone using Git.

Edit 2014/05/21: UE4 Git Plugin alpha v0.3 released, with commit working for small batch of files.
As its quickly reaching completion, I’ve started a dedicated new thread on the “Engine Source & GitHub” section (still not ready for the more general “Tools” section I think).

Edit 2014/05/30: UE4 Git Plugin alpha v0.4 released, with many bug fixes and improvements to usability.
I’ve started to use it “for real” in my own small projects.
As I see it, I will move on “Beta” for the next version, to reflect this increased stability.
Please let me know if you try it, an report any bug or missing feature.

CMake for Android

Last time, we’ve seen how to install and test the standalone toolchain of the NDK to build a native shared library with a standard Makefile & make command under Linux.

CMake LogoBut nowadays, many open source libraries and projects does not directly come with a Makefile, instead using a build system to automate its generation. CMake is becoming more and more used for those kind of jobs, so being able to use it for Android is really interesting. And easy!

A CMake configuration file for Android (android.toolchain.cmake) is provided by the android-cmake Google project hosted on Mercurial (see my previous post on Mercurial). Let’s clone its repository in the home directory with the following commands:
hg clone https://android-cmake.googlecode.com/hg/ android-cmake
Then, add to your .bashrc the ANDROID_NDK_TOOLCHAIN_ROOT and ANDTOOLCHAIN environment variables pointing to NDK and to the cmake config file. I also added a simple alias for later use:

PATH=$PATH:$HOME/android-sdk-linux_x86/tools
PATH=$PATH:$HOME/android-sdk-linux_x86/platform-tools
PATH=$PATH:$HOME/android-ndk-r5b/standalone-toolchain-api5/bin/

ANDROID_NDK_TOOLCHAIN_ROOT=$HOME/android-ndk-r5b/standalone-toolchain-api5
ANDTOOLCHAIN=$HOME/android-cmake/toolchain/android.toolchain.cmake

alias cmake-android='cmake -DCMAKE_TOOLCHAIN_FILE=$ANDTOOLCHAIN'

Ok, let’s try to compile the “hello-cmake” sample provided by the Google project (see hello-cmake documentation):

cd ~/android-cmake/samples/hello-cmake/
mkdir build
cd build
export ANDROID_NDK_TOOLCHAIN_ROOT
cmake -DCMAKE_TOOLCHAIN_FILE=$ANDTOOLCHAIN ..

We can simplify the last command by using our alias, so next type we will use “cmake-android ..” instead.
At this stage, CMake has generated the Makefile for you. Use it to build the sample :
make
Here you are, the shared library has been build and is ready for integration in an Application. You can find it here:
~/android-cmake/samples/hello-cmake/libs/armeabi-v7a/libhello-cmake.so
Now we want to invoke this native library from a Java Application, using JNI. This is documented in the next provided sample, “hello-android-cmake“, which is the Java counterpart of the C application we’ve build.

Copy the above “libs” directory to ~/android-cmake/samples/hello-android-cmake. Then open Eclipse and start a “File->New…->Project…->Android Project”. Select “create project from existing source” and give it the ~/android-cmake/samples/hello-android-cmake path.

Build the application, and launch it on an emulator or an actual device. You should see an activity showing the multi-line text starting by “JNI — pi = 3.14159…” coming from our shared library !

Hello Android CMake

Here you are!

Standalone toolchain

Since the revision 5 of the Native Development Kit previously discussed, the NDK can be customized to obtain a standard GCC cross compiler toolchain. This means that you can use it with standard Makefile and make command, or with more sophisticated build tools like automake, CMake or Bakefile. No more Android.mk ant Application.mk proprietary format required ! This is great in many situation where you want to recompile a complex software with big libraries. Lets have a try !

For this experimental article, I’ll assume that you already have good knowledge of Android development, SDK, ADB and some good understanding of C/C++ compilation workflow (gcc, make and Makefile).

NDK Requirements :

  • Android SDK (yes, the Java part !) : I’ll use API-level 5 (Android 2.0) but the minimum is API-level 3 (Android 1.5): “~/android-sdk-linux_x86/”
  • Android NDK r5b (the C/C++ part): “~/android-ndk-r5b/”
  • GNU Make 3.81 or later (“make” package under Ubuntu or Debian)
  • GNU awk or equivalent (nawk says the documentation, I have mawk)

To make this work under Windows (XP or 7) you’ll need Cygwin 1.7 installed, but it’s not that simple (the standalone toolchain officially dos not support Cygwin…). For that reason I’ve decided to work on this entirely under Linux (latest Ubuntu in my case). I you want to try to make it work under Windows, you could exploit useful information from the following blog post http://www.pocketmagic.net/?p=1462 and from some other Internet sources.

So let’s start by reading the “/android-ndk-r5b/docs/STANDALONE-TOOLCHAIN.html“, and proceed directly with the instructions on section 3 “Invoking the compiler (the easy way)”. Under a Linux console, type:

~/android-ndk-r5b/build/tools/make-standalone-toolchain.sh --platform=android-5 --install-dir=$HOME/android-ndk-r5b/standalone-toolchain-api5

Then add this few lines to the end of your .bashrc file and restart a console (or type them directly on the console):

PATH=$PATH:$HOME/android-sdk-linux_x86/tools
PATH=$PATH:$HOME/android-sdk-linux_x86/platform-tools
PATH=$PATH:$HOME/android-ndk-r5b/standalone-toolchain-api5/bin/

Then, create a standard hello world “hello-ndk.c”:

#include <stdio.h>

int main(void)
{
    printf("Hello from NDK\n");
    return 0;
}

At this stage, compiling for Android works easily with the following command:

arm-linux-androideabi-gcc  hello-ndk.c -o hello-ndk

Before testing it, we would like to add a bit of android API in it. You can easily complete it with a minimal Android log (logcat for Eclipse) :

#include <stdio.h>
#include <android/log.h>

#define LOGI(...) ((void)__android_log_print(ANDROID_LOG_INFO, "hello-ndk", __VA_ARGS__))

int main(void)
{
    printf("Hello from NDK\n");
    LOGI("Hello from NDK");
    return 0;
}

For this, you need to link explicitly with a the “liblog” library :

  • arm-linux-androideabi-gcc  hello-ndk.c -l log -o hello-ndk

Here is a Makefile to handle this with a simple “make” command (or other “make clean” and “make clean all” variants):

CC	= arm-linux-androideabi-gcc
CFLAGS	= -Wall -g
LDFLAGS	= -llog
SRC	=hello-ndk.c
OBJ	=$(SRC:.c=.o)
EXE	=hello-ndk

all: $(SRC) $(EXE)

$(EXE): $(OBJ)
	$(CC) -o $@ $^ $(LDFLAGS)

%.o: %.c
	$(CC) -o $@ -c $< $(CFLAGS)

clean:
	rm -f *.o $(EXE)

This create the standalone executable hello-ndk, so if your device is rooted, you can use adb to copy and execute “hello-ndk” on it, like this:

% adb shell
$ su
# mkdir /data/tmp
# chmod 777 /data/tmp
# exit
$ exit
% adb push hello-ndk /data/tmp
% adb shell
$ /data/tmp/hello-ndk

You should get a “Hello from NDK” on the command line, and the same message on the logcat window of Eclipse (in green, info level).

Hello-NDK-LogcatFor normal users that are not root (no “su” command), there is no way (oops, see edit bellow) of launching directly a native application under Android: you have to package it in a standard Android application .apk and use it from Java code. See http://gimite.net/en/index.php?Run%20native%20executable%20in%20Android%20App.

edit: look at the comment from pitypang, the path /data/local/tmp should work for an unrooted phone !

So we need to build instead a shared library, a “.so” file to be loaded by a Java application (through Java Native Interface, JNI). For this, we need to modify the Makefile like this :

CC	= arm-linux-androideabi-gcc
CFLAGS	= -Wall -g
LDFLAGS	= -llog -shared
SRC	=hello-ndk.c
OBJ	=$(SRC:.c=.o)
EXE	=libhello-ndk.so

With this you will get a libhello-ndk.so shared library. This will do nothing interesting by itself; we need to invoke the native function from Java, or to use the NativeActivity.

I will update this post later to make this works.

Edit:  look also at my post on CMake for Android

Android 2.3 NativeActivity

At each platform API revision, the C native APIs are growing, giving access to new native library, and bringing each time more functionalities to the low level world of C/C++. At this point, they are starting to look mature enough for me to want to dive into them.

As discussed earlier, Android 2.3 (API-9) brings to the C/C++ developers a new Java Class called “NativeActivity“. This allow us to write an entire Android application without using the Java API, managing inputs, internal sensors and the application window entirely with the so called native C APIs of the platforms.

The provided “native-activity” sample (“android-ndk-r5/samples/native-activity“, or in the online documentation of the NativeActivity Class) gives you an example of making use of this new API through a threaded “app-glue” helper. The web page What is the NDK does explain how to create a project from sources of this sample, with or without Eclipse. I made it work flawlessly under the emulator (as I am currently stuck with Android 2.2, API level 8).

The “native_app_glue” wrapper (“android-ndk-r5/sources/android/native_app_glue“) is designed to abstract the complexity of creating a native pthread and synchronizing it with the NativeActivity Lifecyle callbacks. It thus manage for you most of the work needed to handle the complexity of the classical transition (onCreate, onStart, onSaveInstanceState, onResume…) but also more dirty tasks like managing the application window (onNativeWindowCreated…) or the input events looper (onInputQueueCreated…)

But if you want to really understand all the magic behind this app glue, if like me you want to make your own by yourself (for instance in C++), it will need time to dig in it, as there is no comments to help the reader ! I will update this post with a commented version of my C++ implementation, in a step by step process with explanations.

Android Native Development Kit

Android 2.3 Gingerbread has been announced, and what I find the most interesting in it is related to the Native Development KIT (NDK) coming with it; the NDK r5.
Android-NDK

The new API level 9 of Android 2.3 brings with it a “Native access to Activity lifecycle” : it allows developers to write an Android Application with absolutely no Java coding, by the use of a provided Java Class “NativeActivity“. A “native-activity” sample gives you an example of making use of it through the “native_app_glue”, a C-only wrapper (see also my experiments on NativeActivity).

At the same time this revision r5 of the NDK is becoming interesting for me, with the first official support of C++ exception and RTTI. There is also a way to get a “standalone toolchain” with GCC 4.3, which give the ability to use only standard cross-compiler command (make) instead of the specific Android.mk files.

All this is not really well documented… You get plenty of example and sources, but there is not much in-code comments nor any “Native API Reference” available. In fact, even the documentation is not available directly on Internet: it is only provided on the NDK archive!

I share it on this web server : here is the NDK-r5b HTML documentation (http://www.srombauts.fr/android-ndk-r5b/)

Edit: look at this Android Developer Blog post about Gingerbread NDK
Edit2: there is also a android-ndk Google group
Edit3: some other people share my enthusiasm about Gingerbread and the new NDK revision !