Getting started with Android NDK

You want to try out the Android NDK? I have gotten a lot of questions about how to setup and work with the NDK and I decided to write down how I do it. My goal with this entry is to gather all the information you need to get started with the Android NDK. I will not get into details about installing the basic components but will focus on setting up the environment. So you will need some knowledge about working with Android.

You will need to download and install a couple of things.

Eclipse

I usually go with the Eclipse Classic version. It is available from eclipse.org. Installing Eclipse is simply just unpacking the downloaded file.

Android SDK

The SDK is located at developer.android.com There is a really good installation guide at developer.android.com

Android NDK

The NDK is located at developer.android.com with an installation guide.

Eclipse C/C++ Development Tools

To make it a bit easier we also install the C/C++ Development Tools to get C/C++ support in Eclipse. From the ‘Help’ menu choose ‘Install New Software…’

From the drop down select the update site for your eclipse version, in my case Indigo.

Under ‘Programming Languages’ you will find ‘C/C++ Development Tools’. Select it and click ‘next’ and follow the install instructions.

Getting started

I will show you how to get started by making a small application called NDKSetup.

Create a new android project for this example I will call it NDKSetup.

Project Wizard

First thing we need to do is to create a new folder called ‘jni’

The next thing we need to do is to setup Eclipse so we can build the JNI code. Click on the small down arrow on the external tool button and choose the ‘External Tools Configuration…’.

Mark the ‘Program’ and click on the ‘new’-icon.

Select a proper name.

Location is the location of the external tool you want to run, in our case the ndk-build file. Click on ‘Browse file system…’ and locate the ndk-build file located under your NDK folder.

The working directory is the jni folder we created in our project. Click on ‘Browse Workspace…’ …

… and choose the jni folder.

You should now have something looking like this:

Press run and you will get this error:

This means two things. Your setup to the ndk-build works and you are missing the Android.mk file.

Create a new file called Android.mk in the jni folder.

In the Android.mk file write this:

LOCAL_PATH := $(call my-dir)
An Android.mk file must begin defining the LOCAL_PATH variable, this is where the source files are. The macro ‘my-dir’ is the path where the Android.mk file is located.

include $(CLEAR_VARS)
Since all the building and parsing is done in the same context the variables called LOCAL_XXX is globals and need to be cleared.

LOCAL_MODULE := ndksetup
This is where you set the name used as the identifier for each module. Later used in java when loading the module. The system will add ‘lib’ before the module name when compiling into the .so file. So ndksetup will become libndksetup.so. The only exception is if you add ‘lib’ first in your module name then the system will not add it.

LOCAL_SRC_FILES := native.c
Here you add a list of the files you need to compile your module. You do not need to add headers or include files the system will take care of that for you.

include $(BUILD_SHARED_LIBRARY)
The NDK provides you with two make files that parse and build everything accordingly to your Android.mk file. The two once are BUILD_STATIC_LIBRARY for building static library and BUILD_SHARED_LIBRARY for building shared library.

For the example project here we use the BUILD_SHARED_LIBRARY.

If you run the external tool “NDK Build” we get a new error:

So lets att the missing native.c file into the jni folder.

Before we start adding code to the native.c file I think it is easier to write the API starting from java. We start by adding the loading of the library.

We also need to define the function we are going to implement. By adding the keyword ‘native’ the system will know it is a function located in the native code.

Putting in all together give us this:

Back to the native.c file.

The name structure of the function is important. It is build from the java starting with a java identifier followed by the package name, followed by the class name, followed by the function name. This is one way of converting our java function into the native function. I usually do it by right clicking on the function name ( printLog ) and select ‘Copy Qualified Name’ paste it in the native.c file:

Start by changing all dots (.) to underscores (_).
Add the return value and a Java_ identifier to the function:
The input variable is a String in java so lets make it a java string in native as well.
The last thing we need to add is a reference to the JNI enviroment and a reference to java object that this function belongs to.

Finally our first native function will look like this:

Just for fun we add another function, a fibonacci function.

Now you are up and running with your NDK development for Android.

17 Comments

  1. Fry

    Thanks!! it works great !!

  2. Kiran

    Perfect. Really helped. Thanks a lot.

  3. Sharadchandra Pawar

    Your blog is very nice…
    It is very helpful.
    Thank You..

  4. Faniola Michel

    Hi,

    I need your help please. I need to use a static library that was developped by a third-party with NDK. Every time I try to integrate this library, I get errors. Could you please explain me how that could be done or give me a reference?

    Thank you very much in advance.

  5. Beautiful sir! More more! Bravo. Please make more tut’s on NDK. Pretty please with sugar on top! Rock on brother. Cheers!

  6. ANURAG SHARAN

    VERY PRECISE AND EXCELLENT TUTORIAL NEEDED URGENTLY
    THANKS…

  7. Vaishali

    Thanks..helped me…!!!

  8. Sayali

    Exception occurred executing command line.
    Cannot run program “E:say_androidandroid-ndk-r9cndk-build” (in directory “E:nativefirstjni”): CreateProcess error=193, %1 is not a valid Win32 application

  9. Enrico Br

    Thanks for this nice and useful tut! Thumbs up

  10. Vishal

    I get error 193 (%1 is not a valid Win32 app), when I run the app following these steps. What could be the reason?

  11. Niall

    I don’t even follow these steps and I get that win32 error. As a temporary solution I recommend not using Eclipse and instead building from the command line.

  12. It is brilliant! It is the best article about NDK.

  13. shailesh

    Thanks, It is a nice tut on NDK.

  14. shailesh

    One thing is there.
    when i add second function of fabanacci. It unable to compile.
    collect2: ld returned 1 exit status
    make: *** [D:/android/******/NdkSetup//obj/local/armeabi/libndksetup.so] Error 1

  15. Andreas

    Really nice tutorial. Well explained without leaving out any steps. Thanks for that!!

  16. Renan Galdino

    Thanks from Brazil

Trackbacks for this post

  1. JNI NDK Android, how to make the .so file on mac os x snow leopard | BlogoSfera

Leave a Reply