With version 1.5 of the SDK, Google introduced the concept of virtual devices (AVDs). An AVD is simply a set of configuration attributes applied to an emulator image that allows the developer to target a specific version of the SDK. The following are the basic versions of the SDK targeted by AVDs:

Let's create an AVD to target an SDK 1.5 for the sample application.

Figure 2-2. Android Virtual Device Manager dialog box settings for SDK 1.5

Note that in Android 1.6 and later, the GUI has changed a little, as shown in Figure 2-3. To create an AVD, click New to open the Create New AVD dialog box, enter a name, select a firmware target plus SD card size, and then click Create AVD.

Figure 2-3. Creating a new AVD in Android SDK 1.6

With the AVD in place, the next task is to create the project for this chapter, as follows:

Figure 2-4. New Android Project dialog box for this chapter's example

Let's consider what we wish to accomplish with this application:

Figure 2-5 shows the file system layout of the project.

The following Java files describe the project:

Figure 2-5. Project layout

You must create the following files within the native folder (see Figure 2-5):

Let's look at the files in more detail to understand what they do. We'll start with the Java layer.

writeToStream(
getAssets().open(LIB),
openFileOutput(LIB, 0)
);

package ch02.project;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;

import jni.Natives;

import android.app.Activity;
import android.os.Bundle;

public class MainActivity extends Activity {
    private static final String LIB = "libch02.so";
    private static final String LIB_PATH =
        "/data/data/ch02.project/files/" + LIB;

    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);

        try {
            // Install lib
            System.out.println("Installing LIB: " + LIB);

            // Copy lib from assests folder to files folder:
            // /data/data/PKG_NAME/files
            writeToStream(getAssets().open(LIB), openFileOutput(LIB, 0));

            // Load Lib
            System.load(LIB_PATH);

            // Run it
            String[] argv = { "MyLib", "arg1", "arg2" };

            Natives.LibMain(argv);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    /**
     * Write to a stream
     *

* @param in
     * @param out
     * @throws IOException
     */
    public static void writeToStream(InputStream in, OutputStream out)
            throws IOException {
        byte[] bytes = new byte[2048];

        for (int c = in.read(bytes); c != −1; c = in.read(bytes)) {
            out.write(bytes, 0, c);
        }
        in.close();
        out.close();
    }
}

public class MainActivity extends Activity
{
    private static final String LIB = "ch02";

    // Load library: Note that the prefix (lib) and the extension (.so) must be stripped.
    static {
        System.loadLibrary(LIB);
    }

    public void onCreate(Bundle savedInstanceState) {
        // ...
        Natives.LibMain(argv);
    }
}

package jni;

public class Natives
{

    /**
     * Native Main Loop
     *
     * @param argv
     * @return
     */
    public static native int LibMain(String[] argv);

    /**
     * This fires on messages from the C layer
     *
     * @param text
     */
    @SuppressWarnings("unused")
    private static void OnMessage(String text, int level) {
        System.out.println("OnMessage text:" + text + " level=" + level);
    }

}

#include <stdio.h>
#include <stdlib.h>

/* JNI Includes */
#include <jni.h>

#include "include/jni_Natives.h"

#define CB_CLASS "jni/Natives"

/**
 * OnMessage callback
 */
#define CB_CLASS_MSG_CB  "OnMessage"
#define CB_CLASS_MSG_SIG  "(Ljava/lang/String;I)V"

// prototypes

// Lib main Sub
int lib_main(int argc, char **argv) ;

// Used to get the len of a Java Array
const int getArrayLen(JNIEnv * env, jobjectArray jarray);

// printf str messages back to java
void jni_printf(char *format, ...);

// Global env ref (for callbacks)
static JavaVM *g_VM;

// Global Reference to the native Java class jni.Natives.java
static jclass jNativesCls;

/*
 * Class:     jni_Natives
 * Method:    LibMain
 * Signature: ([Ljava/lang/String;)V
 */
JNIEXPORT jint JNICALL Java_jni_Natives_LibMain
  (JNIEnv * env, jclass class, jobjectArray jargv)
{
    // Obtain a global ref to the caller jclass
    (*env)->GetJavaVM(env, &g_VM);

    // Extract char ** args from Java array
    jsize clen =  getArrayLen(env, jargv);

    char * args[(int)clen];

int i;
    jstring jrow;
    for (i = 0; i < clen; i++)
    {
        // Get C string from Java String[i]
        jrow = (jstring)(*env)->GetObjectArrayElement(env, jargv, i);
        const char *row  = (*env)->GetStringUTFChars(env, jrow, 0);

        args[i] = malloc( strlen(row) + 1);
        strcpy (args[i], row);

        // Print args
        jni_printf("Main argv[%d]=%s", i, args[i]);

        // Free Java string jrow
        (*env)->ReleaseStringUTFChars(env, jrow, row);
    }

    /*
     * Load the jni.Natives class
     */
    jNativesCls = (*env)->FindClass(env, CB_CLASS);

    if ( jNativesCls == 0 ) {
        jni_printf("Unable to find class: %s", CB_CLASS);
        return −1;
    }

    // Invoke the Lib main sub. This will loop forever
    // Program args come from Java
    lib_main (clen, args);
    return 0;
}


/**
 * Send a string back to Java
 */
jmethodID mSendStr;

static void jni_send_str( const char * text, int level) {
    JNIEnv *env;

    if ( !g_VM) {
        printf("I_JNI-NOVM: %s
", text);
        return;
    }

    (*g_VM)->AttachCurrentThread (g_VM, (void **) &env, NULL);

    // Load jni.Natives if missing

if ( !jNativesCls ) {
        jNativesCls = (*env)->FindClass(env, CB_CLASS);

        if ( jNativesCls == 0 ) {
                printf("Unable to find class: %s", CB_CLASS);
                return;
        }
    }

    // Call jni.Natives.OnMessage(String, int)
    if (! mSendStr ) {
        // Get  aref to the static method: jni.Natives.OnMessage
        mSendStr = (*env)->GetStaticMethodID(env, jNativesCls
            , CB_CLASS_MSG_CB
            , CB_CLASS_MSG_SIG);
    }
    if (mSendStr) {
        // Call method
        (*env)->CallStaticVoidMethod(env, jNativesCls
                , mSendStr
                , (*env)->NewStringUTF(env, text)
                , (jint) level );
    }
    else {
        printf("Unable to find method: %s, signature: %s
"
                , CB_CLASS_MSG_CB, CB_CLASS_MSG_SIG );
    }
}

/**
 * Printf into the Java layer
 * does a varargs printf into a temp buffer
 * and calls jni_sebd_str
 */
void jni_printf(char *format, ...)
{
    va_list         argptr;
    static char             string[1024];

    va_start (argptr, format);
    vsprintf (string, format,argptr);
    va_end (argptr);

    jni_send_str (string, 0);
}

/**
 * Get Java array length
 */
const int getArrayLen(JNIEnv * env, jobjectArray jarray)
{

return (*env)->GetArrayLength(env, jarray);
}

/**
 * Library main sub
 */
int lib_main(int argc, char **argv)
{
    int i;

    jni_printf("Entering LIB MAIN");

    for ( i = 0 ; i < argc ; i++ ) {
        jni_printf("Lib Main argv[%d]=%s", i, argv[i]);
    }
    return 0;
}

#include <jni.h>

#include "include/jni_Natives.h"

javah -cp ../bin -d include jni.Natives

#define CB_CLASS "jni/Natives"
#define CB_CLASS_MSG_CB  "OnMessage"
#define CB_CLASS_MSG_SIG  "(Ljava/lang/String;I)V"

(Ljava/lang/String;I)V

static JavaVM *g_VM;
static jclass jNativesCls;

// Extract char ** args from Java array
jsize clen =  getArrayLen(env, jargv);

char * args[(int)clen];

int i;
jstring jrow;

// Loop thru Java array
for (i = 0; i < clen; i++)
{
    // Get String[i]
    jrow = (jstring)(*env)->GetObjectArrayElement(env, jargv, i);

    // Convert String[i] to char *
    const char *row  = (*env)->GetStringUTFChars(env, jrow, 0);

    // Allocate space
    args[i] = malloc( strlen(row) + 1);

    // Copy
    strcpy (args[i], row);

    // Free java string jrow
    (*env)->ReleaseStringUTFChars(env, jrow, row);
}

(*env)->GetArrayLength(env, jargs)

void jni_printf(char *format, ...)
{
    va_list         argptr;
    static char    string[1024];

    va_start (argptr, format);
    vsprintf (string, format, argptr);
    va_end (argptr);

jni_send_str (string, 0);
}

jni_printf("This is a message %d, %p, %x, %s", 10, somePointer, 0xFF, "Hello Java")

Before you run the project, you should make sure there are no missing symbols in the native library. This can be a tricky process, as the successful compilation of a shared library will not tell you about missing symbols. Even worse, if symbols are missing, and you try to run the program, the library will fail to load at runtime, leaving you with the headache of figuring out what went wrong.

An easy solution is to write a simple C program that will invoke the library (see Listing 2-8). Then, when linked, the compiler will tell you about missing symbols, which can then be fixed. This program can be also useful in testing the library from the command line before testing from the application itself.

#include <stdio.h>

extern int lib_main(int argc, char **argv);

//void _start(int argc, char **argv)
int main(int argc, char **argv)
{

    int i;
    printf("Argc=%d Argv=%p
", argc, argv);

for ( i = 0 ; i < argc ; i++ ) {
        printf("Main argv[%d]=%s
", i, argv[i]);
    }

    printf("Starting Lib main sub
");
    lib_main(argc, argv) ;

    exit (0);
}

Compile the program with make testlib, or manually using the helper scripts, as follows:

agcc -c     testlib.c
ald -o testlib testlib.o -L. -lch02

Note that you must link with -L. -lch02, which tells the compiler to link against libch02.so and search for the library in the current folder.

Now, start your emulator and let's test the library.

To test the library, upload the files to the device using make pushlib, which expands to the following commands:

adb push libcg02.so /data
adb push testlib /data

Then log in to the device, change to the /data folder, and execute the test program:

$ adb shell
# cd /data
# chmod 777 lib * test*
# ./testlib

bionic/linker/linker.c:1581| ERROR:   833 could not load 'libch02.so'
bionic/linker/linker.c:1641| ERROR: failed to link ./testlib
bionic/linker/linker.c:1741| ERROR: CANNOT LINK EXECUTABLE './testlib'

Here, you have run the program in the version 1.5 of the emulator. As you see, the library fails to load. The next section provides tips to figure out what is going on. If you try this process in the SDK version 1.0 R2, it will work.

Note that this doesn't mean the library will fail to load from the Java app. It simply tells you there is a problem with the native linker /system/bin/linker.

For some reason, the native test program for the library runs in version 1.0 R2 of the SDK, but fails to load in 1.5 R2. The output gives a clue: the file bionic/linker/linker.c:1581 fails to load the library. There is a simple Linux tool called strace that can help in this situation.

The strace tool runs the specified command until it exits. It intercepts and records the system calls that are called by a process and the signals that are received by a process. The name of each system call, its arguments, and its return value are printed. This is a useful diagnostic and debugging tool for solving problems with programs for which the source is not readily available. You will find that a great deal can be learned about a system and its system calls by tracing even ordinary programs.

The book source provides an Android version of strace. (strace is now a built into versions 1.5 and later of the Android SDK.) Let's push it and see what is going on, as shown in Listing 2-9.

$ adb push strace /data
$ adb shell
# cd /data

# ./strace ./testlib

execve("./testlib", ["./testlib"], [/* 10 vars */]) = 0
getpid()                                = 835
gettid()                                = 835
sigaction(SIGILL, {0xb0001a99, [], SA_RESTART}, {SIG_DFL}, 0) = 0
sigaction(SIGABRT, {0xb0001a99, [], SA_RESTART}, {SIG_DFL}, 0) = 0
sigaction(SIGBUS, {0xb0001a99, [], SA_RESTART}, {SIG_DFL}, 0) = 0
stat64("/system/lib/libch02.so", 0xbef9ea58) = −1 ENOENT (No such file or directory)
stat64("/lib/libch02.so", 0xbef9ea58)   = −1 ENOENT (No such file or directory)
mmap2(NULL, 4096, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, −1, 0) = 0x40000000
mprotect(0x40000000, 4096, PROT_READ)   = 0
fstat64(1, {st_mode=S_IFCHR|0600, st_rdev=makedev(136, 1), ...}) = 0
brk(0)                                  = 0x11000
brk(0x11000)                            = 0x11000
brk(0x12000)                            = 0x12000
mprotect(0x40000000, 4096, PROT_READ|PROT_WRITE) = 0
mprotect(0x40000000, 4096, PROT_READ)   = 0
ioctl(1, SNDCTL_TMR_TIMEBASE or TCGETS, {B38400 opost isig icanon echo ...}) = 0
write(1, "bionic/linker/linker.c:1581| ERR"..., 70bionic/linker/linker.c:1581| ERROR:   835 could not load 'libch02.so'
) = 70
write(1, "bionic/linker/linker.c:1641| ERR"..., 61bionic/linker/linker.c:1641| ERROR: failed to link ./testlib
) = 61
write(1, "bionic/linker/linker.c:1741| ERR"..., 71bionic/linker/linker.c:1741| ERROR: CANNOT LINK EXECUTABLE './testlib'
) = 71
exit_group(−1)                          = ?
Process 835 detached

The following lines give a clue to the source of the problem:

stat64("/system/lib/libch02.so", 0xbef9ea58) = −1 ENOENT (No such file or directory)
stat64("/lib/libch02.so", 0xbef9ea58)   = −1 ENOENT (No such file or directory)

The linker first tries to open the library from the device /system/lib folder. This is a read-only file system, and user-defined libraries cannot be saved there. Next, the linker searches the /lib folder, which doesn't exist, thus the link fails. The linker is not searching in the current directory—that is the problem!

The good news is that this will not prevent the library from loading within the Java application, as long as there are no missing symbols.

If you run the same sequence in a version 1.0 R2 of the SDK, you will see that the second line becomes the following:

stat64("./libch02.so", 0xbef9ea58)   = 0 OK

Thus, the program runs successfully.

Finally, if you wish to write a command-line tool to run in the device, you must do so statically. Consider the simple program in Listing 2-10 to print the command-line arguments to stdout.

#include <stdio.h>

int main(int argc, char **argv)
{
    int i;

    for ( i = 0 ; i < argc ; i++ ) {
        printf("Main argv[%d]=%s
", i, argv[i]);
    }

    printf("Hello World
");
    exit( 0);
}

If you compile the program with -static using the helper scripts, you get the following error:

agcc -c     main.c
ald -static -o a.out main.o
arm-none-linux-gnueabi-ld: cannot find -lc

The linker cannot find the C runtime libc.so, even though the path to the library is correct. Remember that ald uses -nostdlib to bypass linking against standard libraries.

When compiling statically (using -static), you must remove -nostdlib from the loader. Thus, the correct linking command should be as follows:

user@ubuntu:~/ch02.Project/native$ arm-none-linux-gnueabi-ld
 --dynamic-linker=/system/bin/linker
 -rpath /system/lib
 -rpath /home/user/tmp/android/system/lib
 -L/home/user/tmp/android/system/lib
 -static -o a.out main.o -lc -lm

/home/user/mydroid/prebuilt/darwin-x86/toolchain/
 arm-eabi-4.2.1/lib/gcc/arm-eabi/4.2.1/libgcc.a
 arm-none-linux-gnueabi-ld: warning: cannot find entry symbol _start;
 defaulting to 000080e0

Now you can test a.out in the device:

$ make pushbin
$ adb shell
# ./a.out test
Main[0]=test
Hello World