Tuesday, June 19, 2012

Android NDK Stable APIs

This is a mirror of official Google NDK documentation.
This is the list of stable APIs/ABIs exposed by the Android NDK.

I. Purpose:
-----------

Each API corresponds to a set of headers files, and a shared library file
that contains the corresponding implementation, and which must be linked
against by your native code.

For example, to use system library "Foo", you would include a header
like <foo.h> in your code, then tell the build system that your native
module needs to link to /system/lib/libfoo.so at load-time by adding
the following line to your Android.mk file:

  LOCAL_LDLIBS := -lfoo

Note that the build system automatically links the C library, the Math
library and the C++ support library to your native code, there is no
need to list them in a LOCAL_LDLIBS line.

There are several "API Levels" defined. Each API level corresponds to
a given Android system platform release. The following levels are
currently supported:

    android-3      -> Official Android 1.5 system images
    android-4      -> Official Android 1.6 system images
    android-5      -> Official Android 2.0 system images
    android-6      -> Official Android 2.0.1 system images
    android-7      -> Official Android 2.1 system images
    android-8      -> Official Android 2.2 system images
    android-9      -> Official Android 2.3 system images
    android-14     -> Official Android 4.0 system images

Note that android-6 and android-7 are the same as android-5 for the NDK,
i.e. they provide exactly the same native ABIs!

IMPORTANT:
    The headers corresponding to a given API level are now located
    under $NDK/platforms/android-<level>/arch-arm/usr/include


II. Android-3 Stable Native APIs:
---------------------------------

All the APIs listed below are available for developing native code that
runs on Android 1.5 system images and above.

The C Library:
--------------

The C library headers, as they are defined on Android 1.5 are available
through their standard names (<stdlib.h>, <stdio.h>, etc...). If one header
is not there at build time, it's because its implementation is not available
on a 1.5 system image.

The build system automatically links your native modules to the C library,
you don't need to add it to LOCAL_LDLIBS.

Note that the Android C library includes support for pthread (<pthread.h>),
so "LOCAL_LIBS := -lpthread" is not needed. The same is true for real-time
extensions (-lrt on typical Linux distributions).


** VERY IMPORTANT NOTE: ******************************************************
*
*  The kernel-specific headers in <linux/...> and <asm/...> are not considered
*  stable at this point. Avoid including them directly because some of them
*  are likely to change in future releases of the platform. This is especially
*  true for anything related to specific hardware definitions.
*
******************************************************************************


The Math Library:
-----------------

<math.h> is available, and the math library is automatically linked to your
native modules at build time, so there is no need to list "-lm" through
LOCAL_LDLIBS.



C++ Library:
------------

An *extremely* minimal C++ support API is available. For Android 1.5, this is
currently limited to the following headers:

   <cstddef>
   <new>
   <utility>
   <stl_pair.h>

They may not contain all definitions required by the standard. Notably,
support for C++ exceptions and RTTI is not available with Android 1.5 system
images.

The C++ support library (-lstdc++) is automatically linked to your native
modules too, so there is no need to list it through LOCAL_LDLIBS



Android-specific Log Support:
-----------------------------

<android/log.h> contains various definitions that can be used to send log
messages to the kernel from your native code. Please have a look at its
content in (build/platforms/android-3/common/include/android/log.h), which
contain many informative comments on how to use it.

You should be able to write helpful wrapper macros for your own usage to
access this facility.

If you use it, your native module should link to /system/lib/liblog.so with:

  LOCAL_LDLIBS := -llog


ZLib Compression Library:
-------------------------

<zlib.h> and <zconf.h> are available and can be used to use the ZLib
compression library. Documentation for it is at the ZLib page:

    http://www.zlib.net/manual.html

If you use it, your native module should link to /system/lib/libz.so with:

  LOCAL_LDLIBS := -lz


Dynamic Linker Library:
-----------------------

<dlfcn.h> is available and can be used to use the dlopen()/dlsym()/dlclose()
functions provided by the Android dynamic linker. You will need to link
against /system/lib/libdl.so with:

  LOCAL_LDLIBS := -ldl


III. Android-4 Stable Native APIs:
----------------------------------

All the APIs listed below are available for developing native code that runs
on Android 1.6 system images and above,


The OpenGL ES 1.x Library:
--------------------------

The standard OpenGL ES headers <GLES/gl.h> and <GLES/glext.h> contain the
declarations needed to perform OpenGL ES 1.x rendering calls from native
code.

If you use them, your native module should link to /system/lib/libGLESv1_CM.so
as in:

  LOCAL_LDLIBS := -lGLESv1_CM


The '1.x' here refers to both versions 1.0 and 1.1 of the OpenGL ES APIs.
Please note that:

  - OpenGL ES 1.0 is supported on *all* Android-based devices.
  - OpenGL ES 1.1 is fully supported only on specific devices that
    have the corresponding GPU.

This is because Android comes with a 1.0-capable software renderer that can
be used on GPU-less devices.

Developers should query the OpenGL ES version string and extension string
to know if the current device supports the features they need. See the
description of glGetString() in the specification to see how to do that:

    http://www.khronos.org/opengles/sdk/1.1/docs/man/glGetString.xml

Additionally, developers must put a <uses-feature> tag in their manifest
file to indicate which version of OpenGL ES their application requires. See
the documentation linked below for details:

 http://developer.android.com/guide/topics/manifest/uses-feature-element.html

Please note that EGL APIs are only available starting from API level 9. You
can however perform the corresponding operations (surface creation and flipping)
by using the VM. For example, with a GLSurfaceView as described here:

http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html

The "san-angeles" sample application shows how you can do that, while
rendering each frame in native code. This is a small Android port of the
excellent "San Angeles Observation" demo program. For more information about
it, see:

    http://jet.ro/visuals/san-angeles-observation/


IV. Android-5 Stable Native APIs:
----------------------------------

All the APIs listed below are available for developing native code that runs
on Android 2.0 system images and above.


The OpenGL ES 2.0 Library:
--------------------------

The standard OpenGL ES 2.0 headers <GLES2/gl2.h> and <GLES2/gl2ext.h> contain the
declarations needed to perform OpenGL ES 2.0 rendering calls from native code.
This includes the ability to define and use vertex and fragment shaders using the
GLSL language.

If you use them, your native module should link to /system/lib/libGLESv2.so
as in:

  LOCAL_LDLIBS := -lGLESv2

Not all devices support OpenGL ES 2.0, developers should thus query the
implementation's version and extension strings, and put a <uses-feature>
tag in their Android manifest. See Section III above for details.

Please note that EGL APIs are only available starting from API level 9.

The "hello-gl2" sample application demonstrate this. It is used to draw a very
simple triangle with the help of a vertex and fragment shaders.

IMPORTANT NOTE:
    The Android emulator does not support OpenGL ES 2.0 hardware emulation
    at this time. Running and testing code that uses this API requires a
    real device with such capabilities.


IV. Android-8 Stable Native APIs:
----------------------------------

All the APIs listed below are available for developing native code that runs
on Android 2.2 system images and above.


The 'jnigraphics' Library:
--------------------------

This is a tiny library that exposes a stable, C-based, interface that allows
native code to reliably access the pixel buffers of Java bitmap objects.

To use it, include the <android/bitmap.h> header in your source code, and
and link to the jnigraphics library as in:

  LOCAL_LDLIBS += -ljnigraphics

For details, read the source header at the following location:

    build/platforms/android-8/arch-arm/usr/include/android/bitmap.h

Briefly, typical usage should look like:

    1/ Use AndroidBitmap_getInfo() to retrieve information about a
       given bitmap handle from JNI (e.g. its width/height/pixel format)

    2/ Use AndroidBitmap_lockPixels() to lock the pixel buffer and
       retrieve a pointer to it. This ensures the pixels will not move
       until AndroidBitmap_unlockPixels() is called.

    3/ Modify the pixel buffer, according to its pixel format, width,
       stride, etc.., in native code.

    4/ Call AndroidBitmap_unlockPixels() to unlock the buffer.


V. Android-9 Stable Native APIs:
--------------------------------

All the APIs listed below are available for developing native code that runs
on Android > 2.3 system images and above.

The EGL graphics library:
-------------------------

EGL provides a native platform interface to allocate and manage OpenGLES
surfaces. For more information about its features, please see:

    http://www.khronos.org/egl

In a nutshell, this will allow you to do the following directly from
native code:

    - List supported EGL configurations
    - Allocate and release OpenGLES surfaces
    - Swap/Flip surfaces for display  (eglSwapBuffers)

This is provided through the following headers:

    <EGL/egl.h>        -> Main EGL API definitions
    <EGL/eglext.h>     -> EGL extension-related definitions

You cal link against the system's EGL library by adding the following
to your NDK module definition:

    LOCAL_LDLIBS += -lEGL


The OpenSL ES native audio Library:
-----------------------------------

Android native audio is based on Khronos Group OpenSL ES™ 1.0.1.

The standard OpenSL ES headers <SLES/OpenSLES.h> and <SLES/OpenSLES_Platform.h>
contain the declarations needed to perform audio input and output from the
native side of Android.

NOTE: Despite the fact that the OpenSL ES 1.0.1 specification uses
      <OpenSLES.h> to include these headers, Khronos has modified later versions of
      the document to recommend <SLES/OpenSLES.h> instead, hence the later
      approach was adopted for Android.

This API level also provides Android-specific extensions, see the content
of <SLES/OpenSLES_Android.h> and <SLES/OpenSLES_AndroidConfiguration.h> for
details.

The system library named "libOpenSLES.so" implements the public native audio
functions. Use the following to link your modules against it:

    LOCAL_LDLIBS += -lOpenSLES

For more information about this topic, please read the document docs/opensles/index.html.


The Android native application APIs:
------------------------------------

Starting from API level 9, it is possible to entirely write an Android
application with native code (i.e. without any Java). That does not mean
that your code does not run inside a VM though, and most of the features
of the platform will still need to be accessed through JNI.

For more information about this topic, please read the dedicated
document named docs/NATIVE-ACTIVITY.html (TODO: WRITE DOC).

The following headers correspond to these new native APIs (see comments
inside them for more details):

  <android/native_activity.h>

        Activity lifecycle management (and general entry point)

  <android/looper.h>
  <android/input.h>
  <android/keycodes.h>
  <android/sensor.h>

        To Listen to input events and sensors directly from native code.

  <android/rect.h>
  <android/window.h>
  <android/native_window.h>
  <android/native_window_jni.h>

        Window management, including the ability to lock/unlock the pixel
        buffer to draw directly into it.

  <android/configuration.h>
  <android/asset_manager.h>
  <android/storage_manager.h>
  <android/obb.h>
        Direct (read-only) access to assets embedded in your .apk. or
        the Opaque Binary Blob (OBB) files, a new feature of Android X.X
        that allows one to distribute large amount of application data
        outside of the .apk (useful for game assets, for example).

All the corresponding functions are provided by the "libandroid.so" library
version that comes with API level 9. To use it, use the following:

    LOCAL_LDLIBS += -landroid


VI. Android-14 Stable Native APIs:
----------------------------------

All the APIs listed below are available for developing native code that runs
on Android > 4.0 system images and above.

The OpenMAX AL native multimedia library:
-----------------------------------------

Android native multimedia is based on Khronos Group OpenMAX AL™ 1.0.1.

The standard OpenMAX AL headers <OMXAL/OpenMAXAL.h> and <OMXAL/OpenMAXAL_Platform.h>
contain the declarations needed to perform multimedia output from the
native side of Android.

NOTE: Despite the fact that the OpenMAX AL 1.0.1 specification uses
      <OpenMAXAL.h> to include these headers, Khronos has modified later versions of
      the document to recommend <OMXAL/OpenMAXAL.h> instead, hence the later
      approach was adopted for Android.

This API level also provides Android-specific extensions, see the content
of <OMXAL/OpenMAXAL_Android.h> for details.

The system library named "libOpenMAXAL.so" implements the public native multimedia
functions. Use the following to link your modules against it:

    LOCAL_LDLIBS += -lOpenMAXAL

For more information about this topic, please read the document docs/openmaxal/index.html.


The OpenSL ES native audio library:
-----------------------------------

Native audio APIs based on OpenSL ES were added in API level 9.
Starting with API level 14, the native audio API was extended to support
decoding to PCM.  See section "The OpenSL ES native audio Library"
above for a high-level summary of how to use OpenSL ES, and the details
in docs/opensles/index.html.

NDK Development

This is a mirror of official Google NDK documentation.
This document describes how one can modify the NDK and generate
new experimental release packages for it.

I. Getting the sources:
=======================

The sources live under the "ndk" and "development/ndk" directories in
the Android source tree:

  - "ndk" contains the main build scripts and documentation
  - "development/ndk" contains platform-specific headers and samples

If you have downloaded the full Android source tree through the "repo"
tool, you can start directly there. Otherwise, you can just get these
two repositories with the following:

  mkdir workdir
  cd workdir
  git clone https://android.googlesource.com/platform/ndk.git ndk
  git clone https://android.googlesource.com/platform/development.git development
  export NDK=`pwd`/ndk


II. Building the platforms tree:
================================

You need to do that once if you want to use the content of $NDK to build
samples, tests or anything else:

  $NDK/build/tools/build-platforms.sh

What the script does is populate the $NDK/platforms and $NDK/samples
directories from the content of development/ndk.

What is under development/ndk is segregated by API level. This makes it
easier to add a new platform to the tree, but is not well-suited to building
stuff. The build-platforms.sh script will gather all files appropriately
and place the result inside $NDK/platforms and $NDK/samples.

Note: These directories are listed by $NDK/.gitignore, so they won't appear
      on your git status. You can remove them if you want by running:

        $NDK/build/tools/dev-cleanup.sh

      which also removes all intermediate files and directories from $NDK.


III. Prebuilt binaries:
=======================

The NDK requires several prebuilt binary executables to work properly, these
include the following:

  - toolchain binaries for the cross-compiler and associated tools
  - gdbserver binaries required for native debugging

These are not provided in the NDK's git repositories. However, there are
several ways to get them:

  1/ From a previous NDK release package:

      By far the easiest thing to do is to copy the binaries from a previous
      NDK installation. You can do that with a command like the following one:

            cp -r $PREVIOUS_NDK/toolchains/* $NDK/toolchains/

      NOTE: The binaries are listed in $NDK/.gitignore and will not appear
            in your git status.


  2/ Download and rebuild directly from the internet:

      IMPORTANT: This is *very* long.

      The NDK comes with several scripts that can be used to rebuild the
      binaries from scratch, after downloading their sources from
      android.googlesource.com.

      There are several ways to do that, the most naive one, which will
      always work but will be *very* long (expect a few hours on a typical
      dual-core machine) is to do the following:

        $NDK/build/tools/rebuild-all-prebuilt.sh

      This will perform all the steps required to rebuild the binaries,
      which include:

        - downloading the sources from android.googlesource.com
        - patching them with appropriate changes, if needed
        - rebuilding everything from scratch
        - copying the generated binaries to the proper location under $NDK

      You will need about 30G of free space in your /tmp directory to be
      able to do that, and *plenty* of free time.

      IMPORTANT: If you plan to generate NDK release packages, even
      experimental ones, we strongly suggest you to use the individual
      steps described in 3/ below.

      IMPORTANT:
          Since NDK r5, Windows binaries can be built on Linux by using the
          --mingw option, which requires that you have the "mingw32" package
          installed on your system. For example:

              $NDK/build/tools/rebuild-all-prebuilt.sh --mingw

          We do not officially support building these binaries directly on
          Windows (either through Cygwin or MSys) anymore, due to the vast
          number of problems these environments create when trying to do so.



  3/ Download, rebuild, package, install in separate steps:

      If you plan to generate your own NDK release packages, it is better
      to rebuild your binaries using separate steps, as in:

         - Download the sources from the Internet, patch them, then
           package the result in a simple tarball.

         - For every target system (linux-x86, darwin-x86 and windows),
           rebuild the binaries from the same source tarball.

         - Package and collect all prebuilt binaries into a single
           directory that will be used when packaging NDK releases.

      Here are more details on how to do that:

      3.a/ Download + patching + packaging sources:

        Use the following command to download, patch and package the
        sources:

           $NDK/build/tools/download-toolchain-sources.sh --package

        This will create a large tarball containing all sources ready to be
        used by the following step. The generated file path will be dumped at
        the script when it completes its operation and should be something
        like:

          /tmp/android-ndk-toolchain-<date>.tar.bz2

        Note that if you don't use the --package option, you will need to
        provide the name of a directory where the patched sources will be
        copied instead, as in:

            $NDK/build/tools/download-toolchain-sources.sh <target-src-dir>


       3.b/ Build the binaries:

        Use the following command to rebuild the binaries from the source
        tarball that was created in the previous section with the --package
        option:

            $NDK/build/tools/rebuild-all-prebuilt.sh --toolchain-pkg=<file>

        Where <file> points to the package generated by the
        download-toolchain-sources.sh script.

        In the case where you downloaded the sources to a directory instead,
        use the --toolchain-src-dir option instead, as with:

            $NDK/build/tools/rebuild-all-prebuilt.sh --toolchain-src-dir=<path>

        This will rebuild all the prebuilt binaries for your host platforms
        and place them in a directory named:

             /tmp/ndk-prebuilt/prebuilt-<date>/

        These binary packages include the following:

            - host-specific toolchain binaries. e.g.
                arm-eabi-4.4.0-linux-x86.tar.bz2

            - toolchain specific device binaries, e.g.
                arm-eabi-4.4.0-gdbserver.tar.bz2

        IMPORTANT:
            To generate Windows binaries on Windows, install the "mingw32"
            package on your system, then use the --mingw option, as in:

               $NDK/build/tools/rebuild-all-prebuilt.sh --mingw --toolchain-pkg=<file>

            Note that device-specific binaries (e.g. gdbserver) cannot be
            rebuilt with this option.

       3.c/ Copy the binaries to your NDK tree:

        Simply go to your NDK tree, and unpack the binary tarballs in place,
        for example:

            cd $NDK
            tar xjf <path>/*.tar.bz2

        Where <path> is a directory containing all the tarballs (e.g. it
        could be simply /tmp/ndk-prebuilt/prebuilt-<date>)

        This will put the corresponding files at the correct location.


       3.c/

      It is a good idea to save the generated toolchain binaries into
      an archive. To do that, use the --package option, as in:

        $NDK/build/tools/rebuild-all-prebuilt.sh --package

      This will generate a package file containing all the prebuilts, that
      can be unpacked directly into your $NDK directory. The package name is
      printed at the end, e.g."android-ndk-prebuild-<date>-<system>.tar.bz2".

      Where <date> is the current date, and <system> is your system name.
      Then, to unpack:

        cd $NDK                               k
        tar xjf /tmp/android-ndk-prebuilt-<date>-<system>.tar.bz2


      The generated package can easily be shared with other people.


IV. Generate new package releases:
==================================

You can generate new experimental NDK release packages once you're satisfied
with your changes, in order to share them with other people. There are two
ways to do that:

  1/ Using the 'make-release.sh' script:

    The simplest, and also the slowest way, to generate a new NDK release
    is to invoke this script, with:

        $NDK/build/tools/make-release.sh

    NOTE: THIS WILL BE VERY VERY LONG. The script will do all the steps
          described in section III *from* scratch, and this can take several
          hours on a dual-core machine.

    You should only use it in case of desperation, or if you don't want
    to deal with all the details exposed in section III or below.


  1/ Using a previous NDK release package:

    This is the second simplest way to generate a new package, and it will
    be extremely quick because it will pick the prebuilt binaries directly
    from the previous package.

    Do the following:

        cd $NDK
        build/tools/package-release.sh --prebuilt-ndk=<file>

    Where <file> points to a previous NDK package (i.e. archive file).

    NOTE: This method can only be used to generate a single release package
          for the current host system.

  2/ Using prebuilt tarballs:

    If you have generated prebuilt binary tarballs with the steps described
    in section III.3 above, you can use these to generate release packages
    as well.

    Assuming that you have collected prebuilt tarballs for all three supported
    host systems (i.e. linux-x86, darwin-x86 and windows) under a directory,
    do the following:

        cd $NDK
        build/tools/package-release.sh --prebuilt-dir=<path>

    The generated NDK package release will have a name that looks like:

        /tmp/ndk-release/android-ndk-<release>-<system>.zip

    Where <release> is by default the current date in ISO format
    (e.g. 20100915), and <system> corresponds to the host system where the
    NDK release is supposed to run.

    The script 'package-release.sh' provides a few additional options:

        --release=<name>       Change the name of the release

        --systems=<list>       Change the list of host systems to package for

        --platforms=<list>     List of API levels to package in the NDK

        --out-dir=<path>       Specify a different output directory for the
                               final packages (instead of /tmp/ndk-release)

    Use --help to list them all.

Android NDK How-To

This is a mirror of official Google NDK documentation.
A collection of tips and tricks for NDK users


How to force the display of build commands:
-------------------------------------------

Do "ndk-build V=1" and actual build commands will be
displayed. This can be used to verify that things are compiled
as you expect them to, and check for bugs in the NDK build system.

(The V=1 trick comes from the Linux kernel build system)


How to force a rebuild of all your sources:
-------------------------------------------

Use GNU Make's "-B" option, as in:

   ndk-build -B


How to store your native sources in a location other than $PROJECT/jni:
-----------------------------------------------------------------------

First, you can simply tell your $PROJECT/jni/Android.mk to include
another Android.mk that are located in different places.

Alternatively, you can define APP_BUILD_SCRIPT in your Application.mk
to point to an alternative Android.mk file.


How to build a project's native files without cd-ing to it:
-----------------------------------------------------------

Sometimes, you may need to rebuild a project's native file without
being able to cd to its top-level path from the command-line. This
is do-able by using the GNU-Make '-C <path>' option, as in:

    ndk-build -C <project-path>


How to store your Application.mk in a location other than $PROJECT/jni:
-----------------------------------------------------------------------

Starting with NDK r4, you can simply place the file under $PROJECT/jni/
and launch the 'ndk-build' script from your project tree.

If you want to use 'ndk-build' but place the file to a different location,
use a GNU Make variable override as:

    ndk-build NDK_APPLICATION_MK=/path/to/your/Application.mk

If you're using the legacy $NDK/apps/<name> build method, you can create
a symbolic link to your final Application.mk there. For example, imagine
that you wrote:

  $PROJECT/foo/Application.mk

You can create a symlink like with a command like:

  ln -s $PROJECT/foo  $NDK/apps/<name>

This will make $NDK/apps/<name>/Application.mk point directly to
$PROJECT/jni/Application.mk

Note that generated files will still go under $NDK/out/apps/<name> though.

Windows users: The NDK is only supported on Cygwin, which implements
symbolic links through the "ln -s" command, as in:

    ln -s  <target>  <link>


How to properly add include directories to your module declaration:
-------------------------------------------------------------------

If you define several modules, it is common to need to include one
module's header while compiling another one. For example, consider
the following example:

  $PROJECT/jni/foo/
    Android.mk
    foo.h
    foo.c

  $PROJECT/jni/bar/
    Android.mk
    bar.c

Where the 'bar.c' uses '#include <foo.h>'. You will need to add the
path to the 'foo' module in jni/bar/Android.mk to build it properly.

One is tempted to use the following:

  LOCAL_C_INCLUDES := ../foo

However this will not work because all compilation happens from the
directory where 'ndk-build' is invoked, and include files must be
relative to it.

The correct line is instead:

  LOCAL_C_INCLUDES := $(LOCAL_PATH)/../foo

Which uses a path relative to $(LOCAL_PATH), in the case where you would
need to move 'foo' and 'bar' to a deeper level in the 'sources' hierarchy.

In case you absolutely need it, you can also use NDK_APP_PROJECT_PATH to
point to your project directory:

  LOCAL_C_INCLUDES := $(NDK_APP_PROJECT_PATH)/jni/foo

However, we don't recommend using this, paths relative to $(LOCAL_PATH)
being better.

Android NDK Overview

This is a mirror of official Google NDK documentation.
Introduction:

The Android NDK is a set of tools that allows Android application developers
to embed native machine code compiled from C and/or C++ source files into
their application packages.

IMPORTANT:
  The Android NDK can only be used to target Android system images
  running Cupcake (a.k.a 1.5) or later versions of the platform.

  1.0 and 1.1 system images are specifically *not* supported due to
  subtle ABI and toolchain changes that happened for the 1.5 release.


I. Android NDK Goals:
---------------------

The Android VM allows your application's source code to call methods
implemented in native code through the JNI. In a nutshell, this means that:

  - Your application's source code will declare one or more methods
    with the 'native' keyword to indicate that they are implemented through
    native code. E.g.:

      native byte[]  loadFile(String  filePath);

  - You must provide a native shared library that contains the
    implementation of these methods, which will be packaged into your
    application's .apk. This library must be named according to standard
    Unix conventions as lib<something>.so, and shall contain a standard JNI
    entry point (more on this later). For example:

      libFileLoader.so

  - Your application must explicitly load the library. For example, to load
    it at application start-up, simply add the following to its source code:

      static {
        System.loadLibrary("FileLoader");
      }

    Note that you should not use the 'lib' prefix and '.so' suffix here.


The Android NDK is a complement to the Android SDK that helps you to:

  - Generate JNI-compatible shared libraries that can run on the Android
    1.5 platform (and later) running on ARM CPUs.

  - Copy the generated shared libraries to a proper location of your
    application project path, so they will be automatically added to your
    final (and signed) .apks

  - In later revisions of the NDK, we intend to provide tools that help
    debug your native code through a remote gdb connection and as much
    source/symbol information as possible.

Moreover, the Android NDK provides:

  - A set of cross-toolchains (compilers, linkers, etc..) that can
    generate native ARM binaries on Linux, OS X and Windows (with Cygwin)

  - A set of system headers corresponding to the list of stable native APIs
    supported by the Android platform. This corresponds to definitions that
    are guaranteed to be supported in all later releases of the platform.

    They are documented in the file docs/STABLE-APIS.html

    IMPORTANT:
    Keep in mind that most of the native system libraries in Android system
    images are not frozen and might changed drastically, or even deleted,
    in later updates and releases of the platform.

  - A build system that allow developers to only write very short build files
    to describe which sources need to be compiled, and how. The build system
    deals with all the hairy toolchain/platform/CPU/ABI specifics. Moreover,
    later updates of the NDK can add support for more toolchains, platforms,
    system interfaces without requiring changes in the developer's build
    files (more on this later).


II. Android NDK Non-Goals:
--------------------------

The NDK is *not* a good way to write generic native code that runs on Android
devices. In particular, your applications should still be written in the Java
programming language, handle Android system events appropriately to avoid the
"Application Not Responding" dialog or deal with the Android application
life-cycle.

Note however that is is possible to write a sophisticated application in
native code with a small "application wrapper" used to start/stop it
appropriately.

A good understanding of JNI is highly recommended, since many operations
in this environment require specific actions from the developers, that are
not necessarily common in typical native code. These include:

  - Not being able to directly access the content of VM objects through
    direct native pointers. E.g. you cannot safely get a pointer to a
    String object's 16-bit char array to iterate over it in a loop.

  - Requiring explicit reference management when the native code wants to
    keep handles to VM objects between JNI calls.


The NDK only provides system headers for a very limited set of native
APIs and libraries supported by the Android platform. While a typical
Android system image includes many native shared libraries, these should
be considered an implementation detail that might change drastically between
updates and releases of the platform.

If an Android system library is not explicitly supported by the NDK
headers, then applications should not depend on it being available, or
they risk breaking after the next over-the-air system update on various
devices.

Selected system libraries will gradually be added to the set of stable NDK
APIs.


III. NDK development in practice:
---------------------------------

Here's a very rough overview of how you can develop native code with the
Android NDK:

  1/ Place your native sources under $PROJECT/jni/...

  2/ Write $PROJECT/jni/Android.mk to describe your sources
     to the NDK build system

  3/ Optional: write $PROJECT/jni/Application.mk to describe your
     project in more details to the build system. You don't need
     one to get started though, but this allows you to target
     more than one CPU or override compiler/linker flags
     (see docs/APPLICATION-MK.html for all details).

  4/ Build your native code by running "$NDK/ndk-build" from your
     project directory, or any of its sub-directories.

The last step will copy, in case of success, the stripped shared libraries
your application needs to your application's root project directory. You
will then need to generate your final .apk through the usual means.

Now, for a few more details:


III.1/ Configuring the NDK:
- - - - - - - - - - - - - -

Previous releases required that you run the 'build/host-setup.sh'
script to configure your NDK. This step has been removed completely
in release 4 (a.k.a. NDK r4).


III.2/ Placing C and C++ sources:
- - - - - - - - - - - - - - - - -

Place your native sources under the following directory:

    $PROJECT/jni/

Where $PROJECT corresponds to the path of your Android application
project.

You are pretty free to organize the content of 'jni' as you want,
the directory names and structure here will not influence the final
generated application packages, so you don't have to use pseudo-unique
names like com.<mycompany>.<myproject> as is the case for application
package names.

Note that C and C++ sources are supported. The default C++ file extensions
supported by the NDK is '.cpp', but other extensions can be handled as well
(see docs/ANDROID-MK.html for details).

It is possible to store your sources in a different location by adjusting
your Android.mk file (see below).


III.3/ Writing an Android.mk build script:
- - - - - - - - - - - - - - - - - - - - - -

An Android.mk file is a small build script that you write to describe your
sources to the NDK build system. Its syntax is described in details in
the file docs/ANDROID-MK.html.

In a nutshell, the NDK groups your sources into "modules", where each module
can be one of the following:

  - a static library
  - a shared library

You can define several modules in a single Android.mk, or you can write
several Android.mk files, each one defining a single module.

Note that a single Android.mk might be parsed several times by the build
system so don't assume that certain variables are not defined in them.
By default, the NDK will look for the following build script:

   $PROJECT/jni/Android.mk

If you want to define Android.mk files in sub-directories, you should
include them explicitly in your top-level Android.mk. There is even
a helper function to do that, i.e. use:

   include $(call all-subdir-makefiles)

This will include all Android.mk files in sub-directories of the current
build file's path.


III.4/ Writing an Application.mk build file (optional):
- - - - - - - - - - - - - - - - - - - - - - - - - - - -

While an Android.mk file describes your modules to the build system, the
Application.mk file describes your application itself. See the
docs/APPLICATION-MK.html document to understand what this file allows you
to do. This includes, among others:

   - The exact list of modules required by your application.

   - The CPU architecture(s) to generate machine code for.

  - Optional information, like whether you want a release or debug
    build, specific C or C++ compiler flags and others that should
    apply to all modules being built.

This file is optional: by default the NDK will provide one that simply
builds *all* the modules listed from your Android.mk (and all the makefiles
it includes) and target the default CPU ABI (armeabi).

There are two ways to use an Application.mk:

  - Place it under $PROJECT/jni/Application.mk, and it will be picked
    up automatically by the 'ndk-build' script (more on this later)

  - Place it under $NDK/apps/<name>/Application.mk, where $NDK
    points to your NDK installation path. After that, launch
    "make APP=<name>" from the NDK directory.

    This was the way this file was used before Android NDK r4.
    It is still supported for compatibility reasons, but we strongly
    encourage you to use the first method instead, since it is much
    simpler and doesn't need modifying / changing directories of the
    NDK installation tree.

Again, see docs/APPLICATION-MK.html for a complete description of its
content.


III.5/ Invoke the NDK build system:
- - - - - - - - - - - - - - - - - -

The preferred way to build machine code with the NDK is to use the
'ndk-build' script introduced with Android NDK r4. You can also use
a second, legacy, method that depends on creating a '$NDK/apps' subdirectory.

In both cases, a successful build will copy the final stripped binary modules
(i.e. shared libraries) required by your application to your application's
project path (Note that unstripped versions are kept for debugging
purposes, there is no need to copy unstripped binaries to a device).


  1: Using the 'ndk-build' command:
  ---------------------------------

  The 'ndk-build' script, located at the top of the NDK installation path
  can be invoked directly from your application project directory (i.e. the
  one where your AndroidManifest.xml is located) or any of its sub-directories.
  For example:

    cd $PROJECT
    $NDK/ndk-build

  This will launch the NDK build scripts, which will automatically probe your
  development system and application project file to determine what to build.

  For example:

    ndk-build
    ndk-build  clean    --> clean generated binaries
    ndk-build  -B V=1   --> force complete rebuild, showing commands

  By default, it expects an optional file under $PROJECT/jni/Application.mk,
  and a required $PROJECT/jni/Android.mk.

  On success, this will copy the generated binary modules (i.e. shared
  libraries) to the appropriate location in your project tree. You can later
  rebuild the full Android application package either through the usual
  'ant' command, or the ADT Eclipse plug-in.

  See docs/NDK-BUILD.html for a more complete description of what this script
  does and which options it can take.


III.6/ Specifying custom output directories:
- - - - - - - - - - - - - - - - - - - - - - -

By default, ndk-build places all intermediate generated files under
$PROJECT/obj. You can however select a different location by defining
the NDK_OUT environment variable to point to a different directory.

When defined, this variable has two effects:

  1/ It ensures that all files that normally go under $PROJECT/obj are
     stored in $NDK_OUT instead

  2/ It tells ndk-gdb to look into $NDK_OUT, instead of $PROJECT/obj for
     any symbolized (i.e. unstripped) versions of the generated binaries.


IV. Rebuild your application package:
- - - - - - - - - - - - - - - - - - -

After generating the binaries with the NDK, you need to rebuild your
Android application package files (.apk) using the normal means, i.e.
either using the 'ant' command or the ADT Eclipse plug-in.

See the Android SDK documentation for more details. The new .apk will
embed your shared libraries, and they will be extracted automatically
at installation time by the system when you install the package on a
target device.


V. Debugging support:
- - - - - - - - - - -

The NDK provides a helper script, named 'ndk-gdb' to very easily launch
a native debugging session of your applications.

Native debugging can *ONLY* be performed on production devices running
Android 2.2 or higher, and does not require root or privileged access, as
long as your application is debuggable.

For more information, read docs/NDK-GDB.html. In a nutshell, native debugging
follows this simple scheme:

   1. Ensure your application is debuggable (e.g. set android:debuggable
      to "true" in your AndroidManifest.xml)

   2. Build your application with 'ndk-build', then install it on your
      device/emulator.

   3. Launch your application.

   4. Run 'ndk-gdb' from your application project directory.

You will get a gdb prompt. See the GDB User Manual for a list of useful
commands.

Android Native CPU ABI Management

This is a mirror of official Google NDK documentation.
Introduction:
=============

Every piece of native code generated with the Android NDK matches a given
"Application Binary Interface" (ABI) that defines exactly how your
application's machine code is expected to interact with the system at
runtime.

A typical ABI describes things in *excruciating* details, and will typically
include the following information:

  - the CPU instruction set that the machine code should use

  - the endianness of memory stores and loads at runtime

  - the format of executable binaries (shared libraries, programs, etc...)
    and what type of content is allowed/supported in them.

  - various conventions used to pass data between your code and
    the system (e.g. how registers and/or the stack are used when functions
    are called, alignment constraints, etc...)

  - alignment and size constraints for enum types, structure fields and
    arrays.

  - the list of function symbols available to your machine code at runtime,
    generally from a very specific selected set of libraries.

This document lists the exact ABIs supported by the Android NDK and the
official Android platform releases.


I. Supported ABIs:
==================

Each supported ABI is identified by a unique name.


 I.1. 'armeabi'
 --------------

  This is the name of an ABI for ARM-based CPUs that support *at* *least*
  the ARMv5TE instruction set. Please refer to following documentation for
  more details:

   - ARM Architecture Reference manual                (a.k.a  ARMARM)
   - Procedure Call Standard for the ARM Architecture (a.k.a. AAPCS)
   - ELF for the ARM Architecture                     (a.k.a. ARMELF)
   - ABI for the ARM Architecture                     (a.k.a. BSABI)
   - Base Platform ABI for the ARM Architecture       (a.k.a. BPABI)
   - C Library ABI for the ARM Architecture           (a.k.a. CLIABI)
   - C++ ABI for the ARM Architecture                 (a.k.a. CPPABI)
   - Runtime ABI for the ARM Architecture             (a.k.a. RTABI)

   - ELF System V Application Binary Interface
     (DRAFT - 24 April 2001)

   - Generic C++ ABI  (http://www.codesourcery.com/public/cxx-abi/abi.html)

  Note that the AAPCS standard defines 'EABI' as a moniker used to specify
  a _family_ of similar but distinct ABIs. Android follows the little-endian
  ARM GNU/Linux ABI as documented in the following document:

      http://www.codesourcery.com/gnu_toolchains/arm/arm_gnu_linux_abi.pdf

  With the exception that wchar_t is only one byte. This should not matter
  in practice since wchar_t is simply *not* really supported by the Android
  platform anyway.

  This ABI does *not* support hardware-assisted floating point computations.
  Instead, all FP operations are performed through software helper functions
  that come from the compiler's libgcc.a static library.

  Thumb (a.k.a. Thumb-1) instructions are supported. Note that the NDK
  will generate thumb code by default, unless you define LOCAL_ARM_MODE
  in your Android.mk (see docs/ANDROID-MK.html for all details).


 I.2. 'armeabi-v7a'
 ------------------

  This is the name of another ARM-based CPU ABI that *extends* 'armeabi' to
  include a few CPU instruction set extensions as described in the following
  document:

  - ARM Architecture v7-a Reference Manual

  The instruction extensions supported by this Android-specific ABI are:

     - The Thumb-2 instruction set extension.
     - The VFP hardware FPU instructions.

  More specifically, VFPv3-D16 is being used, which corresponds to 16
  dedicated 64-bit floating point registers provided by the CPU.

  Other extensions described by the v7-a ARM like Advanced SIMD (a.k.a. NEON),
  VFPv3-D32 or ThumbEE are optional to this ABI, which means that developers
  should check *at* *runtime* whether the extensions are available and provide
  alternative code paths if this is not the case.

  (Just like one typically does on x86 systems to check/use MMX/SSE2/etc...
   specialized instructions).

  You can check docs/CPU-FEATURES.html to see how to perform these runtime
  checks, and docs/CPU-ARM-NEON.html to learn about the NDK's support for
  building NEON-capable machine code too.

  IMPORTANT NOTE: This ABI enforces that all double values are passed during
  function calls in 'core' register pairs, instead of dedicated FP ones.
  However, all internal computations can be performed with the FP registers
  and will be greatly sped up.

  This little constraint, while resulting in a slight decrease of
  performance, ensures binary compatibility with all existing 'armeabi'
  binaries.

  IMPORTANT NOTE: The 'armeabi-v7a' machine code will *not* run on ARMv5 or
                  ARMv6 based devices.


 I.3. 'x86'
 ----------

  This is the name of an ABI for CPUs supporting the instruction set
  commonly named 'x86' or 'IA-32'. More specifically, this ABI corresponds
  to the following:

  - instructions normally generated by GCC with the following compiler
    flags:

      -march=i686 -msse3 -mstackrealign -mfpmath=sse

    which targets Pentium Pro instruction set, according to the GCC
    documentation, plus the MMX, SSE, SSE2 and SSE3 instruction set
    extensions.

  - using the standard Linux x86 32-bit calling convention (e.g. section 6,
    "Register Usage" of the "Calling conventions..." document below), not
    the SVR4 one.

  The ABI does *not* include any other optional IA-32 instruction set
  extension, including, but not limited to:

  - the MOVBE instruction
  - the SSSE3 "supplemental SSE3" extension
  - any variant of "SSE4"

  You can still use these, as long as you use runtime feature probing to
  enable them, and provide fallbacks for devices that do not support them.

  Please refer to the following documents for more details:

    http://gcc.gnu.org/onlinedocs/gcc/i386-and-x86_002d64-Options.html

    Calling conventions for different C++ compilers and operating systems
      http://www.agner.org/optimize/calling_conventions.pdf

    Intel IA-32 Intel Architecture Software Developer's Manual
      volume 2: Instruction Set Reference

    Intel IA-32 Intel Architecture Software Developer's Manual
      volume 3: System Programming

    Amendment to System V Application Binary Interface
      Intel386 Processor Architecture Supplement


 I.4. 'mips'
 -----------

  This is the name of an ABI for MIPS-based CPUs that support *at* *least*
  the MIPS32r1 instruction set. The ABI includes the following features:

   - MIPS32 revision 1 ISA
   - Little-Endian
   - O32
   - Hard-Float
   - no DSP application specific extensions

  Please refer to following documentation for more details:

   - ELF for the MIPS Architecture                    (a.k.a. MIPSELF)
   - FAQ for MIPS Toolchains                          (a.k.a. MIPSFAQ)
   - Toolchain Specifics                              (a.k.a. MIPSTOOL)
   - SDE Library                                      (a.k.a. MIPSSDE)
   - Instruction Set Quick Reference                  (a.k.a. MIPSISA)
   - Architecture for Programmers                     (a.k.a. MIPSARCH)

   - ELF System V Application Binary Interface
     (DRAFT - 24 April 2001)
   - Generic C++ ABI  (http://sourcery.mentor.com/public/cxx-abi/abi.html)

  The MIPS specific documentation is available at:
  http://www.mips.com/products/product-materials/processor/mips-architecture/
  https://sourcery.mentor.com/sgpp/lite/mips/portal/target_arch?@action=faq&target_arch=MIPS

  Note: This ABI assumes a CPU:FPU clock ratio of 2:1 for maximum
  compatability.

  Note: that MIPS16 support is not provided, nor is micromips.


II. Generating code for a specific ABI:
=======================================

By default, the NDK will generate machine code for the 'armeabi' ABI.
You can however add the following line to your Application.mk to generate
ARMv7-a compatible machine code instead:

   APP_ABI := armeabi-v7a

It is also possible to build machine code for *two* distinct ABIs by using:

   APP_ABI := armeabi armeabi-v7a

This will instruct the NDK to build two versions of your machine code: one for
each ABI listed on this line. Both libraries will be copied to your application
project path and will be ultimately packaged into your .apk.

Such a package is called a "fat binary" in Android speak since it contains
machine code for more than one CPU architecture. At installation time, the
package manager will only unpack the most appropriate machine code for the
target device. See below for details.



III. ABI Management on the Android platform:
============================================

This section provides specific details about how the Android platform manages
native code in application packages.


  III.1. Native code in Application Packages:
  -------------------------------------------

    It is expected that shared libraries generated with the NDK are stored in
    the final application package (.apk) at locations of the form:

       lib/<abi>/lib<name>.so

    Where <abi> is one of the ABI names listed in section II above, and <name>
    is a name that can be used when loading the shared library from the VM
    as in:

        System.loadLibrary("<name>");

    Since .apk files are just zip files, you can trivially list their content
    with a command like:

        unzip -l <apk>

    to verify that the native shared libraries you want are indeed at the
    proper location. You can also place native shared libraries at other
    locations within the .apk, but they will be ignored by the system, or more
    precisely by the steps described below; you will need to extract/install
    them manually in your application.

    In the case of a "fat" binary, up to four distinct libraries can be placed
    in the  .apk, for example at:

        lib/armeabi/libfoo.so
        lib/armeabi-v7a/libfoo.so
        lib/x86/libfoo.so
        lib/mips/libfoo.so


  III.2. Android Platform ABI support:
  ------------------------------------

    The Android system knows at runtime which ABI(s) it supports. More
    precisely, up to two build-specific system properties are used to
    indicate:

    - the 'primary' ABI for the device, corresponding to the machine
      code used in the system image itself.

    - an optional 'secondary' ABI, corresponding to another ABI that
      is also supported by the system image.

    For example, a typical ARMv5TE-based device would only define
    the primary ABI as 'armeabi' and not define a secondary one.

    On the other hand, a typical ARMv7-based device would define the
    primary ABI to 'armeabi-v7a' and the secondary one to 'armeabi'
    since it can run application native binaries generated for both
    of them.

    A typical x86-based device only defines a primary abi named 'x86'.

    A typical MIPS-based device only defines a primary abi named 'mips'.

  III.3. Automatic extraction of native code at install time:
  -----------------------------------------------------------

    When installing an application, the package manager service will scan
    the .apk and look for any shared library of the form:

         lib/<primary-abi>/lib<name>.so

    If one is found, then it is copied under $APPDIR/lib/lib<name>.so,
    where $APPDIR corresponds to the application's specific data directory.

    If none is found, and a secondary ABI is defined, the service will
    then scan for shared libraries of the form:

        lib/<secondary-abi>/lib<name>.so

    If anything is found, then it is copied under $APPDIR/lib/lib<name>.so

    This mechanism ensures that the best machine code for the target
    device is automatically extracted from the package at installation
    time.

C++ support with the Android NDK

This is a mirror of official Google NDK documentation.
The Android platform provides a very minimal C++ runtime support library
(/system/lib/libstdc++) and corresponding headers for it in the NDK.

By default, this 'system' runtime does *not* provide the following:

  - Standard C++ Library support (except a few trivial headers).
  - C++ exceptions support
  - RTTI support

However, the NDK provides various "helper C++ runtimes" which can provide them,
or a subset of these features.

To select the runtime you want to use, define APP_STL inside your
Application.mk to one of the following values:

    system          -> Use the default minimal system C++ runtime library.
    gabi++_static   -> Use the GAbi++ runtime as a static library.
    gabi++_shared   -> Use the GAbi++ runtime as a shared library.
    stlport_static  -> Use the STLport runtime as a static library.
    stlport_shared  -> Use the STLport runtime as a shared library.
    gnustl_static   -> Use the GNU STL as a static library.
    gnustl_shared   -> Use the GNU STL as a shared library.

The 'system' runtime is the default if there is no APP_STL definition in
your Application.mk. As an example, to use the static GNU STL, add a line like:

   APP_STL := gnustl_static

To your Application.mk. You can only select a single C++ runtime that all
your code will depend on. It is not possible to mix shared libraries compiled
against different C++ runtimes.

IMPORTANT: Defining APP_STL in Android.mk has no effect!

If you are not using the NDK build system, you can still use the GNU STL,
see docs/STANDALONE-TOOLCHAIN.html for more details.

The capabilities of the various runtimes vary. See this table:

                 C++       C++   Standard
              Exceptions  RTTI    Library

    system        no       no        no
    gabi++        no      yes        no
    stlport       no      yes       yes
    gnustl       yes      yes       yes


I. Runtimes overview:
---------------------

I.1. System runtime:
- - - - - - - - - - -

The system runtime only provides a very small number of C++ standard headers.

This corresponds to the actual C++ runtime provided by the Android platform.
If you use it, your C++ binaries will automatically be linked against the
system libstdc++.

The only headers provided here are the following:

   cassert cctype cerrno cfloat climits cmath csetjmp csignal cstddef
   cstdint cstdio cstdlib cstring ctime cwchar new stl_pair.h typeinfo
   utility

Anything else is _not_ supported, including std::string or std::vector.


I.2. GAbi++ runtime:
- - - - - - - - - - -

This is a new minimalistic runtime that provides the same headers than
the system one, with the addition of RTTI (RunTime Type Information) support.

There is very little reason to use it right now, but it is planned to become
the basis for STLport's exceptions+RTTI support in the future.

If you insist on using it, read the "RTTI Support" and
"Static runtime considerations" sections below.


I.3. STLport runtime:
- - - - - - - - - - -

This is a port of STLport (http://www.stlport.org) that can be used on
Android. It will provide you with a complete set of C++ standard library
headers, however it ONLY SUPPORTS RTTI, AND NO EXCEPTIONS!

That's because the library embeds its own copy of GAbi++.

Available as both both static and shared libraries. To use it, use either
one of these two lines in your Application.mk:

   APP_STL := stlport_shared
   APP_STL := stlport_static

Note that 'stlport_shared' is preferred, for reasons explained in
"Static runtime considerations".


I.4. GNU STL runtime:
- - - - - - - - - - -

This is the GNU Standard C++ Library (a.k.a. libstdc++-v3), providing the
more features. Note that the shared library file is named "libgnustl_shared.so"
instead of "libstdc++.so" as on other platforms.

If you want to use it, please read the "C++ Exceptions support",
"RTTI Support" and "Static runtime considerations" sections below.



II. Important Considerations:
-----------------------------


II.1. C++ Exceptions support:
- - - - - - - - - - - - - - -

The NDK toolchain supports C++ exceptions, since NDK r5, however all C++
sources are compiled with -fno-exceptions support by default, for
compatibility reasons with previous releases.

To enable it, use the new LOCAL_CPP_FEATURES variable in your Android.mk,
as in:

    LOCAL_CPP_FEATURES += exceptions

See docs/ANDROID-MK.html for more details about this varibale.

Another way to do the same is to define it in your LOCAL_CPPFLAGS definition
(but using LOCAL_CPP_FEATURES is preferred), as in:

    LOCAL_CPPFLAGS += -fexceptions

More simply, add a single line to your Application.mk, the setting will
automatically apply to all your project's NDK modules:

    APP_CPPFLAGS += -fexceptions

IMPORTANT: You *will* have to select a C++ runtime that supports
           exceptions to be able to link / run your code. At this point
           this means only 'gnustl_static' or "gnustl_shared'!


II.2. RTTI support:
- - - - - - - - - -

Similarly, the NDK toolchain supports C++ RTTI (RunTime Type Information)
since NDK r5, but all C++ sources are built with -fno-rtti by default for
compatibility reasons. To enable it, add the following to your module
declarations:

    LOCAL_CPP_FEATURES += rtti

This will be equivalent to:

    LOCAL_CPPFLAGS += -frtti

Or more simply to your Application.mk:

    APP_CPPFLAGS += -frtti


II.3. Static runtimes:
- - - - - - - - - - - -

Please keep in mind that the static library variant of a given C++ runtime
SHALL ONLY BE LINKED INTO A SINGLE BINARY for optimal conditions.

What this means is that if your project consists of a single shared
library, you can link against, e.g., stlport_static, and everything will
work correctly.

On the other hand, if you have two shared libraries in your project
(e.g. libfoo.so and libbar.so) which both link against the same static
runtime, each one of them will  include a copy of the runtime's code in
its final binary image. This is problematic because certain global
variables used/provided internally by the runtime are duplicated.

This is likely to result in code that doesn't work correctly, for example:

  - memory allocated in one library, and freed in the other would leak
    or even corrupt the heap.

  - exceptions raised in libfoo.so cannot be caught in libbar.so (and may
    simply crash the program).

  - the buffering of std::cout not working properly

This problem also happens if you want to link an executable and a shared
library to the same static library.

In other words, if your project requires several shared library modules,
then use the shared library variant of your C++ runtime.


II.4. Shared runtimes:
- - - - - - - - - - - -

If you use the shared library variant of a given C++ runtime, keep in mind
that you must load it before any library that depends on it when your
application starts.

As an example, let's consider the case where we have the following modules

  libfoo.so
  libbar.so which is used by libfoo.so
  libstlport_shared.so, used by both libfoo and libbar

You will need to load the libraries in reverse dependency order, as in:

  static {
    System.loadLibrary("libstlport_shared");
    System.loadLibrary("libbar");
    System.loadLibrary("libfoo");
  }


III. EXTRAS:

III.1. STLport-specific issues:
-------------------------------

This NDK provides prebuilt static and shared libraries for STLport,
but you can force it to be rebuilt from sources by defining the following
in your environment or your Application.mk before building:

    STLPORT_FORCE_REBUILD := true

STLport is licensed under a BSD-style open-source license. See
sources/cxx-stl/stlport/README for more details about the library.


III.2. GNU libstdc++ license is GPLv3 + linking exception!
----------------------------------------------------------

Be aware that the GNU libstdc++ is covered by the GPLv3 license (and *not*
the LGPLv2 or LGPLv3 as some assume), full details available here:

    http://gcc.gnu.org/onlinedocs/libstdc++/manual/license.html

Be sure that you comply with all clauses of this license.


IV. Future Plans:
-----------------

  - Add exceptions support to GAbi++
  - Add exceptions support to STLport (once it is in GAbi++)
  - uSTL support?

Android NDK ChangeLog

This is a mirror of official Google NDK documentation.
-------------------------------------------------------------------------------
android-ndk-r8

IMPORTANT BUG FIXES:

- Fixed a typo in GAbi++ implementaiton where result of dynamic_cast<D>(b)
  of base class object 'b' to derived class D is adjusted wrong
  (in the opposite direction from base class). See
  http://code.google.com/p/android/issues/detail?id=28721

- Fixed an issue in make-standalone-toolchain.sh which fails to copy
  libsupc++.*.


IMPORTANT CHANGES:

- Added support for the mips ABI.

  This release of the Android NDK contains support for 'mips' ABI.
  To generate machine runs on MIPS-based Android devices, please add 'mips' to
  APP_ABI definition in your Application.mk, or 'all' to generate binaries for
  all currently supported ABI.  See docs/CPU-MIPS.html for details.

- You can build a standalone mips toolchain using the
  --toolchain=mipsel-linux-android-4.4.3 option when calling
  make-standalone-toolchain.sh. See docs/STANDALONE-TOOLCHAIN.html for more details.


OTHER BUG FIXE:

- Fixed ndk-build.cmd to ensure that ndk-build.cmd works correctly even if
  the user has redefined the SHELL environment variable (which can happen under
  the hood when installing a variety of development tools on Windows)


-------------------------------------------------------------------------------
android-ndk-r7c

This release of the NDK includes an important fix for Tegra2-based devices,
and a few additional fixes and improvements:

IMPORTANT BUG FIXES:

- Fixed GNU STL armeabi-v7a binaries to not crash on non-NEON devices.
  The files provided with NDK r7b where not configured properly, resulting
  in crashes on Tegra2-based devices and others when trying to use certain
  floating-point functions (e.g., cosf, sinf, expf).


IMPORTANT CHANGES:

- Added support for custom output directories through the NDK_OUT
  environment variable. When defined, this variable is used to store all
  intermediate generated files, instead of $PROJECT_PATH/obj.

  The variable is also recognized by ndk-gdb.

- Added support for building modules with hundreds or even thousand of source
  files by defining LOCAL_SHORT_COMMANDS to true in your Android.mk.

  This change forces the NDK build system to put most linker or archiver
  options into list files, to work-around command-line length limitations
  (particularly on Windows). See docs/ANDROID-MK.html for details.


OTHER BUG FIXES:

- Fixed android_getCpuCount() implementation in the cpufeatures helper
  library. The previous implementation only listed the cores that were
  active the first time the function was called. This behavior could
  provide results that were too low on devices that disable and enable
  cores dynamically.

-------------------------------------------------------------------------------
android-ndk-r7b

IMPORTANT BUG FIXES:

- Updated <sys/atomics.h> to avoid correctness issues on some multi-core
  ARM-based devices. Rebuild your unmodified sources with this version of the
  NDK and this problem should completely be eliminated. For more details, read
  docs/ANDROID-ATOMICS.html.

- Reverted to binutils 2.19 to try to fix debugging issues that
  appeared in NDK r7 (which switched to binutils 2.20.1).

- Fixed ndk-build on 32-bit Linux. A packaging error put a 64-bit version
  of the 'awk' executable under prebuilt/linux-x86/bin in NDK r7.

- Fixed native Windows build (ndk-build.cmd). Other build modes were not
  affected. The fixes include:

    * Removed an infinite loop / stack overflow bug that happened when trying
      to call ndk-build.cmd from a directory that was _not_ the top of your
      project path (e.g. any sub-directory of it).

    * Fixed a problem where the auto-generated dependency files were ignored.
      This meant that updating a header didn't trigger recompilation of sources
      that included it.

    * Fixed a problem where special characters in files or paths, other than
      spaces and quotes, were not correctly handled.

- Fixed the standalone toolchain to generate proper binaries when using
  -lstdc++ (i.e. linking against the GNU libstdc++ C++ runtime). You should
  use -lgnustl_shared if you want to link against the shared library
  version or -lstdc++ for the static version.

  See docs/STANDALONE-TOOLCHAIN.html for more details about this fix.

- Fixed gnustl_shared on Cygwin. The linker complained that it couldn't find
  libsupc++.a while the file was at the right location.

- Fixed cygwin C++ link when not using any specific C++ runtime through
  APP_STL.

OTHER CHANGES:

- When your application uses the GNU libstdc++ runtime, the compiler will
  no longer forcibly enable exceptions and RTTI. This change results in smaller
  code. If you need these features, you need to do either one of these:

     1/ Enable exceptions and/or RTTI explicitely in your modules or
        Application.mk. (recommended)

     2/ Define APP_GNUSTL_FORCE_CPP_FEATURES to 'exceptions', 'rtti' or both
        in your Application.mk. See docs/APPLICATION-MK.html for more details.

- ndk-gdb now works properly when your application has private services
  running in independent processes. It debugs the main application process,
  instead of the first process listed by 'ps', which is usually a service
  process.

- Fixed a rare bug where NDK r7 would fail to honor the LOCAL_ARM_MODE value
  and always compile certain source files (but not all) to 32-bit instructions.

- stlport: Refresh the sources to match the Android platform version. This
  update fixes a few minor bugs:

   - Fixed instantiation of an incomplete type.
   - Fixed minor == versus = typo
   - Use memmove instead of memcpy in string::assign
   - Added better handling of IsNANorINF, IsINF, IsNegNAN, etc..

  For complete details, see the commit log.

- stlport: Removed 5 un-necessary static initializers from the library.

- The GNU libstdc++ libraries for armeabi-v7a were mistakenly compiled for
  armeabi instead. This had no impact on correctness, but using the right
  ABI should provide for slightly better performance.

- the 'cpu-features' helper library was updated to report three optional
  x86 CPU features (SSSE3, MOVBE and POPCNT). See docs/CPU-FEATURES.html
  for more details.

- docs/NDK-BUILD.html was updated to mention NDK_APPLICATION_MK instead
  of NDK_APP_APPLICATION_MK to select a custom Application.mk file.

- cygwin: ndk-build no longer creates an empty "NUL" file in the current
  directory when invoked.

- cygwin: better automatic dependency detection. It previously didn't work
  properly in the following case:

    - When the cygwin drive prefix was not /cygdrive
    - When using drive-less mounts, e.g. when Cygwin would translate /home
      to \\server\subdir instead of C:\Some\Dir.

- cygwin: ndk-build does not try to use the native Windows tools under
  $NDK/prebuilt/windows/bin with certain versions of Cygwin and/or
  GNU Make.

-------------------------------------------------------------------------------
android-ndk-r7

IMPORTANT CHANGES:

- New official NDK APIs for Android 4.0 (a.k.a. API level 14),
  which adds the following native features to the platform:

     - Native multimedia API based on the Khronos Group OpenMAX AL™
       1.0.1 Standard.  New headers <OMXAL/OpenMAXAL.h> and
       <OMXAL/OpenMAXAL_Android.h> are provided to allow
       applications targeting this API level to perform multimedia output
       directly from native code using a new Android-specific buffer
       queue interface.  For more details, see docs/openmaxal/index.html
       and http://www.khronos.org/openmax/.

     - Updated the native audio API based on the Khronos Group OpenSL ES
       1.0.1™ Standard.  API Level 14 can now decode compressed
       audio (e.g. MP3, AAC, Vorbis) to PCM.  For more details, see
       docs/opensles/index.html and http://www.khronos.org/opensles/.

- CCache support. To speed up large rebuilds, simply define the NDK_CCACHE
  environment variable to 'ccache' (or the path to your ccache binary), as in:

        export NDK_CCACHE=ccache

  The NDK build system will automatically use it when compiling any source
  file. For more information about CCache, see http://ccache.samba.org  

- You can now set your APP_ABI to 'all' to indicate that you want to build
  your NDK modules for all the ABIs supported by your given NDK release.

  This means that either one of these two lines in your Application.mk are
  equivalent with this release:

        APP_ABI := all
        APP_ABI := armeabi armeabi-v7a x86

  This also works if you define APP_ABI on the command-line, as in:

        ndk-build APP_ABI=all

  Which is a quick way to check that your project builds for all supported
  ABIs without changing its Application.mk file.

- Shorter paths to source and object files used in build commands.
  When invoking $NDK/ndk-build from your project path, the paths to the
  source, object and binary files passed to the build commands will be
  significantly shorter now because they are now passed relative to the
  current directory.

  This is useful when building projects with a lot of source files, to
  avoid limits on the maximum command line length supported by your host
  operating system.

  The behaviour is unchanged if you invoked ndk-build from a sub-directory
  of your project tree, or if you define NDK_PROJECT_PATH to point to a
  specific directory.

- New LOCAL_CPP_FEATURES variable in Android.mk, used to declare which C++
  features (RTTI or Exceptions) your module uses. This is especially handy
  if you have prebuilt modules that depend on them since this will ensure
  the final link will work correctly.

  See docs/ANDROID-MK.html and docs/CPLUSPLUS-SUPPORT.html for more details

- WARNING: VERY EXPERIMENTAL!!

     You can now build your NDK sources on Windows *without* Cygwin.
     Simply call the script 'ndk-build.cmd' from the Windows cmd.exe
     command-line, when in your project path.

     The script takes exactly the same arguments than the original
     ndk-build one.

     Note that the Windows NDK package comes with its own prebuilt
     binaries for GNU Make, Awk and other tools required by the build,
     i.e. you shouldn't need to install anything else to get a working
     build system.

     IMPORTANT: ndk-gdb doesn't work. You still need Cygwin to debug
                at the moment!

     This feature is still very experimental, but feel free to try it
     and report issues on the public forum (android-ndk@googlegroups.com)
     or the public bug databse (http://b.android.com).

     Note that all samples and unit tests succesfully compile with it.

IMPORTANT BUG FIXES:

- Imported shared libraries are now installed by default to the target
  installation location (i.e. libs/%lt;abi%gt;) if APP_MODULES is not
  defined in your Application.mk.

  This means that if a top-level module "foo" imports a module "bar", then
  both libfoo.so and libbar.so will be copied to the install location.

  Previously, only libfoo.so was, unless you listed 'bar' in your APP_MODULES
  too.

  If you define APP_MODULES explicitely, the behaviour is unchanged.

- Static library imports are now properly transitive. If top-level module
  'foo' imports static library 'bar' which imports static library 'zoo',
  the libfoo.so will now be linked against both libbar.a and libzoo.a.

- ndk-gdb now works correctly for activities with multiple categories
  in their MAIN intent filters.

OTHER CHANGES:

- docs/STABLE-APIS.html: Added missing documentation listing EGL
  as a supported stable API, starting from API level 9.

- Add a new C++ support runtime named "gabi++". More details about it
  are available in the updated docs/CPLUSPLUS-SUPPORT.html.

- The STLport C++ runtimes now support RTTI (no exceptions yet though).

- Add a new C++ support runtime named "gnustl_shared" corresponding to the
  shared library version of GNU libstdc++ v3 (GPLv3 license). See more
  info at docs/CPLUSPLUS-SUPPORT.html

- You can now list several file extensions in LOCAL_CPP_EXTENSION. As in:

        LOCAL_CPP_EXTENSION := .cpp .cxx

  To compile both foo.cpp and bar.cxx as C++ sources.

- Refreshed the EGL and OpenGLES Khronos headers to support more extensions.
  Note that this does *not* change the NDK ABIs for the corresponding
  libraries, since each extension must be probed at runtime by the client
  application.

  Which extensions are available depends on your actual device (and GPU
  drivers), not the version of the platform it provides.

  The header changes simply add new constants and types to make it easier
  to use the extensions why they have been probed with eglGetProcAddress() or
  glGetProcAddress(). Here is the list of newly supported extensions:

    GLES 1.x
    --------
    GL_OES_vertex_array_object
    GL_OES_EGL_image_external
    GL_APPLE_texture_2D_limited_npot
    GL_EXT_blend_minmax
    GL_EXT_discard_framebuffer
    GL_EXT_multi_draw_arrays
    GL_EXT_read_format_bgra
    GL_EXT_texture_filter_anisotropic
    GL_EXT_texture_format_BGRA8888
    GL_EXT_texture_lod_bias
    GL_IMG_read_format
    GL_IMG_texture_compression_pvrtc
    GL_IMG_texture_env_enhanced_fixed_function
    GL_IMG_user_clip_plane
    GL_IMG_multisampled_render_to_texture
    GL_NV_fence
    GL_QCOM_driver_control
    GL_QCOM_extended_get
    GL_QCOM_extended_get2
    GL_QCOM_perfmon_global_mode
    GL_QCOM_writeonly_rendering
    GL_QCOM_tiled_rendering

    GLES 2.0
    --------
    GL_OES_element_index_uint
    GL_OES_get_program_binary
    GL_OES_mapbuffer
    GL_OES_packed_depth_stencil
    GL_OES_texture_3D
    GL_OES_texture_float
    GL_OES_texture_float_linear
    GL_OES_texture_half_float_linear
    GL_OES_texture_npot
    GL_OES_vertex_array_object
    GL_OES_EGL_image_external
    GL_AMD_program_binary_Z400
    GL_EXT_blend_minmax
    GL_EXT_discard_framebuffer
    GL_EXT_multi_draw_arrays
    GL_EXT_read_format_bgra
    GL_EXT_texture_format_BGRA8888
    GL_EXT_texture_compression_dxt1
    GL_IMG_program_binary
    GL_IMG_read_format
    GL_IMG_shader_binary
    GL_IMG_texture_compression_pvrtc
    GL_IMG_multisampled_render_to_texture
    GL_NV_coverage_sample
    GL_NV_depth_nonlinear
    GL_QCOM_extended_get
    GL_QCOM_extended_get2
    GL_QCOM_writeonly_rendering
    GL_QCOM_tiled_rendering

    EGL:
    ----
    EGL_ANDROID_recordable
    EGL_NV_system_time

- docs/NATIVE-ACTIVITY.HTML: Fixed typo, the minimum API level
  should be 9, not 8 for native activities.

- removed many unwanted exported symbols from the link-time shared
  system libraries provided by the NDK. This ensures that code generated
  with the standalone toolchain doesn't risk to accidentally depend
  on a non-stable ABI symbol (e.g. any libgcc.a symbol that changes
  each time the toolchain used to build the platform is changed).

- download-toolchain-sources.sh: Script was updated to download the toolchain
  sources from android.googlesource.com, the new location for AOSP servers.

-------------------------------------------------------------------------------
android-ndk-r6b

This is a bug-fix release for NDK r6, no new features are provided.

IMPORTANT BUG FIXES:

- Fixed the multi-architecture build, i.e. when using APP_ABI="armeabi x86"

- Fixed location of prebuilt STLport binaries in the NDK release package.
  (A bug in the packaging script placed them in the wrong location).

- Fixed atexit() usage in shared libraries with the x86 standalone toolchain.

- Fixed make-standalone-toolchain.sh --arch=x86 (it failed to copy the
  proper GNU libstdc++ binaries to the right location).

- Fixed standalone toolchain linker warnings about missing definition and
  size for '__dso_handle' symbol (arm only).

- Fixed the inclusion order of $(SYSROOT)/usr/include for x86 builds,
  see http://code.google.com/p/android/issues/detail?id=18540

- Fixed the definitions of ptrdiff_t and size_t in x86-specific system
  when used with the x86 standalone toolchain.

-------------------------------------------------------------------------------
android-ndk-r6

IMPORTANT CHANGES:

- Official support for the x86 ABI.

  This release of the Android NDK now provides support for the 'x86' ABI.
  This allows you to generate machine code that runs on future x86-based
  Android devices.

  Note that by default, code is still generated for ARM-based devices.
  You can however add 'x86' to your APP_PLATFORM definition in your
  Application.mk. For example, the following line instructs ndk-build
  to build your code for three distinct ABIs:

    APP_ABI := armeabi armeabi-v7a x86

  Unless you rely on ARM-based assembly sources, you shouldn't need to touch
  your Android.mk files to build x86 machine code.

  For all details regarding x86 support, please read the new documentation
  file named docs/CPU-X86.html.

  Don't hesitate to file NDK bugs related to x86 at http://b.android.com

- You can build a standalone x86 toolchain using the --toolchain=x86-4.4.3
  option when calling make-standalone-toolchain.sh. See
  docs/STANDALONE-TOOLCHAIN.html for more details.

- The new 'ndk-stack' tool can be used to translate stack traces
  (as reported by adb logcat in case of crash in native code) into
  something more readable, i.e. containing function / source file /
  line number information corresponding to each stack frame.

  For more information and usage example, see the new documentation
  file docs/NDK-STACK.html

OTHER FIXES & CHANGES:

- The arm-eabi-4.4.0, which had been deprecated since NDK r5, has been
  finally removed from the NDK distribution.

- Support a project.properties file in the application's directory
  instead of default.properties. This is in preparation for future SDK Tools
  changes.

-------------------------------------------------------------------------------
android-ndk-r5c

This release fixes a few bugs in r5b. There are no new features.

IMPORTANT BUG FIXES:

- Fixed a typo that prevented LOCAL_WHOLE_STATIC_LIBRARIES to work correctly
  with the new toolchain. Also properly document this variable in
  docs/ANDROID-MK.html.

- Fixed a bug where code linked against gnustl_static would crash when run
  on Android platform releases older than 2.2.

- <android/input.h>: Two functions in this header file, introduced
  by API level 9 (a.k.a. 2.3) were incorrect and have been fixed. While
  this breaks the source API, the binary interface to the system is
  unchanged.

  The functions missing a third 'history_index' parameter. They correct
  definition is now:

      float AMotionEvent_getHistoricalRawX(const AInputEvent* motion_event,
                                           size_t pointer_index,
                                           size_t history_index);

      float AMotionEvent_getHistoricalRawY(const AInputEvent* motion_event,
                                           size_t pointer_index,
                                           size_t history_index);

- Updated the android-9 C library arm binary to correctly expose at link time
  new functions that were added to it in Gingerbread (e.g. pthread_rwlock_init).

- Fixed a bug that made gdbserver crash on misc. Honeycomb devices (e.g.
  the Motorola Xoom).

OTHER FIXES & CHANGES:

- Object files are now always linked in the order they appear in
  LOCAL_SRC_FILES. This was not the case previously because the files
  were grouped by source extensions instead.

- download-toolchain-sources.sh: Fixed a silly bug that prevented the
  --git-date option to work properly when downloading the master branch.

- Fix an issue where a module could import itself, resulting in an infinite
  loop in GNU Make.

- When import-module fails, it now prints the list of directories
  that were searched. This is useful to check that the NDK_MODULE_PATH
  definition used by the build system is correct.

- When import-module succeeds, it now prints the directory where the module
  was found to the log (visible with NDK_LOG=1).

- <pthread.h>: Fixed the definition of PTHREAD_RWLOCK_INITIALIZER for
  android-9 API level and higher.

- Fixed a bug where LOCAL_ARM_NEON was defined to true would make the build
  fail (typo in build/core/build-binary.mk)

- Fixed a bug that prevented the compilation of .s assembly files
  (.S files were ok).

- Speed-up the build of debuggable applications when there is a very
  large number of include directories in a project.

- ndk-gdb: Better detection of 'adb shell' failures (improves error messages).

- ndk-build: Fix a rare bug that appeared when trying to perform parallel
  builds of debuggable projects.


-------------------------------------------------------------------------------
android-ndk-r5b

This release fixes a few bugs in r5. There are no new features.

IMPORTANT BUG FIXES:

- Fix a compiler bug in the arm-linux-androideabi-4.4.3 toolchain.
  The previous binary generated invalid thumb instruction sequences when
  dealing with signed chars. This problem was first reported on the
  android-ndk forum and fixed by the following change in the toolchain
  sources:

        https://review.source.android.com/#change,19474

- docs/CPLUSPLUS-SUPPORT.html: Add missing documentation for the
  "gnustl_static" value for APP_STL, that allows you to link against
  a static library version of GNU libstdc++.

- ndk-build: Fix a bug that created inconsistent dependency files when a
  compilation error occured on Windows, preventing building properly after
  the error was fixed in the source code.

- ndk-build: Fix a Cygwin-specific bug where using very short paths for
  the Android NDK installation or the project path could lead to the
  generation of invalid dependency files, making incremental builds
  impossible.

- Fix a typo that prevented the cpufeatures library to work correctly
  with the new NDK toolchain.

- Linux toolchain binaries now run on Ubuntu 8.04 or higher.
  More specifically, the r5 binaries did require GLibc 2.11 on the host
  system, and refused to run with previous releases due to an ABI mismatch
  in the GNU C Library. The r5b binaries are generated with a special
  toolchain that instead targets GLibc 2.7 or higher.

- GNU libstdc++ will not crash anymore when printing floating-point values
  through i/o streams.

OTHER FIXES & CHANGES:

- ndk-build: Speed-up the Cygwin build by avoiding calling "cygpath -m"
  from GNU Make for each and every source or object file. This was a problem
  for users with very large source trees.

  In case this doesn't work properly, define NDK_USE_CYGPATH=1 in your
  environment to use 'cygpath -m' as usual.

  Also, if 'cygpath' is not in your path, completely ignore it
  (seems to be enough to run the NDK under MSys).

- ndk-build: Handle installation paths containing spaces when checking
  cygwin installation. Before that, the script complained that the user
  was using an incorrect version of GNU Make (even if he had the right one).

- Fixed a typo that prevented several NDK_MODULE_PATH to work properly when
  it contained multiple directories separated with ":"

- prebuilt-common.sh: Make the script check the compiler directly for 64-bit
  generated machine code, instead of relying on the host tag. That should
  allow the 32-bit toolchain to rebuild properly on Snow Leopard.

- prebuilt-common.sh: Fix the toolchain rebuild scripts to work when
  using a 32-bit host toolchain.

- <netinet/in.h>: Add missing declaration for INET_ADDRSTRLEN
- <netinet/in6.h>: Add missing declaration for IN6_IS_ADDR_MC_NODELOCAL
  and IN6_IS_ADDR_MC_GLOBAL.

- <asm/byteorder.>: Replaced 'asm' with '__asm__' to allow compilation
  with -std=c99. See https://review.source.android.com/#change,20076

- standalone toolchain: The -fpic flag is now the default for the
  arm-linux-androideabi toolchain, instead of -fPIC. This avoids a performance
  degradation when compared to the old android-eabi configuration.

  This only affects users of the standalone toolchain. The NDK build script
  always enforced -fpic implicitely.

-------------------------------------------------------------------------------
android-ndk-r5

IMPORTANT BUG FIXES:

- Allow dlclose() to properly call static C++ destructors when unloading
  a shared library. This requires changes in both the C library and the
  build system. IMPORTANT: This feature is only available for API level 9.

- Fix packaging error for system libraries of level 5 and 8. The libraries
  bundled with the NDK and used at link time were not the correct version,
  and this prevented linking against certain symbols appropriately.

- ndk-gdb: do not start activity unless --start or --launch is used.
  (the documentation was correct, the implementation wrong)

- The system headers for all API levels have been cleaned up and will
  not provide the declarations of functions that are not available in
  the corresponding system libraries.

IMPORTANT CHANGES:

- Support for API level 9, (a.k.a. Android 2.3) which adds the following
  native features to the platform:

     - Native audio API based on the Khronos Group OpenSL ES™ 1.0.1 Standard.
       New headers <SLES/OpenSLES.h> and <SLES/OpenSLES_Android.h>
       are provided to allow applications targeting this API level to perform
       audio input, output and processing directly from native code.

     - Native activity support, i.e. the ability to build applications that
       are coded entirely in C or C++. More precisely, such applications still
       run inside a VM, and will have to access most of the platform's features
       using JNI (i.e. native code calling VM methods). However, this also
       comes with a series of headers and libraries to implement the following
       directly from native code:

          - activity lifecycle management.
          - user input handling (touch, keyboard, trackball, ...).
          - window management (including accessing the pixel buffer).
          - sensor listeners (e.g. accelerometer, compass, ...).
          - hardware configuration management.
          - easily reading assets out of an APK from native code.
          - access to the storage manager, a new feature of Android X.X
            that allows one to provide Opaque Binary Objects containing
            large amounts of data outside of the APK.

       See the documentation in docs/STABLE-APIS.html for more details.

       Note that most of these new features are targeted at game developers.

- Improved gdbserver binary to allow debugging _threaded_ programs properly
  with ndk-gdb (the previous binary could only set breakpoints on the main
  thread).

  IMPORTANT: THIS ONLY WORKS IF YOU RUN ON ANDROID 2.3 OR HIGHER.

  The root cause of the problem is a platform bug that was only fixed in
  2.3. If you try to debug on a previous platform, the gdbserver binary
  will only be able to set breakpoints on the main thread.

  For more information, see the specific section in docs/NDK-GDB.html.

- Easier debuggable builds: just invoke ndk-build while defining the
  NDK_DEBUG variable to 1, as in:

      $NDK/ndk-build NDK_DEBUG=1

  This will have the same result that setting the android:debuggable="true"
  in the <application> element of your AndroidManifest.xml file. See the
  file docs/NDK-BUILD.html for more details.

  Note that you will need to use the SDKr8 build tools to use this feature
  properly!

- Refresh of system C++ headers:

     - Headers have been moved out of the platform directory hierarchy.
       This is to prevent conflicts with other STLs like STLport or the
       GNU libstdc++ which provide their own version of the headers, but
       does not affect your builds.

     - The list of headers has grown to include the following:

            cassert, cctype, cerrno, cfloat, climits, cmath,
            csetjmp, csignal, cstddef, cstdint, cstdio, cstdlib,
            cstring, ctime, cwchar, new, typeinfo, utility

    Note that they still correspond to our minimal C++ runtime, no new feature
    was introduced here.

- Support for C++ exceptions and RTTI. See docs/CPLUSPLUS-SUPPORT.html for
  all details (and limitations).

- STLport implementation: Add sources and prebuilt binaries for a port of
  the STLport C++ Standard Library (www.stlport.org), and an easy way to use
  it at build time by defining APP_STL in your Application.mk. See
  docs/APPLICATION-MK.html and docs/CPLUSPLUS-SUPPORT.html for all details.

- GNU libstdc++ implementation: Available as a static library that you can
  select for your application through APP_STL. See docs/CPLUSPLUS-SUPPORT.html
  for all details.

- Add support for prebuilt libraries with the PREBUILT_SHARED_LIBRARY and
  PREBUILT_STATIC_LIBRARIES build scripts. See the new documentation
  file named docs/PREBUILTS.html for explanations and usage examples.

- Support for module exports: A module can now define a set of compiler or
  linker flags that will be automatically 'imported' by any other module that
  depends on it, through LOCAL_STATIC_LIBRARIES or LOCAL_SHARED_LIBRARIES.

  This is achieved with the help of new Android.mk variables named
  LOCAL_EXPORT_CFLAGS, LOCAL_EXPORT_CPPFLAGS, LOCAL_EXPORT_C_INCLUDES and
  LOCAL_EXPORT_LDLIBS. See docs/ANDROID-MK.html for mode documentation, and
  a 'samples/module-exports' for a sample project that uses this.

- Add support to specify a different file name for generated files, through
  the new LOCAL_MODULE_FILENAME variable. See docs/ANDROID-MK.html for an
  example.

- Add support for module imports, through the NDK_MODULE_PATH environment
  variable and the new 'import-module' function. This allows you to avoid
  hard-coding the path of third-party modules into your project files.

  See docs/IMPORT-MODULE.html for details.

- Add the content of LOCAL_C_INCLUDES to gdb.setup to make native debugging
  easier. Also fixes an issue that prevented clean parallel builds of
  debuggable applications to work correctly. This fixes an error message that
  said:

      /bin/sh: <project>/libs/armeabi/gdb.setup: No such file or directory

  When doing a "ndk-build -j<number>", with <number> bigger than 1.

- Add support for assembly-level source filtering. See the description of
  LOCAL_FILTER_ASM in docs/ANDROID-MK.html for more details. This can be useful
  for certain kinds of obfuscation tasks.

- This NDK comes with a new toolchain (named arm-linux-androideabi-4.4.3)
  which provides many benefits, including:

     - Better code generation than the previous one (gcc-4.4.0)
     - On Windows, the binaries do not depend on Cygwin anymore.
     - The ability to use it as a stand-alone cross-compiler
       (see docs/STANDALONE-TOOLCHAIN.html for all details).

  The binaries for gcc-4.4.0 are still provided for backwards compatibility.
  Use NDK_TOOLCHAIN=arm-eabi-4.4.0 in your environment to force its usage.
  Note that it is now deprecated and will be removed in a future NDK release.

  IMPORTANT: The old toolchain doesn't properly support exceptions, RTTI,
             STLport and GNU libstdc++.

  The binaries for the already-deprecated gcc-4.2.1 have been removed.

- The 'cpufeatures' library has been updated to provide better architecture
  and features detection (including a work-around for buggy ARMv6 kernels
  which report an architecture version of 7).

  The library is now also available as an import module, to simplify its
  usage in your build scripts. See the updated docs/CPU-FEATURES.html file
  for details.

  NOTE: Please update your Android.mk to use module imports as soon as
        possible. The location $NDK/source/cpufeatures/ is deprecated
        and will be removed in a future NDK release. Avoid referencing
        it directly in your build scritps!

OTHER FIXES AND CHANGES:

- Reduced the size of generated binaries by using --strip-unneeded
  instead of --strip-debug. This gets rid of mor symbol table entries
  in release shared libraries and executables, without impacting
  runtime execution.

- Fix bad automatic dependency tracking when using multiple source
  sub-directories.

- The path to system headers is now included last in the compilation command
  line. This prevents conflicts with source code that define their own headers
  with similar names (e.g. a custom "err.h" was ignored, because the system
  <err.h> was used instead).

- Update documentation for 'my-dir' function to explain that, due to the
  way GNU Make works, it really returns the path of the last included
  Makefile (instead of the current one). Also provide examples on how
  to deal with it.

- make-release.sh: Now has an --out-dir=<path> option to specify the
  output directory where the packages are going to be copied. Also
  ensure that generated packages have go+r permissions.

- ndk-build will now properly escape arguments. This means that something
  like this:

     ndk-build  MY_CFLAGS="-DFOO -DBAR"

  will now work correctly.

- Add --git-http option to download-toolchain-sources.sh and
  rebuild-all-prebuilt.sh in order to download sources from
  android.git.kernel.org through HTTP.

- ndk-gdb: properly launch activities for which name does not contain any dot.

- ndk-gdb: add --delay=<timeout> option to specify a delay in seconds
  between activity launch and gdbserver attach. This is needed because certain
  activities can take a long time to properly launch. The default delay is
  also increased to 2 seconds (instead of 1).

- build/tools/build-gcc.sh: copy the sysroot to the build directory. This
  avoids the generated toolchain binaries from hard-coding host build paths.

- Platform files are now under $NDK/platforms instead of $NDK/build/platforms

- Toolchain files are now under $NDK/toolchains instead of
  $NDK/build/toolchains and $NDK/build/prebuilt.

- Release and debug objects are stored under two different directories now
  (i.e. obj/local/<abi>/objs and obj/local/<abi>/objs-debug). This
  prevents rebuilding *everything* when you switch between these two modes,
  which can be a real time-saver for complex projects.

- Fixed a bug that duplicated the LOCAL_LDFLAGS in the final link command
  when LOCAL_ALLOW_UNDEFINED_SYMBOLS was not set to 'true'

-------------------------------------------------------------------------------
android-ndk-r4b

This release fixes a few bugs in r4 scripts. There are no new features.

OTHER FIXES & CHANGES:

- build/tools/rebuild-all-prebuilt.sh: mktemp expects 'XXXXXX' instead of 'XXX'.
  Fix the script (and others in the same directory) to do that properly.

- ndk-gdb: check the target device's API level, and dump an error message if
  it is not at least 8 (Android 2.2 a.k.a. Froyo). Fix script to properly
  remove control characters like '\r' from adb shell's output. Also fix
  script to work properly with OS X's BSD awk.

- ndk-build: Make AndroidManifest.xml optional. Now the build scripts will try
  to look for jni/Android.mk if no manifest is found. If you don't use this,
  you can also define NDK_PROJECT_PATH to point to your tree.

  Also, on Windows, check that a Cygwin-compatible make executable is being
  used, and dump a readable help message to solve the issue if this is not
  the case.

- Place generated binaries under $PROJECT_PATH/obj/ instead of
  $PROJECT_PATH/bin/ndk/. The 'bin' directory is sometimes cleaned
  by the JDT, resulting in the inability to properly load symbol versions
  of the shared libraries when running ndk-gdb.

- Warn when sources with unsupported extensions are used in LOCAL_SRC_FILES.
  Previous behaviour was to silently ignore them.

- Set the optimization mode to 'debug' automatically if the manifest sets
  android:debuggable to 'true'. You can override this by using
  'APP_OPTIM := release' in your Application.mk, or by adding '-O2' to
  your LOCAL_CFLAGS.

  Note that even in release mode, the NDK build scripts will produce
  binaries with symbols under obj/local/<abi>/ that will be used for
  debugging with gdb. However, the debugger will have a harder time to
  print proper local variable values that have been optimized out or
  even set breakpoints properly.

-------------------------------------------------------------------------------
android-ndk-r4

IMPORTANT BUG FIXES:

- The <fenv.h> header was not placed in the correct location and could not
  be found by normal builds.

IMPORTANT CHANGES:

- On Windows, Cygwin 1.7 or higher is now required. The NDK will not
  work properly with Cygwin 1.5 which is now officially obsolete
  anyway.

- Simplified build system: You no longer need to run build/host-setup.sh
  or modify anything under $NDK_ROOT/apps/. Instead, just invoke the
  new 'ndk-build' script from your application's project directory, or
  one of its sub-directories.

  See docs/OVERVIEW.html and docs/NDK-BUILD.html for more details.

  NOTE: For compatibility purpose, you can still define projects
        through $NDK_ROOT/apps/<name> though.

        However, not that sample applications have moved from
        'apps/<name>/project' to 'samples/<name>' and now must
        be built with 'ndk-build'. The source code of pre-existing
        samples didn't change though.

- Easy native debugging support when running debuggable applications
  on Android 2.2 or higher, through the new 'ndk-gdb' helper script.
  See docs/NDK-GDB.html for details.

- Support for hardware FPU. This is through the new 'armeabi-v7a' ABI
  corresponding to ARMv7-a class devices.

  Note that by default, the NDK will still generate machine code for the old
  'armeabi' ABI (ARMv5TE based) which is supported by all official Android
  system images to date.

  You will need to define APP_ABI in your Application.mk file to change this.
  See docs/APPLICATION-MK.html

  More details about ABIs is now available in docs/CPU-ARCH-ABIS.html

- A small static library named 'cpufeatures' is provided with source code
  and can be used at runtime to determine the CPU features supported by the
  target device. It should run on all Android platforms, starting from 1.5.

  For more information, see docs/CPU-FEATURES.html

- Support for the optional ARM Advanced SIMD (a.k.a. NEON) instruction set
  extension through the use the LOCAL_ARM_NEON variable in Android.mk, or
  the '.neon' suffix when listing source files.

  Neon is an *optional* instruction set extension, and not all Android ARMv7
  devices will support it. You will need to use the 'cpufeatures' library to
  determine if such code can be used at runtime, and provide alternate code
  paths if this is not the case. This is similar to MMX/SSE/3DNow on x86
  platforms.

  For more information, see docs/CPU-ARM-NEON.html

- Added a new sample (hello-neon) to demonstrate usage of 'cpufeatures'
  and NEON intrinsics and build support.

- Added <android/bitmap.h>, a new stable API available from android-8
  (a.k.a. Android 2.2) to reliably access the pixel buffer of an
  android.graphics.Bitmap object from native code. See docs/STABLE-API.html
  and the new sample program under 'samples/bitmap-plasma' for details
  and usage example.

- Support the NX (No Execute) security feature, where special sections
  are added to the generated shared libraries to instruct the kernel
  that code shall not be executed from the heap and stack by default.

  See docs/ANDROID-MK.html to see how to disable this, plus reference
  links for more information.

OTHER FIXES AND CHANGES:

- support the .s extension for raw assembly sources (.S is already supported
  but the input files are parsed by the C-preprocessor before being sent to
  the assembler).

- build/host-setup.sh has been removed. There is no need for a 'setup' step
  when using the NDK for the first time. All host-specific autodetection and
  basic tool sanity checking have been moved to the build scripts themselves.

- APP_MODULES in Application.mk is now optional. If not defined, the NDK
  will simply build _all_ the modules that are declared from your Android.mk.

  You can still use APP_MODULES to restrict the set of modules you want to
  build. Note that the NDK now computes the transitive dependencies of these
  modules for you now. See docs/APPLICATION-MK.html for details.

- docs/STABLE-APIS.html: Add missing section for Dynamic Linker Library
  (libdl.so). It is actually supported by all API levels.

- build/tools/download-toolchain-sources.sh: Use 'master' branch by default
  instead of the 'eclair' one.

- build-toolchain.sh: Allow ad-hoc patching of toolchain sources when rebuilding
  them. This is primarily to ease development. All you need to do is put a patch
  under build/tools/toolchain-patches/<foo>/<name>.patch, and it will be applied
  with 'patch -p1' into the <foo> directory of the unpacked toolchain sources
  before the configure step.

- docs/CPU-ARCH-ABIS.html: Mention the experimental 'x86' ABI.

- build/core/mkdeps.sh: Removed obsolete script.

- the NDK build script now only parses the Application.mk and Android.mk of
  the applications listed by APP. The error messages when APP is empty or
  malformed have also been improved.

- removed the annoying 'the mangling of 'va_list' has changed in GCC 4.4'
  warning when building with GCC 4.4.0 for ARM.

- C Library header fixes:

    For all platforms:

        - <arpa/inet.h>: no longer includes <netinet/in6.h>.
        - <ctype.h>: better inlining with -ansi option.
        - <mntent.h>: add missing include for <stdio.h>.
        - <netinet/in.h>: include <netinet/in6.h> and define in6addr_any +
          in6addr_loopback.
        - <netinet/in6.h>: add IPV6_JOIN_GROUP, IPV6_LEAVE_GROUP,
          IN6ADDR_ANY_INIT, ipv6mr_interface.
        - <sys/epoll.h>: add missing C++ inclusion guards.
        - <sys/resource.h>: add missing rlim_t declaration.
        - <sys/system_properties.h>: add missing C++ inclusion guards.
        - <time64.h>: add missing C++ inclusion guards.
        - <netdb.h>: move h_errno declaration inside C++ inclusion guards.

- C Library changes:

    For android-8 (a.k.a. Android 2.2):

        - <dlfcn.h>: add DL_info and dladdr().
        - <err.h>: add err(), warn() and other variants.
        - <regex.h>, <fts.h>, <sys/queue.h>: added
        - <pthread.h>: add pthread_condattr_t
        - <sched.h>: added proper clone() declaration (and implementation).
        - <signal.h>: added killpg().
        - <stdio.h>: add fdprintf() and vfdprintf().
        - <stdlib.h>: fix ptsname_r() signature in declaration. previous
          implementation was broken anyway.
        - <unistd.h>: add getusershell(), setusershell(), endusershell(),
          ttyname(), ttyname_r(), TEMP_FAILURE_RETRY. Fix usleep() signature
          (now returns int).
        - <wchar.h>: add fake mbstowcs() and wcstombs().

  More details available under docs/system/libc/CHANGES.html

-------------------------------------------------------------------------------
android-ndk-r3

IMPORTANT BUG FIXES:

- Fix build/host-setup.sh to execute as a Bourne shell script (again)

- Make target shared libraries portable to systems that don't use the exact
  same toolchain. This is needed due to differences in libgcc.a implementations
  between gcc 4.2.1 and 4.4.0. This change ensures that generated machine
  code doesn't depend on helper functions provided by the Android platform
  runtime.


IMPORTANT CHANGES:

- GCC 4.4.0 is now used by default by the NDK. It generates better code than
  GCC 4.2.1, which was used in previous releases. However, the compiler's C++
  frontend is also a lot more pedantic regarding certain template constructs
  and will even refuse to build some of them.

  For this reason, the NDK also comes with GCC 4.2.1 prebuilt binaries, and
  you can force its usage by defining NDK_TOOLCHAIN in your environment to
  the value 'arm-eabi-4.2.1'. For example:

        export NDK_TOOLCHAIN=arm-eabi-4.2.1
        make APP=hello-jni

  Note that only the 'armeabi' ABI is supported by the 4.2.1 toolchain. We
  recommend switching to 4.2.1 *only* if you encounter compilation problems
  with 4.4.0.

  The 4.2.1 prebuilt binaries will probably be removed from a future release
  of the Android NDK, we thus *strongly* invite you to fix your code if such
  problems happen.

- Support for OpenGL ES 2.0. This is through the new 'android-5' platform to
  reflect Android 2.0 (previously the Eclair branch). This is merely a copy
  of android-4 that also includes headers and libraries for OpenGL ES 2.0.

  See the sample named "hello-gl2" for a *very* basic demonstration. Note that
  OpenGL ES 2.0 is currently *not* available from Java, and must be used
  through native code exclusively.

  IMPORTANT: OpenGL ES 2.0 is not supported in the Android emulator at this
             time. Running/testing any native code that depends on it thus
             requires a real device.

- The NDK build script will now remove installed binaries from the application
  project's path before starting the build. This ensures that:

  - if the build fails for some reason, a stale/obsolete file is not left in
    your application project tree by mistake.

  - if you change the target ABI, a stale/obsolete file is not left into the
    folder corresponding to the old ABI.


- Updated the STABLE-APIS.html document to clarify the OpenGL ES 1.0/1.1/2.0
  issues regarding specific devices (i.e. 1.0 supported everywhere, 1.1 and
  2.0 on specific devices only, need for <uses-feature> tag in manifest).


OTHER FIXES AND CHANGES:

- Actually use the awk version detected by host-setup.sh during the build.

- Only allow undefined symbols when LOCAL_ALLOW_UNDEFINED_SYMBOLS is set
  to 'true', just like the documentation says it works. Also fix a typo
  in CLEAR_VARS that prevented this variable from being cleared properly.

- Simplified build/tools/make-release.sh, the --prebuilt-dir option is
  gone, and --help will dump a clearer description of expected options
  and input files.

- Added --prebuilt-ndk=FILE option to build/tools/make-release.sh script to
  package a new experimental NDK package archive from the current source tree
  plus the toolchain binaries of an existing NDK release package. E.g.:

    build/tools/make-release.sh \
       --prebuilt-ndk=/path/to/android-ndk-1.6_r1-linux-x86.zip

  will generate a new NDK package in /tmp/ndk-release that contains the most
  up-to-date build scripts, plus the toolchain binaries from 1.6_r1 (which
  are not in the git repository).

  Also added the --no-git option to collect all sources from the current
  NDK root directory, instead of the list given by 'git ls-files'. This can
  be useful if you don't want to checkout the whole 'platform/development'
  project from repo and still work on the NDK.

  This change is to help people easily package experimental NDK releases to
  test and distribute fixes and improvements.

- Remove bash-isms from build/tools/build-toolchain.sh. Now it's possible to
  build it with the 'dash' shell on Debian-based systems (tested on Ubuntu 8.04)

- Remove bash-ism from build/tools/build-ndk-sysroot.sh

- Refresh C library headers for all platforms:

    - make <endian.h> simply include <sys/endian.h>
    - make <stdint.h> properly declare 64-bit integer types with a C99 compiler
    - add missing <sys/types.h> to <strings.h>
    - add GLibc-compatible macro aliases (st_atimensec, st_mtimensec and
      st_ctimensec) to <stat.h>
    - add missing declaration for tzset() in <time.h>

- Added build/tools/download-toolchain-sources.sh, a script that allows you
  to download the toolchain sources from the official open-source repository
  at android.git.kernel.org and nicely package them into a tarball that can
  later be used by build/tools/build-toolchain.sh to rebuild the prebuilt
  binaries for your system.

- Updated build/tools/build-toolchain.sh to support the tarballs generated
  by download-toolchain-sources.sh with the --package=<file> option. This
  also builds both gcc 4.2.1 and 4.4.0, adding support for armeabi-v7a to
  gcc 4.4.0.

-------------------------------------------------------------------------------
android-ndk-1.6_r1

IMPORTANT BUG FIXES:

- Fix build/host-setup.sh to:
  * execute as a Bourne shell script
  * remove unused host gcc dependency
  * improve Windows host auto-detection
  * add GNU Make version check
  * add Nawk/Gawk check
  * ensure that the script is run from $NDKROOT as build/host-setup.sh
  * add --help, --verbose, --no-awk-check and --no-make-check options

- Properly add sysroot library search path at build time. This makes a line
  in Android.mk like:

     LOCAL_LDLIBS := -lz

  Actually work correctly, instead of having the linker complaining that it
  could not find the corresponding libz.so library. Also clear LOCAL_LDLIBS
  in $(CLEAR_VARS) script.


IMPORTANT CHANGES:

- The 'sources' directory is gone. The NDK build system now looks for
  $(APP_PROJECT_PATH)/jni/Android.mk by default. You can override this with
  the new APP_BUILD_SCRIPT variable in Application.mk

  For example, the 'hello-jni' sample uses the following files:

    apps/hello-jni/project/jni/Android.mk
    apps/hello-jni/project/jni/hello-jni.c

  The 'apps/<name>' directory is still needed in this release though.

- Change LOCAL_CFLAGS / LOCAL_CPPFLAGS to work as in the full Android build
  system. This means that:

    - LOCAL_CFLAGS   is now used for *both* C and C++ sources  (was only for C)
    - LOCAL_CPPFLAGS is now used for C++ sources only (was for both C and C++)
    - LOCAL_CXXFLAGS is used like LOCAL_CPPFLAGS but is considered obsolete.
      (will disappear in next release)

  Also fixed APP_CPPFLAGS / APP_CFLAGS / APP_CXXFLAGS correspondingly.

- Rename build/platforms/android-1.5 to build/platforms/android-3 to match
  the Android API level instead of the marketing speak.

  Also add a new build/platforms/android-4, and make the build system select
  which platform to use based on the content of the project file named
  $(APP_PROJECT_PATH)/default.properties.

- Add OpenGL ES 1.x headers and libraries to the android-4 stable APIs.
  (NOTE: they are *not* available for android-3)

  Also provide a small port of the "San Angeles Observation" demo to show
  how to make a simple Android application that uses them.


OTHER FIXES AND CHANGES

- Ensure that the __ANDROID__ macro is always defined when building code
  with the NDK. Normally, the macro must be defined by the toolchain
  automatically to indicate that you're targeting the Android runtime.

  This works for the new arm-linux-androideabi toolchain, but there is
  a bug in the way we built the arm-eabi one, so add the flag manually
  through the NDK build script for it.

  Note that the ANDROID macro, is now deprecated. While it is still defined
  by the NDK, you should modify your code to test against __ANDROID__ instead!

- Generate thumb binaries by default.

- Add support for LOCAL_ARM_MODE in Android.mk.

- Add support for the '.arm' suffix in source file names to force the
  compilation of a single source in ARM (32-bit) mode.

- Generate proper unoptimized versions of binaries when APP_OPTIM := debug

- Add support for LOCAL_C_INCLUDES in Android.mk

- Fix compilation of assembler files (e.g. foo.S)

-------------------------------------------------------------------------------
android-ndk-1.5_r1 released.