README

DISCONTINUATION OF PROJECT.

This project will no longer be maintained by Intel.

Intel will not provide or guarantee development of or support for this project, including but not limited to, maintenance, bug fixes, new releases or updates.

Patches to this project are no longer accepted by Intel.

If you have an ongoing need to use this project, are interested in independently developing it,
or would like to maintain patches for the community, please create your own fork of the project.

+-------------------+
| dLeyna in Android |
+-------------------+

This is (1) a collection of native libraries ported for use in Android
applications, (2) an Android application that runs various unit tests of the
native libraries, and (3) an Android application that demonstrates dLeyna
functionality.

Native Libraries
----------------

Dleyna depends directly or indirectly upon the following native libraries:

    gupnp-dlna
    gupnp-av
    gupnp
    gssdp
    libsoup
    libxml2
    glib (glib, gio, gmodule, gobject, gthread)
    gettext (libintl)
    iconv
    libffi

The remote locations of the library sources, the dependencies between them,
how to configure and build them are all described using JHBuild. See
modulesets/android-native.modules. The "standalone toolchain" from the Android
NDK is used to build the libraries.

A convenient script allows you to specify the target architecture (arm
or x86) and Android API level you want to build for, as well as the
version of the cross-compiler from the Android NDK to use:

    [ARCH=<arch>] [API_LEVEL=<level>] build.sh [<cmd>...]

where

    <arch>    is 'x86' or 'armeabi' (default 'x86')
    <level>   is an Android API level: 3,4,5,8,9,14 or 19 (default '19')
    <cmd>...  is a JHBuild command and args (default 'build gupnp-dlna')

The result of the build will be left in a subdirectory named

    install-<arch>-android-<level>

which might be, for example

    install-x86-android-19

Test Native Libraries
---------------------

This is an Android app that incorporates a large number of the unit tests
from the native libraries. It allows the user to select which tests to run,
then sequentially runs them, each in a pristine process. While a test is
running, the user can abort it and skip to the next one, or abort all the
tests.

Before building the test app, you have to make a copy of the configured library
source code into a directory with a name that contains the target architecture
and api level (because some of the unit tests include internal header files
that aren't built out to the install directory). So for example if you're
building for x86 and api level 19, you must do the following:

    cd NativeLibs
    cp -r sources sources-x86-android-19

After doing so, you need to check the correct architecture is selected
in TestNativeLibs/jni/Application.mk You should be able to switch freely
between armeabi and x86 (tested).

Now, the building process is a several steps one (we might automate some of
this in the future). First, you need to make sure the test app is correctly
configured for your target Android's API version. Ideally you'd run this on
TestNativeLibs/ each time you change API versions while building the NativeLibs
(And for that, the first time you build). Although this is not always required,
it certainly doesn't hurt:

android update project --name testnativeapps --path . -s --target "android-19"

Example above is for API level 19 as you might have guessed.

The final step is building the application .apk install package. You do this
from the TestNativeLibs/jni directory, issuing the following command:

NDK_DEBUG=1 ndk-build

The example above would generate debugable native code. You can (and maybe
should) skip the NDK_DEBUG=1 for production builds.

Last step is generating the Application's .apk package from the TestNativeLibs
directory:

ant debug

(Again, this generates a debug apk)

The resulting apk file can be found in TestNativeLibs/bin/

Some of the unit tests expect various resource files to be on the target device.
So before running the test app for the first time on a given device, you must do

    cd TestNativeLibs
    ./InstallResourceFiles [<device>]

where <device> is the name of the device as reported by "adb devices" (only
required if more than one device is visible to adb).

As a final step and for installing the application to a device, connect it and
issue the following command:

adb install TestNativeLibs/bin/<your application name>-debug.apk

Notes on adding tests to the TestNativeLibs application
-------------------------------------------------------

Here is an outline of what you would need to do to add a new unit test:

1) Copy the unit test source from NativeLibs to TestNativeLibs. For example:

    cp NativeLibs/sources/libsoup-2.40.3/tests/socket-test.c \
        TestNativeLibs/jni/libsoup-2.40.3/tests

2) Edit the copied source to rename the function "main" to something unique. For
example in socket-test.c you might rename it to "socket_test_main".

3) Add the test case to TestNativeLibs/jni/tests.c. Here you specify the renamed
main entry point, that same name in Java style, and any args to pass to the main
entry point:

    DEFINE_TEST(soup_socket_test, soupSocketTest, "--debug")

4) Modify TestNativeLibs/jni/Android.mk to add the new unit test. For example

    LOCAL_SRC_FILES := \
        ...
        $(MY_LIBSOUP)/tests/socket-test.c \

Also, add a proper defintion for your static library module at the begining of
the file. Like:

    # <modulename>
        include $(CLEAR_VARS)
        LOCAL_MODULE := <modulename>
        LOCAL_SRC_FILES := ../../NativeLibs/install-$(TARGET_ARCH_ABI)-$(TARGET_PLATFORM)/lib/...
        include $(PREBUILT_STATIC_LIBRARY)

Use the ones already there as a basis and adapt it as needed

5) Still on TestNativeLibs/jni/Android.mk. Locate the module definition for
dleyna_jni and add your library and library tests include paths to
LOCAL_C_INCLUDES as:

    ../../NativeLibs/install-$(TARGET_ARCH_ABI)-$(TARGET_PLATFORM)/include/<library_headers_dir> \
    ../../NativeLibs/install-$(TARGET_ARCH_ABI)-$(TARGET_PLATFORM)/include/<library_headers_dir>/... \
    ../../NativeLibs/sources-$(TARGET_ARCH_ABI)-$(TARGET_PLATFORM)/$(MY_<MODULENAME>) \
    ../../NativeLibs/sources-$(TARGET_ARCH_ABI)-$(TARGET_PLATFORM)/$(MY_<MODULENAME>)/tests

The example above relies on you declaring a MY_<MODULENAME> var at the begining
of the dleyna-jni module declaration so you can use it later and avoid having to
repeatedly enter your library tests and library's top level include directory.
Again, use the already present entries as a model.

Last modification you need to perform to this file is to add your <modulename> to
the LOCAL_STATIC_LIBRARIES list at the end of the deleyna-jni module section.

6) Modify TestNativeLibs/src/com/intel/dleyna/testnativelibs/Tests.java to add
the new unit test:

    public static native void soupSocketTest();
    ...
    SOUP_SOCKET_TEST("", new Impl() {
        public void exec() { soupSocketTest(); }
    }),

7) If the new unit test requires any resources on the device, add them to
TestNativeLibs/ResourceFiles and run InstallResourceFiles as described above.

Dleyna Demo App
---------------

Work in progress...