From e23031c974c9b051ba639f9ad68f891e2ae87da3 Mon Sep 17 00:00:00 2001 From: David Friedman Date: Fri, 22 May 2015 03:20:03 -0700 Subject: Docs: Final CL for NDK-docs-onto-DAC, pulling all files into a single CL. Change-Id: I3867d70f9d669fa08cd7d533d79e02c15339d4ff --- docs/html-ndk/ndk/downloads/index.jd | 27 +- docs/html-ndk/ndk/guides/abis.jd | 493 ++++++++++++ docs/html-ndk/ndk/guides/android_mk.jd | 891 +++++++++++++++++++++ docs/html-ndk/ndk/guides/application_mk.jd | 241 ++++++ docs/html-ndk/ndk/guides/arch.jd | 31 + docs/html-ndk/ndk/guides/build.jd | 23 + docs/html-ndk/ndk/guides/concepts.jd | 301 +++++++ docs/html-ndk/ndk/guides/cpp-support.jd | 328 ++++++++ docs/html-ndk/ndk/guides/cpu-arm-neon.jd | 109 +++ docs/html-ndk/ndk/guides/cpu-features.jd | 210 +++++ docs/html-ndk/ndk/guides/debug.jd | 17 + docs/html-ndk/ndk/guides/guides_toc.cs | 61 +- .../ndk/guides/images/NDK_build_string.png | Bin 0 -> 22494 bytes .../ndk/guides/images/NDK_build_string@2x.png | Bin 0 -> 44014 bytes .../ndk/guides/images/verification_screen.png | Bin 0 -> 56991 bytes .../ndk/guides/images/verification_screen@2x.png | Bin 0 -> 287252 bytes docs/html-ndk/ndk/guides/index.jd | 17 +- docs/html-ndk/ndk/guides/libs.jd | 20 + .../ndk/guides/md_1__concepts__concepts.html | 4 - docs/html-ndk/ndk/guides/mips.jd | 43 + docs/html-ndk/ndk/guides/ndk-build.jd | 194 +++++ docs/html-ndk/ndk/guides/ndk-gdb.jd | 241 ++++++ docs/html-ndk/ndk/guides/ndk-stack.jd | 84 ++ docs/html-ndk/ndk/guides/prebuilts.jd | 145 ++++ docs/html-ndk/ndk/guides/sample.jd | 11 + docs/html-ndk/ndk/guides/sample_hellojni.jd | 122 +++ docs/html-ndk/ndk/guides/sample_na.jd | 194 +++++ docs/html-ndk/ndk/guides/sample_teapot.jd | 236 ++++++ docs/html-ndk/ndk/guides/setup.html | 520 ++++++++++++ docs/html-ndk/ndk/guides/stable_apis.jd | 501 ++++++++++++ docs/html-ndk/ndk/guides/standalone_toolchain.jd | 575 +++++++++++++ docs/html-ndk/ndk/guides/x86-64.jd | 52 ++ docs/html-ndk/ndk/guides/x86.jd | 215 +++++ 33 files changed, 5895 insertions(+), 11 deletions(-) create mode 100644 docs/html-ndk/ndk/guides/abis.jd create mode 100644 docs/html-ndk/ndk/guides/android_mk.jd create mode 100644 docs/html-ndk/ndk/guides/application_mk.jd create mode 100644 docs/html-ndk/ndk/guides/arch.jd create mode 100644 docs/html-ndk/ndk/guides/build.jd create mode 100644 docs/html-ndk/ndk/guides/concepts.jd create mode 100644 docs/html-ndk/ndk/guides/cpp-support.jd create mode 100644 docs/html-ndk/ndk/guides/cpu-arm-neon.jd create mode 100644 docs/html-ndk/ndk/guides/cpu-features.jd create mode 100644 docs/html-ndk/ndk/guides/debug.jd create mode 100644 docs/html-ndk/ndk/guides/images/NDK_build_string.png create mode 100644 docs/html-ndk/ndk/guides/images/NDK_build_string@2x.png create mode 100644 docs/html-ndk/ndk/guides/images/verification_screen.png create mode 100644 docs/html-ndk/ndk/guides/images/verification_screen@2x.png create mode 100644 docs/html-ndk/ndk/guides/libs.jd delete mode 100644 docs/html-ndk/ndk/guides/md_1__concepts__concepts.html create mode 100644 docs/html-ndk/ndk/guides/mips.jd create mode 100644 docs/html-ndk/ndk/guides/ndk-build.jd create mode 100644 docs/html-ndk/ndk/guides/ndk-gdb.jd create mode 100644 docs/html-ndk/ndk/guides/ndk-stack.jd create mode 100644 docs/html-ndk/ndk/guides/prebuilts.jd create mode 100644 docs/html-ndk/ndk/guides/sample.jd create mode 100644 docs/html-ndk/ndk/guides/sample_hellojni.jd create mode 100644 docs/html-ndk/ndk/guides/sample_na.jd create mode 100644 docs/html-ndk/ndk/guides/sample_teapot.jd create mode 100644 docs/html-ndk/ndk/guides/setup.html create mode 100644 docs/html-ndk/ndk/guides/stable_apis.jd create mode 100644 docs/html-ndk/ndk/guides/standalone_toolchain.jd create mode 100644 docs/html-ndk/ndk/guides/x86-64.jd create mode 100644 docs/html-ndk/ndk/guides/x86.jd diff --git a/docs/html-ndk/ndk/downloads/index.jd b/docs/html-ndk/ndk/downloads/index.jd index ef00069ed881..a8ca73d9ffa1 100644 --- a/docs/html-ndk/ndk/downloads/index.jd +++ b/docs/html-ndk/ndk/downloads/index.jd @@ -1,4 +1,25 @@ -page.title=NDK Downloads -@jd:body +ndk=true +page.template=sdk + +ndk.mac64_download=android-ndk-r10e-darwin-x86_64.bin +ndk.mac64_bytes=388937326 +ndk.mac64_checksum=2cb8893a5701603519d38a7e04c50e81 + +ndk.linux64_download=android-ndk-r10e-linux-x86_64.bin +ndk.linux64_bytes=401522849 +ndk.linux64_checksum=19af543b068bdb7f27787c2bc69aba7f + +ndk.linux32_download=android-ndk-r10e-linux-x86.bin +ndk.linux32_bytes=394281908 +ndk.linux32_checksum=c3edd3273029da1cbd2f62c48249e978 -

downloads \ No newline at end of file +ndk.win64_download=android-ndk-r10e-windows-x86_64.exe +ndk.win64_bytes=419616132 +ndk.win64_checksum=8412bb4991a95e08fda50b5a44d95df7 + +ndk.win32_download=android-ndk-r10e-windows-x86.exe +ndk.win32_bytes=396563176 +ndk.win32_checksum=1a82445baaf62aec3a46386ab1e5772c + +page.title=NDK Downloads +@jd:body \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/abis.jd b/docs/html-ndk/ndk/guides/abis.jd new file mode 100644 index 000000000000..81604b5eefeb --- /dev/null +++ b/docs/html-ndk/ndk/guides/abis.jd @@ -0,0 +1,493 @@ +page.title=ABI Management +@jd:body + +

+ +
+ +

Different Android handsets use different CPUs, which in turn support different instruction sets. +Each combination of CPU and instruction set(s) has its own Application Binary Interface, or +ABI. The ABI defines, with great precision, how an application's machine code is supposed to +interact with the system at runtime. You must specify an ABI for each CPU architecture you want +your app to work with.

+ +

A typical ABI includes the following information:

+ + + +

This page enumerates the ABIs that the NDK supports, and provides information about how each ABI +works.

+ +

Supported ABIs

+ +

Each ABI supports one or more instruction sets. Table 1 provides an at-a-glance overview of +the instruction sets each ABI supports.

+ +

+ Table 1. ABIs and supported instruction sets.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ABISupported Instruction Set(s)Notes
{@code armeabi}
  • ARMV5TE and later
    • +
  • Thumb-1
    		• No hard float.
    {@code armeabi-v7a} +
  • armeabi
    • +
  • Thumb-2
    • +
  • VFPv3-D16
    • +
  • Other, optional
    		• Hard float when specified as {@code armeabi-v7a-hard}. +Incompatible with ARMv5, v6 devices.
    {@code arm64-v8a}
  • AArch-64
    • +{@code x86}
  • x86 (IA-32)
    • +
  • MMX
    • +
  • SSE/2/3
    • +
  • SSSE3
    		• No support for MOVBE or SSE4.
    {@code x86_64} +
  • x86-64
    • +
  • MMX
    • +
  • SSE/2/3
    • +
  • SSSE3
    • +
  • SSE4.1, 4.2
    • +
  • POPCNT
    • {@code mips}
  • MIPS32r1 and later
    		• Uses hard-float, and assumes a CPU:FPU clock ratio of 2:1 for maximum +compatibility. Provides neither micromips nor MIPS16.
    {@code mips64}
  • MIPS64r6
    		•  +
    + +

    More detailed information about each ABI appears below.

    + +

    armeabi

    +

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

    + + + +

    The AAPCS standard defines EABI as a family of similar +but distinct ABIs. Also, Android follows the little-endian + +ARM GNU/Linux ABI.

    + +

    This ABI does not support hardware-assisted floating point +computations. Instead, all floating-point operations use software helper +functions from the compiler's {@code libgcc.a} static library.

    + +

    The armeabi ABI supports ARM’s + +Thumb (a.k.a. Thumb-1) instruction set. The NDK generates Thumb +code by default unless you specify different behavior using the +LOCAL_ARM_MODE variable in your Android.mk +file.

    + +

    armeabi-v7a (armeabi-v7a-hard)

    +

    This ABI extends armeabi to include several + +CPU instruction set extensions. The instruction extensions that this Android-specific +ABI supports are:

    + + + +

    Other extensions that the v7-a ARM spec describes, including + +Advanced SIMD (a.k.a. NEON), VFPv3-D32, and ThumbEE, are optional +to this ABI. Since their presence is not guaranteed, the system should check at runtime +whether the extensions are available. If they are not, you must use alternative code paths. This +check is similar to the one that the system typically performs to check or use +MMX, +SSE2, and other specialized +instruction sets on x86 CPUs.

    + +

    For information about how to perform these runtime checks, refer to +CPU Features. +Also, for information about the NDK's support for building +machine code for NEON, see +NEON Support.

    + +

    The {@code armeabi-v7a} ABI uses the {@code -mfloat-abi=softfp} switch to +enforce the rule that the compiler must pass all double values in core register pairs during +function calls, instead of dedicated floating-point ones. The system can perform all internal +computations using the FP registers. Doing so speeds up the computations greatly.

    + +

    Although the requirement to use core register pairs produces a modest performance hit, it ensures +compatibility with all existing armeabi binaries. If you need the additional +performance, you can specify your ABI as {@code armeabi-v7a-hard} instead. Doing so +allows you to use hard floats, while still linking with Android native APIs +that use {@code softfp}. For more information, refer to the comments in +{@code $NDK/tests/device/hard-float/jni/android.mk}.

    + +

    Note: You cannot specify {@code APP_ABI} as both +{@code armeabi-v7a} and {@code armeabi-v7a-hard}. In either case, the build system places the +shared libraries in the {@code armeabi-v7a/} directory.

    + +

    armeabi-v7a-hard

    +

    This variant of the {@code armeabi-v7a} ABI is unique to the NDK. The NDK build +system adds the following flags in addition to those that it uses for the +{@code armeabi-v7a} ABI:

    + +
    +TARGET_CFLAGS += -mhard-float -D_NDK_MATH_NO_SOFTFP=1
+TARGET_LDFLAGS += -Wl,--no-warn-mismatch -lm_hard
+
    + +

    The compiler compiles all code with hard-float, and links it with {@code libm_hard.a}. +This math library is the same one as {@code libm.a}, except that it follows hard-float ABI +conventions. In the APK, the generated shared libraries reside in {@code /lib/armeabi-v7a/}.

    + +

    arm64-v8a

    +

    This ABI is for ARMv8-based CPUs that support AArch64. It also includes the NEON and +VFPv4 instruction sets.

    + +

    For more information, see the +ARMv8 +Technology Preview, and contact ARM for further details.

    + +

    x86

    +

    This ABI is for CPUs supporting the instruction set commonly +referred to as "x86" or "IA-32". Characteristics of this ABI include:

    + + + +

    The ABI does not include any other optional IA-32 instruction set +extensions, such as:

    + +

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

    +

    The NDK toolchain assumes 16-byte stack alignment before a function call. The default tools and +options enforce this rule. If you are writing assembly code, you must make sure to maintain stack +alignment, and ensure that other compilers also obey this rule.

    + +

    Refer to the following documents for more details:

    + + +

    x86_64

    +

    This ABI is for CPUs supporting the instruction set commonly referred to as +"x86-64." It supports instructions that GCC typically generates with the following +compiler flags:

    +
    +-march=x86-64 -msse4.2 -mpopcnt -m64 -mtune=intel
+
    + +

    These flags target the x86-64 instruction set, according to the GCC +documentation. along with the +MMX, +SSE, +SSE2, +SSE3, +SSSE3, +SSE4.1, +SSE4.2, and +POPCNT +instruction-set extensions. The generated code is an optimization balanced +across the top Intel 64-bit CPUs.

    + +

    For more information on compiler flags, particularly related to performance optimization, +refer to GCC +x86 Performance.

    + +

    This ABI does not include any other optional x86-64 instruction set +extensions, such as:

    + + + +

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

    +

    Refer to the following documents for more details:

    + + + +

    mips

    +

    This ABI is for MIPS-based CPUs that support at least the MIPS32r1 instruction set. It includes +the following features:

    + + + +

    For more information, please refer to the following documentation:

    + + + +

    The MIPS-specific documentation is available +here, with +further information +here.

    + + + +

    mips64

    +

    This ABI is for MIPS64 R6. For more information, see +MIPS Architecture.

    + +

    Generating Code for a Specific ABI

    +

    By default, the NDK generates machine code for the armeabi ABI. You can +generate ARMv7-a-compatible machine code, instead, by adding the following line +to your {@code Application.mk} file.

    +
    +APP_ABI := armeabi-v7a
+
    + +

    To build machine code for two or more distinct ABIs, using spaces as delimiters. For +example:

    + +
    +APP_ABI := armeabi armeabi-v7a
+
    + +

    This setting tells the NDK to build two versions of your machine code: one +for each ABI listed on this line. For more information on the values you can specify for the +{@code APP_ABI} variable, see Android.mk. +

    + +

    When you build multiple machine-code versions, the build system copies the libraries to your +application project path, and ultimately packages them into your APK, so creating +a fat binary. A fat binary +is larger than one containing only the machine code for a single system; the tradeoff is +gaining wider compatibility, but at the expense of a larger APK.

    + +

    At installation time, the package manager unpacks only the most appropriate +machine code for the target device. For details, see Automatic +extraction of native code at install time.

    + + +

    ABI Management on the Android Platform

    +

    This section provides details about how the Android platform manages native +code in APKs.

    + +

    Native code in app packages

    +

    Both the Play Store and Package Manager expect to find NDK-generated +libraries on filepaths inside the APK matching the following pattern:

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

    Here, {@code <abi>} is one of the ABI names listed under Supported ABIs, +and {@code <name>} is the name of the library as you defined it for the {@code LOCAL_MODULE} +variable in the {@code Android.mk} file. Since +APK files are just zip files, it is trivial to open them and confirm that the shared native +libraries are where they belong.

    + +

    If the system does not find the native shared libraries where it expects them, it cannot use +them. In such a case, the app itself has to copy the libraries over, and then +perform dlopen().

    + +

    In a fat binary, each library resides under a directory whose name matches a corresponding ABI. +For example, a fat binary may contain:

    + +
    +/lib/armeabi/libfoo.so
+/lib/armeabi-v7a/libfoo.so
+/lib/arm64-v8a/libfoo.so
+/lib/x86/libfoo.so
+/lib/x86_64/libfoo.so
+/lib/mips/libfoo.so
+/lib/mips64/libfoo.so
+
    + +

    Note: ARMv7-based Android devices running 4.0.3 or earlier +install native libraries from the {@code armeabi} directory instead of the {@code armeabi-v7a} +directory if both directories exist. This is because {@code /lib/armeabi/} comes after +{@code /lib/armeabi-v7a/} in the APK. This issue is fixed from 4.0.4.

    + +

    Android Platform ABI support

    +

    The Android system knows at runtime which ABI(s) it supports, because build-specific system +properties indicate:

    + + + +

    This mechanism ensures that the system extracts the best machine code from +the package at installation time.

    + +

    For best performance, you should compile directly for the primary ABI. For example, a +typical ARMv5TE-based device would only define the primary ABI: {@code armeabi}. By contrast, a +typical, ARMv7-based device would define the primary ABI as {@code armeabi-v7a} and the secondary +one as {@code armeabi}, since it can run application native binaries generated for each of them.

    + +

    Many x86-based devices can also run {@code armeabi-v7a} and {@code armeabi} NDK binaries. For +such devices, the primary ABI would be {@code x86}, and the second one, {@code armeabi-v7a}.

    + +

    A typical MIPS-based device only defines a primary abi: {@code mips}.

    + +

    Automatic extraction of native code at install time

    + +

    When installing an application, the package manager service scans the APK, and looks for any +shared libraries of the form:

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

    If none is found, and you have defined a secondary ABI, the service scans for shared libraries of +the form:

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

    When it finds the libraries that it's looking for, the package manager +copies them to /lib/lib<name>.so, under the application's +{@code data} directory ({@code data/data/<package_name>/lib/}).

    + +

    If there is no shared-object file at all, the application builds and installs, but crashes at +runtime.

    \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/android_mk.jd b/docs/html-ndk/ndk/guides/android_mk.jd new file mode 100644 index 000000000000..da946794f05c --- /dev/null +++ b/docs/html-ndk/ndk/guides/android_mk.jd @@ -0,0 +1,891 @@ +page.title=Android.mk +@jd:body + +
    + +
    + + +

    This page describes the syntax of the {@code Android.mk} build file, +which glues your C and C++ source files to the Android NDK.

    + +

    Overview

    +

    The {@code Android.mk} file resides in a subdirectory of your project's {@code jni/} directory, +and describes your sources and shared libraries to the build system. It is really a tiny GNU +makefile fragment that the build system parses once or more. The {@code Android.mk} file is useful +for defining project-wide settings that {@code Application.mk}, the build system, and your +environment variables leave undefined. It can also override project-wide settings for specific +modules.

    + +

    The syntax of the {@code Android.mk} allows you to group your sources into +modules. A module is either a static library, a shared library, or a standalone +executable. You can define one or more modules in each {@code Android.mk} file, and +you can use the same source file in multiple modules. The build system only places shared libraries +into your application package. In addition, static libraries can generate shared libraries.

    + +

    In addition to packaging libraries, the build system handles a variety of other details for you. +For example, you don't need to list header files or explicit dependencies between generated files in +your {@code Android.mk} file. The NDK build system computes these relationships automatically for +you. As a result, you should be able to benefit from new toolchain/platform support in future NDK +releases without having to touch your {@code Android.mk} file.

    + +

    The syntax of this file is very close to that used in the {@code Android.mk} files distributed with +the full Android Open Source Project. While the +build system implementation that uses them is different, their similarity is an +intentional design decision aimed at making it easier for application +developers to reuse source code for external libraries.

    + +

    Basics

    +

    Before exploring the syntax in detail, it is useful to start by understanding the basics +of what a {@code Android.mk} file contains. This section uses the {@code Android.mk} file in the +Hello-JNI sample toward that end, explaining the role that each line in the file plays.

    + + +

    An {@code Android.mk} file must begin by defining the {@code LOCAL_PATH} variable: + +

    +LOCAL_PATH := $(call my-dir)
+
    + +

    This variable indicates the location of the source files in the development tree. Here, the macro +function {@code my-dir}, provided by the build system, returns the path of the current directory +(the directory containing the {@code Android.mk} file itself).

    + +

    The next line declares the {@code CLEAR_VARS} variable, whose value the build system provides. + +

    +include $(CLEAR_VARS)
+
    + +

    The {@code CLEAR_VARS} variable points to a special GNU Makefile that clears many +{@code LOCAL_XXX} variables for you, such as {@code LOCAL_MODULE}, {@code LOCAL_SRC_FILES}, and +{@code LOCAL_STATIC_LIBRARIES}. Note that it does not clear {@code LOCAL_PATH}. This variable must +retain its value because the system parses all build control files in a single GNU Make execution +context where all variables are global. You must (re-)declare this variable before describing each +module.

    + +

    Next, the {@code LOCAL_MODULE} variable stores the name of the module that you wish to build. +Use this variable once per module in your application.

    + +
    +LOCAL_MODULE := hello-jni
+
    + +

    Each module name must be unique and not contain any spaces. The build system, when it +generates the final shared-library file, automatically adds the proper prefix and suffix to +the name that you assign to {@code LOCAL_MODULE|. For example, the example that appears above +results in generation of a library called {@code libhello-jni.so}.

    + +

    Note: If your module's name already starts with {@code lib}, the +build system does not prepend an additional {@code lib} prefix; it takes the module name as-is, and +adds the {@code .so} extension. So a source file originally called, for example, {@code libfoo.c} +still produces a shared-object file called {@code libfoo.so}. This behavior is to support libraries +that the Android platform sources generate from {@code Android.mk} files; the names of all such +libraries start with {@code lib}.

    + +

    The next line enumerates the source files, with spaces delimiting multiple files:

    + +
    +LOCAL_SRC_FILES := hello-jni.c
+
    + +

    The {@code LOCAL_SRC_FILES} variable must contain a list of C and/or C++ source files to build +into a module.

    + +

    The last line helps the system tie everything together:

    + +
    +include $(BUILD_SHARED_LIBRARY)
+
    + +

    The {@code BUILD_SHARED_LIBRARY} variable points to a GNU Makefile script that collects all the +information you defined in {@code LOCAL_XXX} variables since the most recent {@code include}. This +script determines what to build, and how to do it.

    + +

    There are more complex examples in the samples directories, with commented +{@code Android.mk} files that you can look at. In addition, the +walkthrough of the native-activity sample +disucsses that sample's {@code Android.mk} file in some detail. Finally, the next section explains +the variables from this section in a bit more detail. + + +

    Variables and Macros

    +

    The build system provides many possible variables for use in the the {@code Android.mk} file. +Many of these variables come with preassigned values. Others, you assign.

    + +

    In addition to these variables, you can also define your own arbitrary ones. If you do so, keep +in mind that the NDK build system reserves the following variable names:

    + +

    If you need to define your own convenience variables in an {@code Android.mk} file, we +recommend prepending {@code MY_} to their names. + + +

    NDK-defined variables

    +

    This section discusses the GNU Make variables that the build system defines before parsing your +{@code Android.mk} file. Under certain circumstances, the NDK might parse your {@code Android.mk} +file several times, using a different definition for some of these variables each time.

    + +

    CLEAR_VARS

    +

    This variable points to a build script that undefines nearly all {@code LOCAL_XXX} variables +listed in the "Developer-defined variables" section below. Use this variable to include +this script before describing a new module. The syntax for using it is:

    + +
    +include $(CLEAR_VARS)
+
    + +

    BUILD_SHARED_LIBRARY

    +

    This variable points to a build script that collects all the information about the module +you provided in your {@code LOCAL_XXX} variables, and determines how to build a target shared +library from the sources you listed. Note that using this script requires that you have already +assigned values to {@code LOCAL_MODULE} and {@code LOCAL_SRC_FILES}, at a minimum (for more +information about these variables, see Module-description variables).

    + +

    The syntax for using this variable is:

    + +
    +include $(BUILD_SHARED_LIBRARY)
+
    + +

    A shared-library variable causes the build system to generate a library file with a {@code .so} +extension.

    + +

    BUILD_STATIC_LIBRARY

    +

    A variant of {@code BUILD_SHARED_LIBRARY} that is used to build a static library. The build +system does not copy static libraries into your project/packages, but it can use them to build +shared libraries (see {@code LOCAL_STATIC_LIBRARIES} and {@code LOCAL_WHOLE_STATIC_LIBRARIES}, +below). The syntax for using this variable is:

    + +
    +include $(BUILD_STATIC_LIBRARY)
+
    + +

    A static-library variable causes the build system to generate a library with a {@code .a} +extension.

    + +

    PREBUILT_SHARED_LIBRARY

    +

    Points to a build script used to specify a prebuilt shared library. Unlike in the case of +{@code BUILD_SHARED_LIBRARY} and {@code BUILD_STATIC_LIBRARY}, here the value of +{@code LOCAL_SRC_FILES} cannot be a source file. Instead, it must be a single path to a prebuilt +shared library, such as {@code foo/libfoo.so}. The syntax for using this variable is:

    + +
    +include $(PREBUILT_SHARED_LIBRARY)
+
    + +

    You can also reference a prebuilt library in another module by using the +{@code LOCAL_PREBUILTS} variable. The following example shows an example of using +{@code LOCAL_PREBUILTS}: + + + +

    For more information about using prebuilts, see +NDK Prebuilt Library Support.

    + + +

    PREBUILT_STATIC_LIBRARY

    +

    The same as {@code PREBUILT_SHARED_LIBRARY}, but for a prebuilt static library. For more +information about using prebuilts, see NDK Prebuilt +Library Support.

    + +

    TARGET_ARCH

    +

    The name of the target CPU architecture as the Android Open Source Project specifies it. +For any ARM-compatible build, use {@code arm}, independent of the CPU architecture revision or +ABI (see TARGET_ARCH_ABI, below).

    + +

    The value of this variable is taken from the APP_ABI variable that you define in the +{@code Android.mk} file, which the system +reads ahead of parsing the {@code Android.mk} file.

    + +

    TARGET_PLATFORM

    +

    The Android API level number for the build system to target. +For example, the Android 5.1 system images correspond to Android API level 22: {@code android-22}. +For a complete list of platform names and corresponding Android system +images, see Android NDK Stable APIs. +The following example shows the syntax for using this variable:

    + +
    +TARGET_PLATFORM := android-22
+
    + +

    TARGET_ARCH_ABI

    +

    This variable stores the name of the CPU and architecture to target when the build system +parses this {@code Android.mk} file. You can specify one or more of the following values, using +a space as a delimiter between multiple targets. Table 1 shows the ABI setting to use for each +supported CPU and architecture. + +

    + Table 1. ABI settings for different CPUs and architectures.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    CPU and architectureSetting
    ARMv5TE{@code armeabi}
    ARMv7{@code armeabi-v7a}
    ARMv8 AArch64{@code arm64-v8a}
    i686{@code x86}
    x86-64{@code x86_64}
    mips32 (r1){@code mips}
    mips64 (r6){@code mips64}
    All{@code all}
    + +

    The following example shows how to set ARMv8 AArch64 as the target CPU-and-ABI combination:

    + +
    +TARGET_ARCH_ABI := arm64-v8a
+
    + +

    Note: Up to Android NDK 1.6_r1, this variable is defined as +{@code arm}.

    + +

    For more details about architecture ABIs and associated compatibility +issues, refer to + +Android Native CPU ABI Management

    + +

    New target ABIs in the future will have different values.

    + +

    TARGET_ABI

    +

    A concatenation of target Android API level and ABI, it is especially useful when you want to test against +a specific target system image for a real device. For example, to specify a 64-bit ARM device +running on Android API level 22:

    + +
    +TARGET_ABI := android-22-arm64-v8a
+
    + +

    Note: Up to Android NDK 1.6_r1, the default value was +{@code android-3-arm}.

    + +

    Module-description variables

    +

    The variables in this section describe your module to the build system. Each module description +should follow this basic flow: +

    + +

    LOCAL_PATH

    +

    This variable is used to give the path of the current file. You must define +it at the start of your {@code Android.mk} file. The following example shows how to do so:

    + +
    +LOCAL_PATH := $(call my-dir)
+
    + +

    The script to which {@code CLEAR_VARS} points does not clear this variable. Therefore, you only need +to define it a single time, even if your {@code Android.mk} file describes multiple modules.

    + +

    LOCAL_MODULE

    +

    This variable stores the name of your module. It must be unique among all module names, +and must not contain any spaces. You must define it before including any scripts (other than +the one for {@code CLEAR_VARS}). You need not add either the {@code lib} prefix +or the {@code .so} or {@code .a} file extension; the build system makes these modifications +automatically. Throughout your {@code Android.mk} and {@code Application.mk} files, refer to +your module by its unmodified name. For example, the following line results in the generation of a +shared library module called {@code libfoo.so}:

    + +
    +LOCAL_MODULE := "foo"
+
    + +

    If you want the generated module to have a name other than {@code lib} + the value of +{@code LOCAL_MODULE}, you can use the {@code LOCAL_MODULE_FILENAME} variable to give the +generated module a name of your own choosing, instead.

    + +

    LOCAL_MODULE_FILENAME

    +

    This optional variable allows you to override the names that the build system +uses by default for files that it generates. For example, if the name of your {@code LOCAL_MODULE} +is {@code foo}, you can force the system to call the file it generates {@code libnewfoo}. The +following example shows how to accomplish this:

    + +
    +LOCAL_MODULE := foo
+LOCAL_MODULE_FILENAME := libnewfoo
+
    + +

    For a shared library module, this example would generate a file called {@code libnewfoo.so}.

    + +

    Note: You cannot override filepath or file extension.

    + +

    LOCAL_SRC_FILES

    +

    This variable contains the list of source files that the build system uses to generate the +module. Only list the files that the build system actually passes to the compiler, since the build +system automatically computes any associated depencies.

    +

    Note that you can use both relative (to {@code LOCAL_PATH}) and absolute file paths. + +

    We recommend avoiding absolute file paths; relative paths make your +{@code Android.mk} file more +portable.

    + +

    Note: Always use Unix-style forward slashes (/) in build files. +The build system does not handle Windows-style backslashes (\) properly.

    + +

    LOCAL_CPP_EXTENSION

    +

    You can use this optional variable to indicate a file extension other than {@code .cpp} for your +C++ source files. For example, the following line changes the extension to {@code .cxx}. +(The setting must include the dot.) + +

    +LOCAL_CPP_EXTENSION := .cxx
+
    + +

    From NDK r7, you can use this variable to specify multiple extensions. For instance:

    + +
    +LOCAL_CPP_EXTENSION := .cxx .cpp .cc
+
    + +

    LOCAL_CPP_FEATURES

    + +

    You can use this optional variable to indicate that your code relies on specific C++ features. +It enables the right compiler and linker flags during the build process. For prebuilt binaries, +this variable also declares which features the binary depends on, thus helping ensure the final +linking works correctly. We recommend that you use this variable instead of enabling +{@code -frtti} and {@code -fexceptions} directly in your {@code LOCAL_CPPFLAGS} definition.

    + +

    Using this variable allows the build system to use the appropriate flags for each module. Using +{@code LOCAL_CPPFLAGS} causes the compiler to use all specified flags for all modules, regardless +of actual need.

    + +For example, to indicate that your code uses RTTI (RunTime Type Information), write:

    + +
    +LOCAL_CPP_FEATURES := rtti
+
    + +

    To indicate that your code uses C++ exceptions, write:

    + +
    +LOCAL_CPP_FEATURES := exceptions
+
    + +

    You can also specify multiple values for this variable. For example:

    + +
    +LOCAL_CPP_FEATURES := rtti features
+
    + +The order in which you describe the values does not matter. + + +

    LOCAL_C_INCLUDES

    +

    You can use this optional variable to specify a list of paths, relative to the +NDK {@code root} directory, to add to the include search path when compiling all sources +(C, C++ and Assembly). For example:

    + +
    +LOCAL_C_INCLUDES := sources/foo
+
    + +

    Or even:

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

    Define this variable before setting any corresponding inclusion flags via {@code LOCAL_CFLAGS} +or {@code LOCAL_CPPFLAGS}.

    + +

    The build system also uses {@code LOCAL_C_INCLUDES} paths automatically when launching native +debugging with ndk-gdb.

    + + +

    LOCAL_CFLAGS

    + +

    This optional variable sets compiler flags for the build system to pass when building C +and C++ source files. The ability to do so can be useful for specifying additional macro +definitions or compile options.

    + +

    Try not to change the optimization/debugging level in your {@code Android.mk} file. +The build system can handle this setting automatically for you, using the relevant information +in the {@code Application.mk} file. Doing it this way allows the build system to generate useful +data files used during debugging.

    + +

    Note: In android-ndk-1.5_r1, the corresponding flags only applied +to C source files, not C++ ones. They now match the full Android build system behavior. +(You can now use {@code LOCAL_CPPFLAGS} to specify flags for C++ sources only.)

    + +

    It is possible to specify additional include paths by writing: + +

    +LOCAL_CFLAGS += -I<path>,
+
    + +It is better, however, to use {@code LOCAL_C_INCLUDES} for this purpose, since +doing so also makes it possible to use the paths available for native debugging with ndk-gdb.

    + + +

    LOCAL_CPPFLAGS

    +

    An optional set of compiler flags that will be passed when building C++ +source files only. They will appear after the LOCAL_CFLAGS on the +compiler's command-line.

    + + +

    Note: In android-ndk-1.5_r1, the corresponding flags applied to +both C and C++ sources. This has been corrected to match the full Android build system. +To specify flags for both C and C++ sources, use {@code LOCAL_CFLAGS}.

    + + +

    LOCAL_STATIC_LIBRARIES

    + +

    This variable stores the list of static libraries modules on which the current module depends.

    + +

    If the current module is a shared library or an executable, this variable will force +these libraries to be linked into the resulting binary.

    + +

    If the current module is a static library, this variable simply indicates that other +modules depending on the current one will also depend on the listed +libraries.

    + +

    LOCAL_SHARED_LIBRARIES

    + +

    This variable is the list of shared libraries modules on which this module depends at +runtime. This information is necessary at link time, and to embed the corresponding information +in the generated file.

    + +

    LOCAL_WHOLE_STATIC_LIBRARIES

    +

    This variable is a variant of {@code LOCAL_STATIC_LIBRARIES}, and expresses that the linker +should treat the associated library modules as whole archives. For more information +on whole archives, see the GNU linker's +documentation for the +{@code --whole-archive} flag.

    + +

    This variable is useful when there are circular dependencies among +several static libraries. When you use this variable to build a shared library, it will force +the build system to add all object files from your static libraries to the final binary. The same +is not true, however, when generating executables.

    + + +

    LOCAL_LDLIBS

    + +

    This variable contains the list of additional linker flags for use in building your shared +library or executable. It enables you to use the {@code -l} prefix to pass the name of specific +system libraries. For example, the following example tells the linker to generate a module that +links to {@code /system/lib/libz.so} at load time:

    + +
    +LOCAL_LDLIBS := -lz
+
    + +

    For the list of exposed system libraries against which you can link in this NDK release, see +Android NDK Stable APIs.

    + +

    Note: If you define this variable for a static library, +the build system ignores it, and {@code ndk-build} prints a warning.

    + +

    LOCAL_LDFLAGS

    + +

    The list of other linker flags for the build system to use when building your shared library +or executable. For example, the following example uses the {@code ld.bfd} linker on ARM/X86 GCC +4.6+, on which {@code ld.gold} is the default

    + +
    +LOCAL_LDFLAGS += -fuse-ld=bfd
+
    + +

    Note: If you define this variable for a static library, the build +system ignores it, and ndk-build prints a warning.

    + +

    LOCAL_ALLOW_UNDEFINED_SYMBOLS

    + +

    By default, when the build system encounters an undefined reference encountered while trying to +build a shared, it will throw an undefined symbol error. This error can help you catch +catch bugs in your source code.

    + +

    To disable this check, set this variable to {@code true}. Note that this setting may cause the +shared library to load at runtime.

    + +

    Note: If you define this variable for a static library, +the build system ignores it, and ndk-build prints a warning.

    + +

    LOCAL_ARM_MODE

    +

    By default, the build system generates ARM target binaries in thumb mode, where each +instruction is 16 bits wide and linked with the STL libraries in the {@code thumb/} directory. +Defining this variable as {@code arm} forces the build system to generate the module's object +files in 32-bit {@code arm} mode. The following example shows how to do this:

    + +
    +LOCAL_ARM_MODE := arm
+
    + +

    You can also instruct the build system to only build specific sources in {@code arm} mode by +appending {@code .arm} suffix to the the source filenames. For example, the following example +tells the build system to always compile {@code bar.c} in ARM mode, but to build +{@code foo.c} according to the value of {@code LOCAL_ARM_MODE}.

    + +
    +LOCAL_SRC_FILES := foo.c bar.c.arm
+
    + +

    + +

    Note: You can also force the build system to generate ARM binaries +by setting {@code APP_OPTIM} in your +Android +NDK & ARM NEON Instruction Set Extension Support and Android +NDK CPU Features Detection Library.

    + +

    Alternatively, you can use the {@code .neon} suffix to specify that the build system only +compile specific source files with NEON support. In the following example, the build system compiles +{@code foo.c} with thumb and neon support, {@code bar.c} with thumb support, and +{@code zoo.c} with support for ARM and NEON:

    + +
    +LOCAL_SRC_FILES = foo.c.neon bar.c zoo.c.arm.neon
+
    + + +

    If you use both suffixes, {@code .arm} must precede {@code .neon}.

    + +

    LOCAL_DISABLE_NO_EXECUTE

    + +

    Android NDK r4 added support for the "NX bit" security feature. It is +enabled by default, but you can disable it by setting this variable to {@code true}. We do not +recommend doing so without a compelling reason.

    + +

    This feature does not modify the ABI, and is only enabled on kernels +targeting ARMv6+ CPU devices. Machine code with this feature enabled +will run unmodified on devices running earlier CPU architectures.

    +

    For more information, see Wikipedia: NX bit +and The GNU stack kickstart. + +

    LOCAL_DISABLE_RELRO

    + +

    By default, the NDK compiles code with read-only relocations and GOT +protection. This variable instructs the runtime linker to mark certain regions of memory +as read-only after relocation, making certain security exploits (such as GOT overwrites) +more difficult. Note that these protections are only effective on Android API level 16 and higher. +On lower API levels, the code will still run, but without memory protections.

    + +

    This variable is turned on by default, but you can disable it by setting its value to +{@code true}. We do not recommend doing so without a compelling reason.

    + +

    For more information, see +RELRO: +RELocation Read-Only and Security +enhancements in RedHat Enterprise Linux (section 6).

    + +

    LOCAL_DISABLE_FORMAT_STRING_CHECKS

    + +

    By default, the build system compiles code with format string protection. Doing so forces a +compiler error if a non-constant format string is used in a {@code printf}-style function.

    +

    This protection is off by default, but you can disable it by setting its value to +{@code true}. We do not recommend doing so without a compelling reason.

    + + +

    LOCAL_EXPORT_CFLAGS

    + +

    This variable records a set of C/C++ compiler flags to add to the {@code LOCAL_CFLAGS} definition +of any other module that uses this one via the {@code LOCAL_STATIC_LIBRARIES} or +{@code LOCAL_SHARED_LIBRARIES} variables.

    + +

    For example, consider the following pair of modules: {@code foo} and {@code bar}, which depends +on {@code foo}:

    + +
    +include $(CLEAR_VARS)
+LOCAL_MODULE := foo
+LOCAL_SRC_FILES := foo/foo.c
+LOCAL_EXPORT_CFLAGS := -DFOO=1
+include $(BUILD_STATIC_LIBRARY)
+
+
+include $(CLEAR_VARS)
+LOCAL_MODULE := bar
+LOCAL_SRC_FILES := bar.c
+LOCAL_CFLAGS := -DBAR=2
+LOCAL_STATIC_LIBRARIES := foo
+include $(BUILD_SHARED_LIBRARY)
+
    + +

    Here, the build system passes the flags {@code -DFOO=1} and {@code -DBAR=2} to the compiler when +building {@code bar.c}. It also prepends exported flags to your your module's {@code LOCAL_CFLAGS} +so you can easily override them.

    + +In addition, the relationship among modules is transitive: If {@code zoo} depends on +{@code bar}, which in turn depends on {@code foo}, then {@code zoo} also inherits all flags +exported from {@code foo}.

    + +

    Finally, the build system does not use exported flags when building locally (i.e., building the +module whose flags it is exporting). Thus, in the example above, it does not pass {@code -DFOO=1} +to the compiler when building {@code foo/foo.c}. To build locally, use {@code LOCAL_CFLAGS} +instead.

    + +

    LOCAL_EXPORT_CPPFLAGS

    +

    This variable is the same as {@code LOCAL_EXPORT_CFLAGS}, but for C++ flags only.

    + +

    LOCAL_EXPORT_C_INCLUDES

    +

    This variable is the same as {@code LOCAL_EXPORT_CFLAGS}, but for C include paths. It is useful +in cases where, for example, {@code bar.c} needs to include headers from module {@code foo}.

    + +

    LOCAL_EXPORT_LDFLAGS

    +

    This variable is the same as {@code LOCAL_EXPORT_CFLAGS}, but for linker flags.

    + +

    LOCAL_EXPORT_LDLIBS

    +

    This variable is the same as {@code LOCAL_EXPORT_CFLAGS}, telling the build system to pass names +of specific system libraries to the compiler. Prepend {@code -l} to the name of each library you +specify.

    + +

    Note that the build system appends imported linker flags to the value of your module's +{@code LOCAL_LDLIBS} variable. It does this due to the way Unix linkers work.

    + +

    This variable is typically useful when module {@code foo} is a static library +and has code that depends on a system library. You can then use {@code LOCAL_EXPORT_LDLIBS} to +to export the dependency. For example:

    + +
    +include $(CLEAR_VARS)
+LOCAL_MODULE := foo
+LOCAL_SRC_FILES := foo/foo.c
+LOCAL_EXPORT_LDLIBS := -llog
+include $(BUILD_STATIC_LIBRARY)
+
+include $(CLEAR_VARS)
+LOCAL_MODULE := bar
+LOCAL_SRC_FILES := bar.c
+LOCAL_STATIC_LIBRARIES := foo
+include $(BUILD_SHARED_LIBRARY)
+
    + +

    In this example, the build system puts {@code -llog} at the end of the linker command when it +builds {@code libbar.so}. Doing so tells the linker that, because {@code libbar.so} depends +on {@code foo}, it also depends on the system logging library.

    + +

    LOCAL_SHORT_COMMANDS

    +

    Set this variable to {@code true} when your module has a very high +number of sources and/or dependent static or shared libraries. Doing so forces the +build system to use {@code @} syntax for archives containing intermediate object files +or linking libraries.

    + +

    This feature can be useful on Windows, where the command line accepts a maximum of only +of 8191 characters, which can be too small for complex projects. It also impacts the compilation of +individual source files, placing nearly all compiler flags inside list files, too.

    + +

    Note that any value other than {@code true} will revert to the +default behaviour. You can also define {@code APP_SHORT_COMMANDS} in your +{@code Application.mk} file to force this +behavior for all modules in your project.

    + +

    We do not recommend enabling this feature by default, since it makes the build slower.

    + + +

    LOCAL_THIN_ARCHIVE

    + +

    Set this variable to {@code true} when building static libraries. +Doing so will generate a thin archive, a library file that does not contain +object files, but instead just file paths to the actual objects that it would normally +contain.

    +

    This is useful to reduce the size of your build output. The drawback is that +such libraries cannot be moved to a different location (all paths +inside them are relative).

    +

    Valid values are {@code true}, {@code false} or empty. A +default value can be set in your {@code Application.mk} file through the {@code APP_THIN_ARCHIVE} + +variable.

    +

    Note: This is ignored for non-static library modules, or prebuilt +static library ones.

    + +

    LOCAL_FILTER_ASM

    +

    Define this variable as a shell command that the build system will use to filter the +assembly files extracted or generated from the files you specified for {@code LOCAL_SRC_FILES}.

    +

    Defining this variable causes the following things to occur:

    + + +

    For example:

    + +
    +LOCAL_SRC_FILES  := foo.c bar.S
+LOCAL_FILTER_ASM :=
+
+foo.c --1--> $OBJS_DIR/foo.S.original --2--> $OBJS_DIR/foo.S --3--> $OBJS_DIR/foo.o
+bar.S                                 --2--> $OBJS_DIR/bar.S --3--> $OBJS_DIR/bar.o
+
    + +

    "1" corresponds to the compiler, "2" to the filter, and "3" to the assembler. The filter must +be a standalone shell command that takes the name of the input file as its first argument, and the +name of the output file as the second one. For example:

    + +
    +myasmfilter $OBJS_DIR/foo.S.original $OBJS_DIR/foo.S
+myasmfilter bar.S $OBJS_DIR/bar.S
+
    + +

    NDK-Provided Function Macros

    +

    This section explains GNU Make function macros that the NDK provides. Use +{@code $(call <function>)} to evaluate them; they return textual information.

    + +

    my-dir

    + +

    This macro returns the path of the last included makefile, which typically is the +current {@code Android.mk}'s directory. {@code my-dir} is useful for defining +{@code LOCAL_PATH} at the start of your {@code Android.mk} file. For example:

    + +
    +LOCAL_PATH := $(call my-dir)
+
    + +

    Due to the way GNU Make works, what this macro really returns is the +path of the last makefile that the build system included when parsing the build scripts. For this +reason, you should not call {@code my-dir} after including another file.

    + +

    For example, consider the following example:

    + +
    +LOCAL_PATH := $(call my-dir)
+
+# ... declare one module
+
+include $(LOCAL_PATH)/foo/`Android.mk`
+
+LOCAL_PATH := $(call my-dir)
+
+# ... declare another module
+
    + +

    The problem here is that the second call to {@code my-dir} defines +{@code LOCAL_PATH} as {@code $PATH/foo} instead of {@code $PATH}, because that was where its +most recent include pointed.

    + +

    You can avoid this problem by putting additional includes after everything +else in the {@code Android.mk} file. For example:

    + +
    +LOCAL_PATH := $(call my-dir)
+
+# ... declare one module
+
+LOCAL_PATH := $(call my-dir)
+
+# ... declare another module
+
+# extra includes at the end of the Android.mk file
+include $(LOCAL_PATH)/foo/Android.mk
+
+
    + +

    If it is not feasible to structure the file in this way, save the value of the first +{@code my-dir} call into another variable. For example:

    + +
    +MY_LOCAL_PATH := $(call my-dir)
+
+LOCAL_PATH := $(MY_LOCAL_PATH)
+
+# ... declare one module
+
+include $(LOCAL_PATH)/foo/`Android.mk`
+
+LOCAL_PATH := $(MY_LOCAL_PATH)
+
+# ... declare another module
+
    + +

    all-subdir-makefiles

    + +

    Returns the list of {@code Android.mk} files located in all subdirectories of +the current {@code my-dir} path. + +

    You can use this function to provide deep-nested source directory hierarchies to the build +system. By default, the NDK only looks for files in the directory containing the +{@code Android.mk} file.

    + +

    this-makefile

    +

    Returns the path of the current makefile (from which the build system called the function).

    + +

    parent-makefile

    +

    Returns the path of the parent makefile in the inclusion tree (the path of the makefile that +included the current one).

    + +

    grand-parent-makefile

    +

    Returns the path of the grandparent makefile in the inclusion tree (the path of the makefile that +included the current one).

    + +

    import-module

    +

    A function that allows you to find and include the {@code Android.mk} +of another module by name. A typical example is as follows:

    + +
    +$(call import-module,<name>)
+
    + +

    In this example, the build system looks for the module tagged <name> in the list of +directories referenced that your {@code NDK_MODULE_PATH} environment variable references, and +includes its {@code Android.mk} file automatically for you.

    + +

    For more information, see Android Module Paths (Sharing Code). +

    diff --git a/docs/html-ndk/ndk/guides/application_mk.jd b/docs/html-ndk/ndk/guides/application_mk.jd new file mode 100644 index 000000000000..be82fbe513dc --- /dev/null +++ b/docs/html-ndk/ndk/guides/application_mk.jd @@ -0,0 +1,241 @@ +page.title=Application.mk +@jd:body + +
    +
    +

    On this page

    + +
      +
    1. Overview
      2. +
    2. Variables
      3. +
    +
    +
    + +

    This document explains the syntax of the {@code Application.mk} build file, which describes the +native modules that your app requires. A module can be a static library, a shared library, +or an executable.

    + +

    We recommend that you read the Concepts and +Android.mk pages before this one. Doing so will +help maximize your understanding of the material on this page.

    + +

    Overview

    +The {@code Application.mk} file is really a tiny GNU Makefile fragment that defines several +variables for compilation. It usually resides under {@code $PROJECT/jni/}, where {@code $PROJECT} +points to your application's project directory. Another alternative is to place it under a +sub-directory of the top-level {@code $NDK/apps/} directory. For example:

    + +
    +$NDK/apps/<myapp>/Application.mk
+
    + +

    Here, {@code <myapp>} is a short name used to describe your app to the NDK build system. It +doesn't actually go into your generated shared libraries or your final packages.

    + +

    Variables

    +

    APP_PROJECT_PATH

    +

    This variable stores the absolute path to your app's project-root directory. The build system +uses this information to place stripped-down versions of the generated JNI shared libraries +into a specific location known to the APK-generating tools.

    + +

    If you place your {@code Application.mk} file under {@code $NDK/apps/<myapp>/}, you must +define this variable. If you place it under {@code $PROJECT/jni/}, it is optional. + +

    APP_OPTIM

    +

    Define this optional variable as either {@code release} or {@code debug}. You use it to +alter the optimization level when building your application's modules.

    + +

    Release mode is the default, and generates highly optimized binaries. Debug mode generates +unoptimized binaries that are much easier to debug.

    + +

    Note that you can debug either release or debug binaries. Release binaries, however, provide less +information during debugging. For example, the build system optimizes out some variables, +preventing you from inspecting them. Also, code re-ordering can make it more difficult to step +through the code; stack traces may not be reliable.

    + +

    Declaring {@code android:debuggable} in your application manifest's {@code <application>} +tag will cause this variable to default to {@code debug} instead of {@code release}. Override this +default value by setting {@code APP_OPTIM} to {@code release}.

    + + +

    APP_CFLAGS

    +

    This variable stores a set of C compiler flags that the build system passes to the compiler +when compiling any C or C++ source code for any of the modules. You can use this variable to change +the build of a given module according to the application that needs it, instead of having to modify +the {@code Android.mk} file itself.

    + + +

    All paths in these flags should be relative to the top-level NDK directory. For example, if you +have the following setup:

    + +
    +sources/foo/Android.mk
+sources/bar/Android.mk
+
    + +

    To specify in {@code foo/Android.mk} that you want to add the path to the {@code bar} sources +during compilation, you should use: + +

    +APP_CFLAGS += -Isources/bar
+
    + +

    Or, alternatively:

    + +
    +APP_CFLAGS += -I$(LOCAL_PATH)/../bar
+
    + +

    {@code -I../bar} will not work since it is equivalent to +{@code -I$NDK_ROOT/../bar}.

    + +

    Note: This variable only works on C, not C++, sources in +android-ndk-1.5_r1. In all versions after that one, {@code APP_CFLAGS} matches the full Android +build system.

    + +

    APP_CPPFLAGS

    +

    This variable contains a set of C++ compiler flags that the build system passes to the compiler +when building only C++ sources.

    + +

    Note: In android-ndk-1.5_r1, this variable works on both C and +C++ sources. In all subsequent versions of the NDK, {@code APP_CPPFLAGS} now matches the full +Android build system. For flags that apply to both C and C++ sources, use {@code APP_CFLAGS}.

    + +

    APP_LDFLAGS

    +

    A set of linker flags that the build system passes when linking the application. This variable +is only relevant when the build system is building shared libraries and executables. When the +build system builds static libraries, it ignores these flags.

    + +

    APP_BUILD_SCRIPT

    +

    By default, the NDK build system looks under {@code jni/} for a file named +{@code Android.mk}.

    + +

    If you want to override this behavior, you can define {@code APP_BUILD_SCRIPT} to point to an +alternate build script. The build system always interprets a non-absolute path as relative to the +NDK's top-level directory.

    + +

    APP_ABI

    +

    By default, the NDK build system generates machine code for the +{@code armeabi} ABI. This machine code +corresponds to an ARMv5TE-based CPU with software floating point operations. You can use +{@code APP_ABI} to select a different ABI. Table 1 shows the {@code APP_ABI} +settings for different instruction sets.

    + +

    + Table 1. {@code APP_ABI} settings for different instruction sets.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Instruction setValue
    Hardware FPU instructions on ARMv7 based devices{@code APP_ABI := armeabi-v7a}
    ARMv8 AArch64{@code APP_ABI := arm64-v8a}
    IA-32{@code APP_ABI := x86}
    Intel64{@code APP_ABI := x86_64}
    MIPS32{@code APP_ABI := mips}
    MIPS64 (r6){@code APP_ABI := mips64}
    All supported instruction sets{@code APP_ABI := all}
    + +

    Note: {@code all} is available starting from NDKr7.

    + +

    You can also specify multiple values by placing them on the same line, delimited by spaces. +For example:

    + +
    +APP_ABI := armeabi armeabi-v7a x86 mips
+
    + +

    For the list of all supported ABIs and details about their usage and limitations, refer to +Android Native CPU ABI Management.

    + +

    APP_PLATFORM

    +

    This variable contains the name of the target Android platform. For example, {@code android-3} +specifies the Android 1.5 system images. For a complete list of platform names and corresponding +Android system images, see Android NDK Stable APIs +.

    + +

    APP_STL

    +

    By default, the NDK build system provides C++ headers for the minimal C++ runtime library +({@code system/lib/libstdc++.so}) provided by the Android system. In addition, it comes with +alternative C++ implementations that you can use or link to in your own applications. +Use {@code APP_STL} to select one of them. Table 2 shows the {@code APP_STL} values to specify +support for different libraries.

    + +

    + Table 2. {@code APP_STL} settings to support different libraries.

    + + + + + + + + + + + + + + + + + +
    LibraryValue
    Static STLport{@code APP_STL := stlport_static}
    Shared STLport{@code APP_STL := stlport_shared}
    Default C++ runtime{@code APP_STL := system}
    + +

    For more information on this subject, see C++ +Support.

    + + +

    APP_SHORT_COMMANDS

    +

    The equivalent of {@code LOCAL_SHORT_COMMANDS} in {@code Application.mk} for your whole project. +For more information, see the documentation for this variable on +{@code Android.mk}.

    + +

    NDK_TOOLCHAIN_VERSION

    +

    Define this variable as either {@code 4.9} or {@code 4.8} to select a version of the GCC +compiler. Version 4.9 is the default for 64-bit ABIs, and 4.8 is the default for 32-bit ABIs. +To select a version of Clang, define this variable as {@code clang3.4}, {@code clang3.5}, or +{@code clang}. Specifying {@code clang} chooses the most recent version of Clang.

    + +

    APP_PIE

    +

    Starting from Android 4.1 (API level 16), Android's dynamic linker supports position-independent +executables (PIE). Use the {@code -fPIE} flag to build them. This flag makes it harder to exploit +memory corruption bugs by randomizing code location. By default, {@code ndk-build} automatically +sets this value to {@code true} if your project targets {@code android-16} or higher. You may set +it manually to either {@code true} or {@code false}.

    + +

    This flag applies only to executables. It has no effect when building shared or static +libraries.

    + +

    Note: PIE executables cannot run on Android releases prior to 4.1. +

    This restriction only applies to executables. It has no effect when building shared or static +libraries.

    + +

    APP_THIN_ARCHIVE

    +

    Sets the default value of {@code LOCAL_THIN_ARCHIVE} in the {@code Android.mk} file for all +static library modules in this project. For more information, see the documentation for +{@code LOCAL_THIN_ARCHIVE} on {@code Android.mk}. +

    diff --git a/docs/html-ndk/ndk/guides/arch.jd b/docs/html-ndk/ndk/guides/arch.jd new file mode 100644 index 000000000000..875bbd90f5ea --- /dev/null +++ b/docs/html-ndk/ndk/guides/arch.jd @@ -0,0 +1,31 @@ +page.title=Architectures and CPUs +@jd:body + +
    +

    This section includes detailed information about ABIs and detailed information on support for respective instruction sets. It includes these topics:

    +
      +
    • ABI Management
        +
      • Different ABIs support different CPUs and processing capabilities.
        • +
      +
      • +
    • Neon
        +
      • Details about targeting devices whose CPUs support Neon, or Advanced SIMD. Neon is an optional extension of the armv7 architecture.
        • +
      +
      • +
    • Mips
        +
      • Details about targeting devices with CPUs supporting the MIPS32 instruction set.
        • +
      +
      • +
    • x86
        +
      • Details about targeting devices with CPUs supporting the IA-32 instruction set.
        • +
      +
      • +
    • x86-64
        +
      • Details about targeting devices whose CPUs support the x86-64 instruction set.
        • +
      +
      • +
    • CPU Features
        +
      • A small library that detects the target device's CPU family and supported features.
        • +
      +
      • +
    \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/build.jd b/docs/html-ndk/ndk/guides/build.jd new file mode 100644 index 000000000000..b1893fa66c66 --- /dev/null +++ b/docs/html-ndk/ndk/guides/build.jd @@ -0,0 +1,23 @@ +page.title=Building +@jd:body + +
    +

    This section explains, in detail, how to use the NDK to build your project. It comprises the following topics:

    +
      +
    • ndk-build
        +
      • How to use the shell script that invokes the tools to build your shared libraries.
        • +
      +
      • +
    • Android.mk
        +
      • Syntax for the file that describes your build sources to the build system.
        • +
      +
      • +
    • Application.mk
        +
      • Syntax for the file that describes the native modules that your application requires.
        • +
      +
      • +
    • Standalone Toolchain
        +
      • How to integrate the NDK into your existing build system.
        • +
      +
      • +
    \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/concepts.jd b/docs/html-ndk/ndk/guides/concepts.jd new file mode 100644 index 000000000000..bd4570ecb0c7 --- /dev/null +++ b/docs/html-ndk/ndk/guides/concepts.jd @@ -0,0 +1,301 @@ +page.title=Concepts +@jd:body + + + +

    Before Beginning

    + +

    This guide assumes that you are:

    + +

    Introduction

    + +

    This section provides a high-level explanation of how the NDK works. The Android NDK is a set of +tools allowing you to embed C or C++ (“native code”) into your Android apps. The ability to use +native code in Android apps can be particularly useful to developers who wish to do one or more of +the following:

    +
      +
    • Port their apps between platforms.
      • +
    • Reuse existing libraries, or provide their own libraries for reuse. +
      • +
    • Increase performance in certain cases, particularly computationally intensive ones like games. +
      • +
    +

    How it Works

    + +

    This section introduces the main components used in building a native application for Android, +and goes on to describe the process of building and packaging.

    +

    Main components

    + +

    You should have an understanding of the following components as you build your app:

    +
      +
    • ndk-build: The ndk-build script launches the build scripts at the heart of the NDK. These +scripts: +
        +
      • Automatically probe your development system and app project file to determine what to build.
        • +
      • Generate binaries.
        • +
      • Copy the binaries to your app's project path.
        • +
      +

      For more information, see the +ndk-build section of this guide.

      +
      • +
    + +
      +
    • Java: From your Java source, the Android build process generates {@code .dex} +("Dalvik EXecutable") files, which are what the Android OS runs in the Dalvik Virtual Machine +(“DVM”). Even if your app contains no Java source code at all, the build process still generates a +{@code .dex} executable file within which the native component runs. + +

      When developing Java components, use the {@code native} keyword to indicate methods implemented +as native code. For example, the following function declaration tells the compiler that the +implementation is in a native library:

      + + + +
      +public native int add(int  x, int  y);
+
      +
      • +
    + +
      +
    • Native shared libraries: The NDK builds these libraries, or {@code .so} files, from your native +source code. + +

      Note: If two libraries implement respective methods with the same +signature, a link error occurs. In C, "signature" means method name only. In C++, "signature" means +not only method name, but also its argument names and types.

      +
      • +
    + +
      +
    • Native static libraries: The NDK can also build static libraries, or {@code .a} files, which you +can link against other libraries.
      • +
    + +
      +
    • Java Native Interface ("JNI"): The JNI is the interface via which the Java and C++ components +talk to one another. This guide assumes knowledge of the JNI; for information about it, consult the + +Java Native Interface Specification.
      • +
    + +
      +
    • Application Binary Interface ("ABI"): The ABI defines exactly how your app's machine code is +expected to interact with the system at runtime. The NDK builds {@code .so} files against these +definitions. Different ABIs correspond to different architectures: The NDK includes ABI support for +ARMEABI (default), MIPS, and x86. For more information, see +ABI Management.
      • +
    + +
      +
    • Manifest: If you are writing an app with no Java component to it, you must declare the +{@link android.app.NativeActivity} class in the +manifest. The +Native Activity section provides more detail on how to do this, under +“Using the native-activity.h interface.” +
      • +
    + +

    The following two items only apply in cases in which you are using the toolchains provided with +the Android NDK as standalone compilers.

    + +
      +
    • {@code Android.mk}: You must create an {@code Android.mk} configuration file inside your +{@code jni} folder. The ndk-build script looks at this file, which defines the module and its name, +the source files to be compiled, build flags and libraries to link. For more information, see the +Android.mk section of this document.
      • +
    + +
      +
    • {@code Application.mk}: You may optionally create an Application.mk file. This file enumerates +and describes the modules that your app requires. This information includes:
        +
      • ABIs used to compile for specific platforms.
        • +
      • Toolchains.
        • +
      • Standard libraries to include (static and dynamic STLport or default system).
        • +
      +

      For more information, see the +Application.mk section.

      +
      • +
    + + +

    Flow

    + +

    The general flow for developing a native app for Android is as follows:

    +
      +
    1. Design your app, deciding which parts to implement in Java, and which parts to implement as +native code. + +

      Note: While it is possible to completely avoid Java, you are likely +to find the Android Java framework useful for tasks including controlling the display and UI.

      +
      2. + +
    2. Create an Android app Project in Eclipse as you would for any other Android project.
      3. +
    3. If you are writing a native-only app, declare the {@link android.app.NativeActivity} class in +{@code AndroidManifest.xml}. You can do so from the Eclipse/ADT Android Manifest Editor, or by +hand-editing the file. For more information, see the Native Activity section. +
      4. +
    4. Create an Android.mk file describing the native library, including name, flags, linked libraries +and source files to be compiled in the ‘JNI’ directory.
      5. +
    5. OPTIONAL: Create an {@code Application.mk} file configuring the target ABIs, toolchain, +release/debug mode, and STL. For any of these that you do not specify, the following default values +are used, respectively: +
        +
      • +ABI: armeabi +
        • +
      • +Toolchain: GCC 4.8 +
        • +
      • +Mode: Release +
        • +
      • +STL: system +
      +
      6. +
    6. Place your native source under the project's {@code jni} directory.
      7. +
    7. Use ndk-build to compile the native ({@code .so}, {@code .a}) libraries.
      8. +
    8. Build the Java component, producing the executable {@code .dex} file.
      9. +
    9. Package everything into an APK file, containing {@code .so}, {@code .dex}, and other files +needed for your app to run. +
    + +

    Note that Eclipse can perform steps 7. through 9. in a single operation.

    + +

    Native Activities and Applications

    + +

    The Android SDK provides a helper class, {@link android.app.NativeActivity}, that allows you to +write a completely native activity. {@link android.app.NativeActivity} handles the communication +between the Android framework and your native code, so you do not have to subclass it or call its +methods. All you need to do is declare your application to be native in your +{@code AndroidManifest.xml} file, and begin creating your native application.

    + +

    An Android application using {@link android.app.NativeActivity} still runs in its own virtual +machine, sandboxed from other applications. You can therefore still access Android framework APIs +through the JNI. In certain cases, however–such as for sensors, input events, and +assets–the NDK provides native interfaces that you can use instead of having to call +across the JNI. For more information about such support, see +Stable APIs.

    + +

    Regardless of whether or not you are developing a native activity, we recommend that you create +your projects with the traditional Android build tools. Doing so helps ensure building and packaging +of Android applications with the correct structure.

    + +

    The Android NDK provides you with two choices to implement your native activity:

    + +
      +
    • The {@code native_activity.h} header defines the native version of the +{@link android.app.NativeActivity} class. It contains the callback interface and data structures +that you need to create your native activity. Because the main thread of your application handles +the callbacks, your callback implementations must not be blocking. If they block, you might receive +ANR (Application Not Responding) errors because your main thread is unresponsive until the callback +returns.
      • +
    • The android_native_app_glue.h file defines a static helper library built on top of the +{@code native_activity.h} interface. It spawns another thread, which handles things such as +callbacks or input events in an event loop. Moving these events to a separate thread prevents any +callbacks from blocking your main thread.
      • +
    + +

    The {@code <ndk_root>/sources/android/native_app_glue/android_native_app_glue.c} source is +also available, allowing you to modify the implementation.

    +

    For more information on how to use this static library, examine the native-activity sample +application and its documentation. Further reading is also available in the comments in the {@code <ndk_root>/sources/android/native_app_glue/android_native_app_glue.h} file.

    + +

    Using the native-activity.h interface

    + +

    To implement a native activity with the {@code native-activity.h} interface:

    + +
      +
    1. Create a {@code jni/} directory in your project's root directory. This directory stores all of +your native code.
      2. +
    2. Declare your native activity in the {@code AndroidManifest.xml} file.
      3. + +

      Because your application has no Java code, set {@code android:hasCode} to {@code false}.

      + +
      +<application android:label="@string/app_name" android:hasCode="false">
+
      + +

      You must set the {@code android:name} attribute of the activity tag to +{@link android.app.NativeActivity}.

      + +
      +<activity android:name="android.app.NativeActivity"
+            android:label="@string/app_name">
+
      +

      Note: You can subclass {@link android.app.NativeActivity}. If you +do, use the name of the subclass instead of {@link android.app.NativeActivity}.

      +

      The {@code android:value} attribute of the {@code meta-data} tag specifies the name of the shared +library containing the entry point to the application (such as C/C++ {@code main}), omitting the +{@code lib} prefix and {@code .so} suffix from the library name.

      + +
      +          <meta-data android:name="android.app.lib_name"
+            android:value="native-activity" />
+            <intent-filter>
+              <action android:name="android.intent.action.MAIN" />
+              <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+          </activity>
+        </application>
+      </manifest>
+
      + +
    3. Create a file for your native activity, and implement the {@code ANativeActivity_onCreate()} +function, which the app calls when the native activity starts. This function, analogous +to {@code main} in C/C++, receives a pointer to an {@code ANativeActivity} structure, +which contains function pointers to the various callback implementations that you need to write. +Set the applicable callback function pointers in {@code ANativeActivity->;callbacks} to the +implementations of your callbacks.
      4. + + + +
    4. Set the {@code ANativeActivity->;instance} field to the address of any instance of specific +data that you want to use.
      5. +
    5. Implement anything else that you want your activity to do upon starting.
      6. +
    6. Implement the rest of the callbacks that you set in {@code ANativeActivity->;callbacks}. For +more information on when the callbacks are called, see the +SDK documentation for Activity Lifecycles. +
      7. +
    7. Develop the rest of your application.
      8. +
    8. Create an {@code Android.mk file} in the {@code jni/} directory of your project to describe your +native module to the build system. For more information, see the +Android.mk section.. +
      9. +
    9. Once you have an {@code Android.mk} file, compile your native code using the {@code ndk-build} +command.
      10. + +
      +$ cd <path>/<to>/<project>
+$ <ndk>/ndk-build
+
      + +
    10. Build and install your Android project as usual, using Ant or Eclipse. If your native code is in +the {@code jni/} directory, the build script automatically packages the {@code .so} file(s) built +from it into the APK.
      11. +
    + +

    You can find further information on using {@code native-activity.h} here.

    + + + diff --git a/docs/html-ndk/ndk/guides/cpp-support.jd b/docs/html-ndk/ndk/guides/cpp-support.jd new file mode 100644 index 000000000000..60541815ff28 --- /dev/null +++ b/docs/html-ndk/ndk/guides/cpp-support.jd @@ -0,0 +1,328 @@ +page.title=C++ Library Support +@jd:body + + + +

    The Android platform provides a very minimal C++ runtime support library ({@code libstdc++}). +This minimal support does not include, for example:

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

    The NDK provides headers for use with this default library. In addition, the NDK provides a +number of helper runtimes that provide additional features. This page provides information about +these helper runtimes, their characteristics, and how to use them. +

    + +

    Helper Runtimes

    + +

    Table 1 provides names, brief explanations, and features of runtimes available inthe NDK.

    + +

    + Table 1. NDK Runtimes and Features.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameExplanation> +Features +
    {@code libstdc++} (default) The default minimal system C++ runtime library.N/A
    {@code gabi++_static} The GAbi++ runtime (static).C++ Exceptions and RTTI
    {@code gabi++_shared} The GAbi++ runtime (shared).C++ Exceptions and RTTI
    {@code stlport_static} The STLport runtime (static). C++ Exceptions and RTTI; Standard Library
    {@code stlport_shared} The STLport runtime (shared). C++ Exceptions and RTTI; Standard Library
    {@code gnustl_static} The GNU STL (static). C++ Exceptions and RTTI; Standard Library
    {@code gnustl_shared} The GNU STL (shared). C++ Exceptions and RTTI; Standard Library
    {@code c++_static} The LLVM libc++ runtime (static). C++ Exceptions and RTTI; Standard Library
    {@code c++_shared} The LLVM libc++ runtime (shared). C++ Exceptions and RTTI; Standard Library
    + +

    How to set your runtime

    + +

    Use the {@code APP_STL} variable in your +{@code Application.mk} file to specify the runtime you wish to use. Use the values in +the "Name" column in Table 1 as your setting. For example:

    + +
    +APP_STL := gnustl_static
+
    + +

    You may only select one runtime for your app, and can only do in +{@code Application.mk}.

    + +

    Even if you do not use the NDK build system, you can still use STLport, libc++ or GNU STL. +For more information on how to use these runtimes with your own toolchain, see Standalone Toolchain.

    + +

    Runtime Characteristics

    +

    System runtime

    + +

    This runtime only provides the following headers, with no support beyond them:

    +
      +
    • {@code cassert}
      • +
    • {@code cctype}
      • +
    • {@code cerrno}
      • +
    • {@code cfloat}
      • +
    • {@code climits}
      • +
    • {@code cmath}
      • +
    • {@code csetjmp}
      • +
    • {@code csignal}
      • +
    • {@code cstddef}
      • +
    • {@code cstdint}
      • +
    • {@code cstdio}
      • +
    • {@code cstdlib}
      • +
    • {@code cstring}
      • +
    • {@code ctime}
      • +
    • {@code cwchar}
      • +
    • {@code new}
      • +
    • {@code stl_pair.h}
      • +
    • {@code typeinfo}
      • +
    • {@code utility}
      • +
    + +

    GAbi++ runtime

    +

    This runtime provides the same headers as the default runtime, but adds support for RTTI +(RunTime Type Information) and exception handling.

    + + +

    STLport runtime

    +

    This runtime is an Android port of STLport +(http://www.stlport.org). It provides a complete set of C++ +standard library headers. It also, by embedding its own instance of GAbi++, provides support for +RTTI and exception handling.

    + +

    While shared and static versions of this runtime are avilable, we recommend using the shared +version. For more information, see Static runtimes.

    + +

    The shared library file is named {@code libstlport_shared.so} instead of {@code libstdc++.so} +as is common on other platforms.

    + +

    In addition to the static- and shared-library options, you can also force the NDK to +build the library from sources by adding the following line to your {@code Application.mk} +file, or setting it in your environment prior to building:

    + +
    +STLPORT_FORCE_REBUILD := true
+
    + + +

    GNU STL runtime

    +

    This runtime is the GNU Standard C++ Library, ({@code libstdc++-v3}). Its shared library file is +named {@code libgnustl_shared.so}.

    + + +

    libC++ runtime:

    +

    This runtime is an Android port of LLVM libc++. Its +shared library file is named {@code libc++_shared.so}.

    + +

    By default, this runtime compiles with {@code -std=c++11}. As with GNU {@code libstdc++}, you +need to explicitly turns on exceptions or rtti support. For information on how to do this, see +C++ Exceptions and RTTI.

    + +

    The NDK provides prebuilt static and shared libraries for {@code libc++} compiled by Clang 3.4, +but you can force the NDK to rebuild {@code libc++} from sources by adding the following line to +your {@code Application.mk} file, or setting it in your environment prior to building:

    + +
    +LIBCXX_FORCE_REBUILD := true
+
    + +

    atomic support

    + +

    If you include {@code <atomic>}, it's likely that you also need {@code libatomic}. +If you are using {@code ndk-build}, add the following line:

    + +
    +LOCAL_LDLIBS += -latomic
+
    + +

    If you are using your own toolchain, use:

    + +
    +-latomic
+
    + +

    Note: {@code -latomic} is only available for GCC 4.8. +Because Clang 3.5 and Clang 3.6 use GCC 4.8's headers and libraries, as well as its +{@code as} and {@code ld} options, those versions of Clang also get {@code -latomic}.

    + + +

    Compatibility

    + +

    Around 99% of tests pass when compiling {@code libc++} with Clang 3.4 for all supported ABIs. +The failures are mostly in the areas of {@code wchar_t} and locales that Android bionic +doesn't support. Switching locale from the default produces the following warning in +{@code logcat}:

    + +
    +newlocale() WARNING: Trying to set locale to en_US.UTF-8 other than "", "C" or "POSIX"
+
    + +

    We do not recommend using {@code libc++} with GCC 4.6 because of GCC 4.6's limited c++11 +support.

    + +

    For information on {@code libc++} tests that fail to compile, {@code black_list*} in +{@code $NDK/tests/device/test-libc++-shared-full/jni/Android.mk}. For information about tests +that fail to run correctly, see {@code $NDK/tests/device/test-libc++-shared-full/BROKEN_RUN}. +{@code $NDK}, here, is the your NDK installation's root directory.

    + + +

    Important Considerations

    + +

    C++ Exceptions

    +

    In all versions of the NDK later than NDKr5, the NDK toolchain allows you to use C++ runtimes +that support exception handling. However, to ensure compatibility with earlier releases, it +compiles all C++ sources with {@code -fno-exceptions} support by default. You can enable C++ +exceptions either for your entire app, or for individual modules. + +

    To enable exception-handling support for your entire app, add the following line to +your {@code Application.mk} file. +To enable exception-handling support for individual modules', add the following line to +their respective {@code Android.mk} files.

    + +
    +APP_CPPFLAGS += -fexceptions
+
    + +

    RTTI

    +

    In all versions of the NDK later than NDKr5, the NDK toolchain allows you to use C++ runtimes +that support RTTI. However, to ensure compatibility with earlier releases, it compiles all C++ +sources with {@code -fno-rtti} by default. + +

    To enable RTTI support for your entire app for your entire application, add the following line to +your {@code Application.mk} file: + +

    +APP_CPPFLAGS += -frtti
+
    + +To enable RTTI support for individual modules, add the following line to +their respective {@code Android.mk} files: + +
    +LOCAL_CPP_FEATURES += rtti
+
    + +Alternatively, you can use: + +
    +LOCAL_CPPFLAGS += -frtti
+
    + +

    Static runtimes

    +

    Linking the static library variant of a C++ runtime to more than one binary may result in +unexpected behavior. For example, you may experience:

    + +
      +
    • Memory allocated in one library, and freed in the other, causing memory leakage or heap +corruption.
      • +
    • Exceptions raised in {@code libfoo.so} going uncaught in {@code libbar.so}, causing your app +to crash.
      • +
    • Buffering of {@code std::cout} not working properly
      • +
    + +

    In addition, if you link two shared libraries–or a shared library and an executable– +against the same static runtime, the final binary image of each shared library includes a copy of +the runtime's code. Having multiple instances of runtime code is problematic because of duplication +of certain global variables that the runtime uses or provides internally.

    + +

    This problem does not apply to a project comprising a single shared library. For example, +you can link against {@code stlport_static}, and expect your app to behave correctly. If your +project requires several shared library modules, we recommend that you use the shared library +variant of your C++ runtime.

    + +

    Shared runtimes

    +

    If your app targets a version of Android earlier than Android 4.3 (Android API level 18), +and you use the shared library variant of a given C++ runtime, you must load the shared library +before any other library that depends on it.

    + +

    For example, an app may have the following modules:

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

    You must need to load the libraries in reverse dependency order:

    +
    +    static {
+      System.loadLibrary("stlport_shared");
+      System.loadLibrary("bar");
+      System.loadLibrary("foo");
+    }
+
    + +

    Note: Do not use the {@code lib} prefix when calling +{@code System.loadLibrary()}.

    + +

    Licensing

    + +

    STLport is licensed under a BSD-style open-source license. See +{@code $NDK/sources/cxx-stl/stlport/README} for more details about STLport.

    + +

    GNU libstdc++ is covered by the GPLv3 license, and not the LGPLv2 or LGPLv3. For +more information, see +License on the GCC website.

    + +

    LLVM {@code libc++} +is dual-licensed under both the University of Illinois "BSD-Like" license and the MIT license.

    \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/cpu-arm-neon.jd b/docs/html-ndk/ndk/guides/cpu-arm-neon.jd new file mode 100644 index 000000000000..32e9942b8e7c --- /dev/null +++ b/docs/html-ndk/ndk/guides/cpu-arm-neon.jd @@ -0,0 +1,109 @@ +page.title=NEON Support +@jd:body + + + +

    The NDK supports the ARM Advanced SIMD, an optional instruction-set extension of the ARMv7 spec. +NEON provides a set of scalar/vector instructions and registers (shared with the FPU) comparable to +MMX/SSE/3DNow! in the x86 world. To function, it requires VFPv3-D32 (32 hardware FPU 64-bit +registers, instead of the minimum of 16).

    + +

    The NDK supports the compilation of modules or even specific source files with support for NEON. +As a result, a specific compiler flag enables the use of GCC ARM NEON intrinsics and VFPv3-D32 +at the same time.

    + +

    Not all ARMv7-based Android devices support NEON, but devices that do may benefit significantly +from its support for scalar/vector instructions. For x86 devices, the NDK can also translate NEON +instructions into SSE, although with several restrictions. For more information, see +Using LOCAL_ARM_NEON +

    To have the NDK build all its source files with NEON support, include the following line in +your module definition:

    + +
    +LOCAL_ARM_NEON := true
+
    + +

    It can be especially useful to build all source files with NEON support if you want to build a +static or shared library that specifically contains NEON code paths.

    + +

    Using the .neon Suffix

    +

    When listing source files for your {@code LOCAL_SRC_FILES} variable, you have the option of +using the {@code .neon} suffix to indicate that you want to build binaries with NEON support. +For example, the following example builds one file with {@code .neon} support, and another +without it:

    + +
    +LOCAL_SRC_FILES := foo.c.neon bar.c
+
    + +

    You can combine the {@code .neon} suffix with the {@code .arm} suffix, which specifies the 32-bit +ARM instruction set for non-NEON instructions. In such a definition, {@code arm} must come before +{@code neon}. For example: {@code foo.c.arm.neon} works, but {@code foo.c.neon.arm} does not.

    + +

    Build Requirements

    +

    NEON support only works with the {@code armeabi-v7a} and {@code x86} ABIs. If the NDK build +scripts encounter other ABIs while attempting to build with NEON support, the NDK build scripts +exit. x86 provides partial NEON support via translation header. It is +important to use checks like the following in your +{@code Android.mk} file:

    + +
    +# define a static library containing our NEON code
+ifeq ($(TARGET_ARCH_ABI),$(filter $(TARGET_ARCH_ABI), armeabi-v7a x86))
+include $(CLEAR_VARS)
+LOCAL_MODULE    := mylib-neon
+LOCAL_SRC_FILES := mylib-neon.c
+LOCAL_ARM_NEON  := true
+include $(BUILD_STATIC_LIBRARY)
+endif # TARGET_ARCH_ABI == armeabi-v7a || x86
+
    + +

    Runtime Detection

    +

    Your app must perform runtime detection to confirm that NEON-capable machine code can be run on +the target device. This is because not all ARMv7-based Android devices support NEON. The app can +perform this check using the +{@code cpufeatures} library that comes with +this NDK.

    + +

    You should explicitly check that {@code android_getCpuFamily()} returns {@code +ANDROID_CPU_FAMILY_ARM}, and that {@code android_getCpuFeatures()} returns a value including the +{@code ANDROID_CPU_ARM_FEATURE_NEON flag} set. For example:

    + +
    +#include <cpu-features.h>
+...
+...
+if (android_getCpuFamily() == ANDROID_CPU_FAMILY_ARM &&
+    (android_getCpuFeatures() & ANDROID_CPU_ARM_FEATURE_NEON) != 0)
+{
+    // use NEON-optimized routines
+    ...
+}
+else
+{
+    // use non-NEON fallback routines instead
+    ...
+}
+
+...
+
    + +

    Sample Code

    +

    The source code for the NDK's hello-neon sample provides an example of how to use the +{@code cpufeatures} library and NEON intrinsics at the same time. This sample implements a tiny +benchmark for a FIR filter loop using a C version, and a NEON-optimized one for devices that +support it.

    \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/cpu-features.jd b/docs/html-ndk/ndk/guides/cpu-features.jd new file mode 100644 index 000000000000..b27250acb263 --- /dev/null +++ b/docs/html-ndk/ndk/guides/cpu-features.jd @@ -0,0 +1,210 @@ +page.title=The cpufeatures Library +@jd:body + +
    +
    +

    On this page

    + +
      +
    1. Usage
      2. +
    2. Functions
      3. +
    3. Change History
      4. +
    +
    +
    + +

    The NDK provides a small library named {@code cpufeatures} that your app can use at runtime to +detect the target device's CPU family and the optional features it supports. It is designed to work +as-is on all official Android platform versions.

    + +

    Usage

    +

    The {@code cpufeatures} library is available as an import module. To use it, follow the procedure +below:

    + +
      +
    1. List {@code cpufeatures} in your list of static library dependencies. For example: + +
      +LOCAL_STATIC_LIBRARIES := cpufeatures
+
      +
      2. + +
    2. In your source code, include the {@code <cpu-features.h>} header file.
      3. + +
    3. At the end of your {@code Android.mk} file, +insert an instruction to import the {@code android/cpufeatures} module. For example: + +
      +$(call import-module,android/cpufeatures)
+
      + +

      Here is a simple example of an {@code Android.mk} file that imports the {@code cpufeatures} +library:

      + +
      +<project-path>/jni/Android.mk:
+LOCAL_PATH := $(call my-dir)
+
+include $(CLEAR_VARS)
+LOCAL_MODULE := <your-module-name>
+LOCAL_SRC_FILES := <your-source-files>
+LOCAL_STATIC_LIBRARIES := cpufeatures
+include $(BUILD_SHARED_LIBRARY)
+
+$(call import-module,android/cpufeatures)
+
      +
      4. +
    + +

    Functions

    +

    The {@code cpufeatures} library provides two functions. The first function returns the family to +which the device's CPU belongs. Declare it as follows:

    + +
    +AndroidCpuFamily android_getCpuFamily();
+
    + +

    The function returns one of the following enums, representing the CPU family/architecture that +the device supports.

    +
      +
    • {@code ANDROID_CPU_FAMILY_ARM}
      • +
    • {@code ANDROID_CPU_FAMILY_X86}
      • +
    • {@code ANDROID_CPU_FAMILY_MIPS}
      • +
    • {@code ANDROID_CPU_FAMILY_ARM64}
      • +
    • {@code ANDROID_CPU_FAMILY_X86_64}
      • +
    • {@code ANDROID_CPU_FAMILY_MIPS64}
      • +
    + +

    For a 32-bit executable on a 64-bit system, this function returns only the 32-bit value.

    + +

    The second function returns the set of optional features that the device's CPU supports. Declare +it as follows: + +

    +uint64_t android_getCpuFeatures();
+
    + +

    The return value takes the form of a set of bit flags, each flag representing one +CPU-family-specific feature. The rest of this section provides information on features for +the respective families.

    + +

    32-bit ARM CPU family

    + +

    The following flags are available for the 32-bit ARM CPU family:

    +
    +
    {@code ANDROID_CPU_ARM_FEATURE_VFPv2}
    +
    Indicates that the device's CPU supports the VFPv2 instruction set. Most ARMv6 CPUs support +this instruction set.
    + +
    {@code ANDROID_CPU_ARM_FEATURE_ARMv7}
    +
    Indicates that the device's CPU supports the ARMv7-A instruction set as supported by the +armeabi-v7a ABI. This instruction set supports both +Thumb-2 and VFPv3-D16 instructions. This return value also indicates support for the VFPv3 hardware +FPU instruction-set extension.
    + +
    {@code ANDROID_CPU_ARM_FEATURE_VFPv3}
    +
    Indicates that the device's CPU supports the VFPv3 hardware FPU instruction-set extension. +

    This value is equivalent to the {@code VFPv3-D16} instruction set, which provides provides only +16 hardware double-precision FP registers.

    + +
    {@code ANDROID_CPU_ARM_FEATURE_VFP_D32}
    +
    Indicates that the device's CPU supports 32 hardware double-precision FP registers instead of +16. Even when there are 32 hardware double-precision FP registers, there are still only 32 +single-precision registers mapped to the same register banks.
    + +
    {@code ANDROID_CPU_ARM_FEATURE_NEON}
    +
    Indicates that the device's CPU supports the ARM Advanced SIMD (NEON) vector instruction set +extension. Note that ARM mandates that such CPUs also implement VFPv3-D32, which provides 32 +hardware FP registers (shared with the NEON unit).
    + +
    {@code ANDROID_CPU_ARM_FEATURE_VFP_FP16}
    +
    Indicates that the device's CPU supports instructions to perform floating-point operations on +16-bit registers. This feature is part of the VFPv4 specification.
    + +
    {@code ANDROID_CPU_ARM_FEATURE_VFP_FMA}
    +
    Indicates that the device's CPU supports the fused multiply-accumulate extension for the VFP +instruction set. Also part of the VFPv4 specification.
    + +
    {@code ANDROID_CPU_ARM_FEATURE_NEON_FMA}
    +
    Indicates that the device's CPU supports the fused multiply-accumulate extension for the NEON +instruction set. Also part of the VFPv4 specification.
    + +
    {@code ANDROID_CPU_ARM_FEATURE_IDIV_ARM}
    +
    Indicates that the device's CPU supports integer division in ARM mode. Only available on later- +model CPUs, such as Cortex-A15.
    + +
    {@code ANDROID_CPU_ARM_FEATURE_IDIV_THUMB2}
    +
    Indicates that the device's CPU supports Integer division in Thumb-2 mode. Only available on +later-model CPUs, such as Cortex-A15.
    + +
    {@code ANDROID_CPU_ARM_FEATURE_iWMMXt}
    +
    Indicates that the device's CPU supports an instruction-set extension that adds MMX registers +and instructions. This feature is only available on a few XScale- based CPUs.
    + +
    {@code ANDROID_CPU_ARM_FEATURE_LDREX_STREX}
    +
    Indicates that the device's CPU supports LDREX and STREX instructions available since ARMv6. +Together, these instructions provide atomic updates on memory with the help of exclusive +monitor.
    +
    + +

    64-bit ARM CPU family

    + +

    The following flags are available for the 64-bit ARM CPU family:

    +
    +
    {@code ANDROID_CPU_ARM64_FEATURE_FP}
    +
    Indicates that the device's CPU has a Floating Point Unit (FPU). All Android ARM64 devices must +support this feature.
    +
    {@code ANDROID_CPU_ARM64_FEATURE_ASIMD}
    +
    Indicates that the device's CPU has an Advanced SIMD (ASIMD) unit. All Android ARM64 devices +must support this feature.
    +
    {@code ANDROID_CPU_ARM64_FEATURE_AES}
    +
    Indicates that the device's CPU supports {@code AES} instructions.
    +
    {@code ANDROID_CPU_ARM64_FEATURE_CRC32}
    +
    Indicates that the device's CPU supports {@code CRC32} instructions.
    +
    {@code ANDROID_CPU_ARM64_FEATURE_SHA1}
    +
    Indicates that the device's CPU supports {@code SHA1} instructions.
    +
    {@code ANDROID_CPU_ARM64_FEATURE_SHA2}
    +
    Indicates that the device's CPU supports {@code SHA2} instructions.
    +
    {@code ANDROID_CPU_ARM64_FEATURE_PMULL}
    +
    Indicates that the device's CPU supports 64-bit {@code PMULL} and {@code PMULL2} +instructions.
    +
    + +

    32-bit x86 CPU family

    + +

    The following flags are available for the 32-bit x86 CPU family.

    +

    +
    {@code ANDROID_CPU_X86_FEATURE_SSSE3}
    +Indicates that the device's CPU supports the SSSE3 instruction extension set. + +
    {@code ANDROID_CPU_X86_FEATURE_POPCNT}
    +
    Indicates that the device's CPU supports the {@code POPCNT} instruction.
    + +
    {@code ANDROID_CPU_X86_FEATURE_MOVBE}
    +
    Indicates that the device's CPU supports the {@code MOVBE} instruction. This instruction is +specific to some Intel IA-32 CPUs, such as Atom.
    +
    + +

    {@code android_getCpuFeatures()} returns {@code 0} for CPU families for which there are no +listed extensions.

    + +

    The following function returns the maximum number of CPU cores on the target device:

    + +
    +int  android_getCpuCount(void);
+
    + +

    MIPS CPU family

    + +
    +
    {@code ANDROID_CPU_MIPS_FEATURE_R6}
    +
    Indicates that the CPU executes MIPS Release 6 instructions natively, and supports obsoleted R1..R5 instructions only via kernel traps.
    + +
    {@code ANDROID_CPU_MIPS_FEATURE_MSA}
    +
    Indicates that the CPU supports MIPS SIMD Architecture instructions.
    +
    + +

    Change History

    +

    For the complete change history of this library, see the comments in +{@code $NDK/sources/android/cpufeatures/cpu-features.c}, where {@code $NDK} is the root of your +NDK installation.

    \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/debug.jd b/docs/html-ndk/ndk/guides/debug.jd new file mode 100644 index 000000000000..b202ed9ab968 --- /dev/null +++ b/docs/html-ndk/ndk/guides/debug.jd @@ -0,0 +1,17 @@ +page.title=Debugging +@jd:body + +
    Debugging
    +
    +
    +

    This section introduces you to debugging with the NDK. It includes:

    +
      +
    • ndk-gdb and ndk-gdb-py
        +
      • The helper shell script named ndk-gdb, which allows you to launch a native debugging session for your NDK-generated machine code.
        • +
      +
      • +
    • ndk-stack
        +
      • A tool that helps you use ADB logcat in your debugging.
        • +
      +
      • +
    \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/guides_toc.cs b/docs/html-ndk/ndk/guides/guides_toc.cs index e6bc19928f69..3763c53b98ee 100644 --- a/docs/html-ndk/ndk/guides/guides_toc.cs +++ b/docs/html-ndk/ndk/guides/guides_toc.cs @@ -8,8 +8,65 @@ diff --git a/docs/html-ndk/ndk/guides/images/NDK_build_string.png b/docs/html-ndk/ndk/guides/images/NDK_build_string.png new file mode 100644 index 000000000000..338378bca6f0 Binary files /dev/null and b/docs/html-ndk/ndk/guides/images/NDK_build_string.png differ diff --git a/docs/html-ndk/ndk/guides/images/NDK_build_string@2x.png b/docs/html-ndk/ndk/guides/images/NDK_build_string@2x.png new file mode 100644 index 000000000000..5ba3ce3baf66 Binary files /dev/null and b/docs/html-ndk/ndk/guides/images/NDK_build_string@2x.png differ diff --git a/docs/html-ndk/ndk/guides/images/verification_screen.png b/docs/html-ndk/ndk/guides/images/verification_screen.png new file mode 100644 index 000000000000..91858baa850c Binary files /dev/null and b/docs/html-ndk/ndk/guides/images/verification_screen.png differ diff --git a/docs/html-ndk/ndk/guides/images/verification_screen@2x.png b/docs/html-ndk/ndk/guides/images/verification_screen@2x.png new file mode 100644 index 000000000000..0d666c9d02b3 Binary files /dev/null and b/docs/html-ndk/ndk/guides/images/verification_screen@2x.png differ diff --git a/docs/html-ndk/ndk/guides/index.jd b/docs/html-ndk/ndk/guides/index.jd index 8c3ecab0d2e3..3fbfb47a6985 100644 --- a/docs/html-ndk/ndk/guides/index.jd +++ b/docs/html-ndk/ndk/guides/index.jd @@ -1,4 +1,17 @@ -page.title=Concepts +page.title=Getting Started @jd:body -

    To use the NDK, you must download it and install it separately from the SDK. To do so, follow these directions. \ No newline at end of file +

    This section provides the information you need to get up and running +with the NDK.

    +
      +
    • Setup
      • +
        +
      • Learn how to set up the NDK, and verify that it's integrated into + your toolchain.
        • +
      +
    • Concepts
      • +
        +
      • Learn some basics about how the NDK works and its components, and about how to use it. +
        • +
      +
    diff --git a/docs/html-ndk/ndk/guides/libs.jd b/docs/html-ndk/ndk/guides/libs.jd new file mode 100644 index 000000000000..1d4d2ac7faa9 --- /dev/null +++ b/docs/html-ndk/ndk/guides/libs.jd @@ -0,0 +1,20 @@ +page.title=Libraries +@jd:body + +
    +

    This section discusses libraries included with the NDK, as well as how to use other people's libraries and modules in your own application. It discusses:

    +
      +
    • Stable APIs
        +
      • This section discusses the stable APIs exposed by the NDK.
        • +
      +
      • +
    • Prebuilt Libraries
        +
      • How to include and use prebuilt libraries in your own application.
        • +
      +
      • +
    • C++ Support
      +
        +
      • Information about the NDK's C++ runtime support library and corresponding header files.
        • +
      +
      • +
    \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/md_1__concepts__concepts.html b/docs/html-ndk/ndk/guides/md_1__concepts__concepts.html deleted file mode 100644 index 2dcf6aed7f64..000000000000 --- a/docs/html-ndk/ndk/guides/md_1__concepts__concepts.html +++ /dev/null @@ -1,4 +0,0 @@ -page.title=Concepts -@jd:body - -

    This section provides a high-level explanation of how the NDK works. The Android NDK is a set of tools allowing you to embed C or C++ (“native code”) into your Android apps. The ability to use native code in Android apps can be particularly useful to developers who wish to do one or more of the following: \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/mips.jd b/docs/html-ndk/ndk/guides/mips.jd new file mode 100644 index 000000000000..1aa1868db7ad --- /dev/null +++ b/docs/html-ndk/ndk/guides/mips.jd @@ -0,0 +1,43 @@ +page.title=MIPS Support +@jd:body + +

    +
    +

    On this page

    + +
      +
    1. Overview
      2. +
    2. Compatibility
      3. +
    +
    +
    + +

    The NDK supports the {@code mips} ABI, which allows native code to run on Android-based devices +that have CPUs supporting the MIPS32 instruction set.

    + +

    Overview

    +

    To generate MIPS machine code, include {@code mips} in your +{@code Application.mk} file's +{@code APP_ABI} definition. For example:

    + +
    +APP_ABI := mips
+
    + +

    For more information about defining the {@code APP_ABI} variable, see +{@code Application.mk}.

    + +

    The build system places generated libraries into {@code $PROJECT/libs/mips/}, where +{@code $PROJECT} represents your project's root directory, and embeds them in your APK under +{@code /lib/mips/}.

    + +

    The Android package manager extracts these libraries when installing your APK on a compatible +MIPS-based device, placing them under your app's private data directory.

    + +

    In the Google Play store, the server filters applications so that a consumer sees only the native +libraries that run on the CPU powering his or her device.

    + +

    Compatibility

    +

    MIPS support requires, at minimum, Android 2.3 (Android API level 9). If your project files +target an older API level, but include MIPS as a targeted platform, the NDK build script +automatically selects the right set of native platform headers/libraries for you.

    \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/ndk-build.jd b/docs/html-ndk/ndk/guides/ndk-build.jd new file mode 100644 index 000000000000..d52d22464bda --- /dev/null +++ b/docs/html-ndk/ndk/guides/ndk-build.jd @@ -0,0 +1,194 @@ +page.title=ndk-build +@jd:body + + + +

    ndk-build is a tiny shell script introduced in Android NDK r4. Its purpose +is simply to invoke the right NDK build script. + +

    Internals

    + +ndk-build is equivalent to:

    + +
    +$GNUMAKE -f <ndk>/build/core/build-local.mk
+<parameters>
+
    + +

    $GNUMAKE points to GNU Make 3.81 or later, and +<ndk> points to your NDK installation directory. You can use +this information to invoke ndk-build from other shell scripts, or even your own +make files.

    + +

    Invoking from the Command Line

    +

    ndk-build lives in the top level the NDK installation directory. To run it from the +command line, invoke it while in or under your application project directory. +For example:

    + +
    +cd <project>
+$ <ndk>/ndk-build
+
    + +

    In this example, <project> points to your +project’s root directory, and <ndk> is the directory where +you installed the NDK. As noted in Setup, you can add {@code $NDK} to your +{@code PATH} to avoid having to type the whole filepath every time you use ndk-build. +Alternatively, you can create an alias.

    +

    +

    Options

    +

    All parameters to ndk-build are passed directly to the underlying GNU {@code make} +command that runs the NDK build scripts. Combine ndk-build and +options in the form ndk-build <option>. For example:

    + +
    +$ ndk-build clean
+
    + +

    The following options are available:

    +
    +
    {@code clean}
    +
    Remove any previously generated binaries.
    +
    {@code V=1}
    +
    Launch build, and display build commands.
    +
    {@code -B}
    +
    Force a complete rebuild.
    +
    {@code -B V=1}
    +
    Force a complete rebuild, and display build commands.
    +
    {@code NDK_LOG=1} +
    Display internal NDK log messages (used for debugging the NDK itself).
    +
    {@code NDK_DEBUG=1}
    +
    Force a debuggable build (see Table 1).
    +
    {@code NDK_DEBUG=0}
    +
    Force a release build (see Table 1).
    +
    {@code NDK_HOST_32BIT=1}
    +
    Always use the toolchain in 32-bit mode (see 64-bit and 32-bit + Toolchains).
    +
    {@code NDK_APPLICATION_MK=<file>}
    +
    Build, using a specific Application.mk file pointed to by the + {@code NDK_APPLICATION_MK} variable.
    +
    {@code -C <project>}
    +
    Build the native code for the project path located at {@code <project>}. Useful if you + don't want to {@code cd} to it in your terminal.
    +
    + +

    Invoking from Eclipse

    +

    To build from Eclipse, make sure that you have configured it as described in +Setup. If you +wish to build using the default ndk-build command, with no +options, you can just build your project just as you would any Android project. +To get Eclipse to add any of the options described above, follow these steps:

    +
      +
    1. In the Project Explorer pane, right-click your project name.
      2. +
    2. Select Properties.
      3. +
    3. Click C/C++ Build.
      4. +
    4. Under the Builder Settings tab, uncheck Use default build command.
      5. +
    5. In the Build command field, enter the entire build string as if you were typing it on +the command line.
      6. +
    6. Click OK.
      7. +
    +Figure 1 shows an example of an entered string.
    +
    +enter the build string next to 'Build command' +

    Figure 1. Specifying a debug build from within +Eclipse

    +

    +

    Debuggable versus Release builds

    +

    Use the NDK_DEBUG option and, in certain cases, +{@code AndroidManifest.xml} to specify debug or release build, +optimization-related behavior, and inclusion of symbols. Table 1 shows the +results of each possible combination of settings.

    +

    Table 1. Results of NDK_DEBUG (command line) and +android:debuggable (manifest) combinations.

    + + + + + + + +
    NDK_DEBUG=0 NDK_DEBUG=1NDK_DEBUG not specified +
    android:debuggble="true" Debug; Symbols; Optimized*1 +Debug; Symbols; Not optimized*2 (same as NDK_DEBUG=1) +
    android:debuggable="false"Release; Symbols; Optimized +Release; Symbols; Not optimizedRelease; No symbols; +Optimized*3
    +*1: Useful for profiling.
    +*2: Default for running ndk-gdb.
    +*3: Default mode.
    +
    +

    Note: {@code NDK_DEBUG=0} is the equivalent of +{@code APP_OPTIM=release}, and complies with the GCC {@code -O2} option. {@code NDK_DEBUG=1} is the +equivalent of {@code APP_OPTIM=debug} in {@code Application.mk}, and complies with the GCC +{@code -O0} option. For more information about {@code APP_OPTIM}, see +Application.mk.

    +

    The syntax on the command line is, for example:

    + +
    +$ ndk-build NDK_DEBUG=1
+
    + +

    If you are using build tools from prior to SDK r8, you must also modify your +{@code AndroidManifest.xml} file to specify debug mode. The syntax for doing so resembles the +following:

    + +
    <application android:label="@string/app_name"
+android:debuggable="true">
+
    + +From SDK r8 onward, you do not need to touch {@code AndroidManifest.xml}. Building a debug package +(e.g. with ant debug or the corresponding option of the ADT plugin) causes the tool automatically to +pick the native debug files generated with {@code NDK_DEBUG=1}. + + +

    64-bit and 32-bit toolchains

    +

    Some toolchains come with both 64-bit and 32-bit versions. For example, +directories {@code <ndk>/toolchain/<name>/prebuilt/} and +{@code <ndk>/prebuilt/} may contain both {@code linux-x86} and +{@code linux-x86_64} folders for Linux tools in 32-bit and 64-bit modes, +respectively. The ndk-build script automatically chooses a 64-bit version of +the toolchain if the host OS supports it. You can force the use of a 32-bit +toolchain by using {@code NDK_HOST_32BIT=1} either in your environment or +on the ndk-build command line.

    +

    Note that 64-bit tools utilize host resources better (for instance, they are faster, and handle +larger programs), and they can still generate 32-bit binaries for Android.

    + +

    Requirements

    +

    You need GNU Make 3.81 or later to use ndk-build or the NDK in general. +The build scripts will detect a non-compliant Make tool, and generate an error +message.

    +

    If you have GNU Make 3.81 installed, but the default make +command doesn’t launch it, define {@code GNUMAKE} in your environment to point to it +before launching ndk-build. For example:

    + +
    +$ export GNUMAKE=/usr/local/bin/gmake
+$ ndk-build
+
    + +

    You can override other host prebuilt tools in {@code $NDK/prebuilt/<OS>/bin/} +with the following environment variables:

    + +
    +$ export NDK_HOST_AWK=<path-to-awk>
+$ export NDK_HOST_ECHO=<path-to-echo>
+$ export NDK_HOST_CMP=<path-to-cmp>
+
    diff --git a/docs/html-ndk/ndk/guides/ndk-gdb.jd b/docs/html-ndk/ndk/guides/ndk-gdb.jd new file mode 100644 index 000000000000..2370ba2a90f6 --- /dev/null +++ b/docs/html-ndk/ndk/guides/ndk-gdb.jd @@ -0,0 +1,241 @@ +page.title=ndk-gdb +@jd:body + +
    +
    +

    On this page

    + +
      +
    1. Requirements
      2. +
    2. Usage
      3. +
    3. Thread Support
      4. +
    +
    +
    + +

    The NDK includes a helper shell script named {@code ndk-gdb} to easily launch a native debugging + session for your NDK-generated machine code.

    + +

    Requirements

    + +

    For native debugging to work, you must follow these requirements:

    + +
      +
    • Build your app using the {@code ndk-build} script. The {@code ndk-gdb} script +does not support using the legacy {@code make APP=<name>} method to build.

      • +
    • Enable app debugging in your {@code AndroidManifest.xml} file by including an +{@code <application>} element that sets the {@code android:debuggable} attribute to {@code +true}.
      • +
    • Build your app to run on Android 2.2 (Android API level 8) or higher.
      • +
    • Debug on a device or emulator running Android 2.2 or higher. For debugging purposes, the target +API level that you declare in your {@code AndroidManifest.xml} file does not matter.
      • +
    • Develop your app in a Unix shell. On Windows, use Cygwin +or the experimental {@code ndk-gdb-py} Python +implementation.
      • +
    • Use GNU Make 3.81 or higher.
      • +
    • If you are building your app from +Eclipse, build it +using version 0.9.7 or higher of the ADT plug-in.
      • + +

      Usage

      + To invoke the {@code ndk-gdb} script, change into the application directory or any directory under + it. For example:

      + +
      +cd $PROJECT
+$NDK/ndk-gdb
+
      + +

      Here, {@code $PROJECT} points to your project's root directory, and {@code $NDK} points to your +NDK installation path.

      + +

      When you invoke {@code ndk-gdb}, it configures the session to look for your source files +and symbol/debug versions of your generated native libraries. On successfully attaching to your +application process, {@code ndk-gdb} outputs a long series of error messages, noting that it cannot +find various system libraries. This is normal, because your host machine does not contain +symbol/debug versions of these libraries on your target device. You can safely ignore these +messages.

      + +

      Next, {@code ndk-gdb} displays a normal GDB prompt.

      + +

      You interact with {@code ndk-gdb} in the same way as you would with GNU GDB. For example, you can +use {@code b <location>} to set breakpoints, and {@code c} (for "continue") to +resume execution. For a comprehensive list of commands, see the +GDB manual.

      + +

      Note that when you quit the GDB prompt, the application process that you're debugging stops. This +behavior is a gdb limitation.

      + +

      {@code ndk-gdb} handles many error conditions, and displays an informative error message if it +finds a problem. these checks include making sure that the following conditions are satisfied:

      + +
        +
      • Checks that ADB is in your path.
        • +
      • Checks that your application is declared debuggable in its manifest.
        • +
      • Checks that, on the device, the installed application with the same package name is also +debuggable.
        • +
      + +

      By default, {@code ndk-gdb} searches for an already-running application process, and displays an +error if it doesn't find one. You can, however, use the {@code --start} or +{@code --launch=<name>} option to automatically start your activity before the debugging +session. For more information, see Options.

      + + +

      Options

      +

      To see a complete list of options, type {@code ndk-gdb --help} on the command line. Table 1 +shows a number of the more commonly used ones, along with brief descriptions.

      + +

      + Table 1. Common ndk-gdb options and their descriptions.

      + + + + + + + + + + + + + + + + + + + + + +

      Starting {@code ndk-gdb} with this option specified launches the first launchable activity listed +in your application manifest. Use {@code --launch=<name>} to start the next launchable +activity. To dump the list of launchable activities, run {@code --launch-list} from the command +line.

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      OptionDescription>
      {@code --verbose}

      This option tells the build system to print verbose information about the native-debugging +session setup. It is necessary only for debugging problems when the debugger can't connect to the +app, and the error messages that {@code ndk-gdb} displays are not enough.

      {@code --force}By default, {@code ndk-gdb} aborts if it finds that another native debugging session is already + running on the same device. This option kills the other session, and replaces it with a new one. + Note that this option does not kill the actual app being debugged, which you must kill + separately.
      {@code --start}

      When you start {@code ndk-gdb}, it tries by default to attach to an existing running instance of +your app on the target device. You can override this default behavior by using {@code --start} to +explicitly launch the application on the target device before the debugging session.

      {@code --launch=<name>}

      This option is similar to {@code --start}, except that it allows you to start a specific + activity from your application. This feature is only useful if your manifest defines multiple + launchable activities.

      {@code --launch-list}

      This convenience option prints the list of all launchable activity names found in your + app manifest. {@code --start} uses the first activity name.

      {@code --project=<path>}This option specifies the app project directory. It is useful if you want to launch the + script without first having to change to the project directory.

      {@code --port=<port>}

      By default, {@code ndk-gdb} uses local TCP port 5039 to communicate with the app it + is debugging on the target device. Using a different port allows you to natively debug programs + running on different devices or emulators connected to the same host machine.

      {@code --adb=<file>}

      This option specifies the adb +tool executable. It is only necessary if you have not set your path to include that executable.

      +
      +
    • {@code -d}
      • +
    • {@code -e}
      • +
    • {@code -s <serial>}

      • These flags are similar to the adb commands with the same names. Set these flags if you have +several devices or emulators connected to your host machine. Their meanings are as follows:

      +
      +
      {@code -d}
      +
      Connect to a single physical device.
      +
      {@code -e}
      +
      Connect to a single emulator device.
      +
      {@code -s <serial>}
      +
      Connect to a specific device or emulator. Here, {@code <serial>} is the device's name + as listed by the {@code adb devices} command.
      +
      + +

      Alternatively, you can define the {@code ADB_SERIAL} environment variable to list a specific +device, without the need for a specific option.

      +
    • {@code --exec=<file>}
      • +
    • {@code -x <file>}
      • +

      This option tells {@code ndk-gdb} to run the GDB initialization commands found in +{@code <file>} after connecting to the process it is debugging. This is a useful feature if +you want to do something repeatedly, such as setting up a list of breakpoints, and then resuming +execution automatically.

      {@code --nowait}

      Disable pausing the Java code until GDB connects. Passing this option may cause the debugger + to miss early breakpoints.

      +
      {@code --tui} +{@code -t}

      Enable Text User Interface if it is available.

      {@code --gnumake-flag=<flag>}

      This option is an extra flag (or flags) to pass to the +{@code ndk-build} system when +querying it for project information. You can use multiple instances of this option in the +same command.

      {@code --stdcxx-py-pr={auto|none|gnustdcxx[-GCCVER]|stlport}}

      Use specified Python pretty-printers for displaying types in the Standard C++ Library. + {@code auto} mode works by looking at the {@code .so} files for a {@code libstdc++} library, + and as such only works for a shared library. When linking statically to a {@code libstdc++} library, + you must specify the required printers. The default is {@code none}.

      + +

      Note: The final three options in this table are only for the +Python version of {@code ndk-gdb}.

      + +

      Thread Support

      +

      If your app runs on a platform older than Android 2.3 (API level 9), {@code ndk-gdb} +cannot debug native threads properly. The debugger can only debug the main thread, abd completely +ignores the execution of other threads.

      + +

      Using a version of Android prior to 2.3 causes {@code ndk-gdb} to display the following message +prior to showing the GDB prompt:

      + +
      +Thread debugging is unsupported on this Android platform!
+
      + + +

      If you place a breakpoint on a function executed on a non-main thread, the program exits, and +GDB displays the following message:

      + +
      +Program terminated with signal SIGTRAP, Trace/breakpoint trap.
+      The program no longer exists.
+
      diff --git a/docs/html-ndk/ndk/guides/ndk-stack.jd b/docs/html-ndk/ndk/guides/ndk-stack.jd new file mode 100644 index 000000000000..27c752af12c8 --- /dev/null +++ b/docs/html-ndk/ndk/guides/ndk-stack.jd @@ -0,0 +1,84 @@ +page.title=ndk-stack +@jd:body + +
      +
      +

      On this page

      + +
        +
      1. Usage
        2. +
      +
      +
      + +

      The {@code ndk-stack} tool allows you to filter stack traces as they appear in the +output of {@code adb logcat}, and replace any address inside a shared library with the corresponding +{@code <source-file>:<line-number>} values.

      + +

      For example, it translates something like:

      + +
      +I/DEBUG   (   31): *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
+I/DEBUG   (   31): Build fingerprint: 'generic/google_sdk/generic/:2.2/FRF91/43546:eng/test-keys'
+I/DEBUG   (   31): pid: 351, tid: 351  %gt;%gt;%gt; /data/local/ndk-tests/crasher <<<
+I/DEBUG   (   31): signal 11 (SIGSEGV), fault addr 0d9f00d8
+I/DEBUG   (   31):  r0 0000af88  r1 0000a008  r2 baadf00d  r3 0d9f00d8
+I/DEBUG   (   31):  r4 00000004  r5 0000a008  r6 0000af88  r7 00013c44
+I/DEBUG   (   31):  r8 00000000  r9 00000000  10 00000000  fp 00000000
+I/DEBUG   (   31):  ip 0000959c  sp be956cc8  lr 00008403  pc 0000841e  cpsr 60000030
+I/DEBUG   (   31):          #00  pc 0000841e  /data/local/ndk-tests/crasher
+I/DEBUG   (   31):          #01  pc 000083fe  /data/local/ndk-tests/crasher
+I/DEBUG   (   31):          #02  pc 000083f6  /data/local/ndk-tests/crasher
+I/DEBUG   (   31):          #03  pc 000191ac  /system/lib/libc.so
+I/DEBUG   (   31):          #04  pc 000083ea  /data/local/ndk-tests/crasher
+I/DEBUG   (   31):          #05  pc 00008458  /data/local/ndk-tests/crasher
+I/DEBUG   (   31):          #06  pc 0000d362  /system/lib/libc.so
+I/DEBUG   (   31):
+
      + +

      Into the more readable output:

      + +
      +********** Crash dump: **********
+Build fingerprint: 'generic/google_sdk/generic/:2.2/FRF91/43546:eng/test-keys'
+pid: 351, tid: 351  >>> /data/local/ndk-tests/crasher <<<
+signal 11 (SIGSEGV), fault addr 0d9f00d8
+Stack frame #00  pc 0000841e  /data/local/ndk-tests/crasher : Routine zoo in /tmp/foo/crasher/jni/zoo.c:13
+Stack frame #01  pc 000083fe  /data/local/ndk-tests/crasher : Routine bar in /tmp/foo/crasher/jni/bar.c:5
+Stack frame #02  pc 000083f6  /data/local/ndk-tests/crasher : Routine my_comparison in /tmp/foo/crasher/jni/foo.c:9
+Stack frame #03  pc 000191ac  /system/lib/libc.so
+Stack frame #04  pc 000083ea  /data/local/ndk-tests/crasher : Routine foo in /tmp/foo/crasher/jni/foo.c:14
+Stack frame #05  pc 00008458  /data/local/ndk-tests/crasher : Routine main in /tmp/foo/crasher/jni/main.c:19
+Stack frame #06  pc 0000d362  /system/lib/libc.so
+
      + +

      Usage

      +

      To use {@code ndk-stack}, you first need a directory containing symbolic versions of your app's +shared libraries. If you use the NDK build system ({@code ndk-build}), these shared-library +files reside under {@code $PROJECT_PATH/obj/local/<abi>}, where {@code <abi>} represents +your device's ABI. By default, the system uses the {@code armeabi} ABI.

      + +

      There are two ways to use the tool. You can feed the logcat text as direct input to the program. +For example:

      + +
      +adb logcat | $NDK/ndk-stack -sym $PROJECT_PATH/obj/local/armeabi
+
      + +

      You can also use the {@code -dump} option to specify the logcat as an input file. For example: +

      + +
      +adb logcat > /tmp/foo.txt
+$NDK/ndk-stack -sym $PROJECT_PATH/obj/local/armeabi -dump foo.txt
+
      + +

      When it begins parsing the logcat output, the tool looks for an initial line of asterisks. +For example:

      + +
      +*** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
+
      + +

      Note: When copy/pasting traces, don't forget this line, or +{@code ndk-stack} won't work correctly.

      \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/prebuilts.jd b/docs/html-ndk/ndk/guides/prebuilts.jd new file mode 100644 index 000000000000..f0530d197a44 --- /dev/null +++ b/docs/html-ndk/ndk/guides/prebuilts.jd @@ -0,0 +1,145 @@ +page.title=Using Prebuilt Libraries +@jd:body + + + +

      The NDK supports the use of prebuilt libraries, both static and shared. There are two principal +use cases for this functionality:

      + +
        +
      • Distributing your own libraries to third-party NDK developers without distributing your + sources.
        • +
      • Using a prebuilt version of your own libraries to speed up your build.
        • +
      + +

      This page explains how to use prebuilt libraries.

      + +

      Declaring a Prebuilt Library

      +

      You must declare each prebuilt library you use as a single independent module. To do + so, perform the following steps: + +

        +
      1. Give the module a name. This name does not need to be the same as that of the prebuilt + library, itself.
        2. +
      2. In the module's {@code Android.mk} + file, assign to {@code LOCAL_SRC_FILES} the path to the prebuilt library you are providing. + Specify the path relative to the value of your {@code LOCAL_PATH} variable.

        +

        Note: You must make sure to select the version of your prebuilt + library appropriate to your target ABI. For more information on ensuring library support for + ABIs, see Selecting ABIs for Prebuilt Libraries.

        3. +
      3. Include {@code PREBUILT_SHARED_LIBRARY} or {@code PREBUILT_STATIC_LIBRARY}, depending on + whether you are using a shared ({@code .so}) or static {@code .a}) library.
        4. +
      + +

      Here is a trivial example that assumes that the prebuilt library {@code libfoo.so} resides in + the same directory as the {@code Android.mk} + file that describes it.

      + +
      +LOCAL_PATH := $(call my-dir)
+
+include $(CLEAR_VARS)
+LOCAL_MODULE := foo-prebuilt
+LOCAL_SRC_FILES := libfoo.so
+include $(PREBUILT_SHARED_LIBRARY)
+
      + +

      In this example, the name of the module is the same as that of the prebuilt library.

      + +

      The build system places a copy of your prebuilt shared library into {@code $PROJECT/obj/local}, +and another copy, stripped of debug information, into {@code $PROJECT/libs/<abi>}. Here, +{@code $PROJECT} is the root directory of your project.

      + +

      Referencing the Prebuilt Library from Other Modules

      +

      To reference a prebuilt library from other modules, specify its name as the value +of the {@code LOCAL_STATIC_LIBRARIES} or {@code LOCAL_SHARED_LIBRARIES} variable in the +{@code Android.mk} files associated with those +other modules.

      + +

      For example, the description of a module using {@code libfoo.so} might be as follows:

      + +
      +include $(CLEAR_VARS)
+LOCAL_MODULE := foo-user
+LOCAL_SRC_FILES := foo-user.c
+LOCAL_SHARED_LIBRARIES := foo-prebuilt
+include $(BUILD_SHARED_LIBRARY)
+
      + +

      Here, {@code LOCAL_MODULE} is the name of the module referring to the prebuilt; {@code + LOCAL_SHARED_LIBRARIES} is the name of the prebuilt, itself.

      + +

      Exporting Headers for Prebuilt Libraries

      +

      The code in {@code foo-user.c} depends on specific declarations that normally +reside in a header file, such as {@code foo.h}, distributed with the prebuilt library. +For example, {@code foo-user.c} might have a line like the following:

      + +
      +#include <foo.h>
+
      + +

      In such a case, you need to provide the header and its include path to the compiler when you +build the {@code foo-user} module. A simple way to accomplish this task is to use exports in the +prebuilt module definition. For example, as long as header {@code foo.h} is located under the +{@code include} directory associated with the prebuilt module, you can declare it as follows:

      + +
      +include $(CLEAR_VARS)
+LOCAL_MODULE := foo-prebuilt
+LOCAL_SRC_FILES := libfoo.so
+LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include
+include $(PREBUILT_SHARED_LIBRARY)
+
      + +

      The {@code LOCAL_EXPORT_C_INCLUDES} definition here ensures that the build system +exports the path to the prebuilt library's {@code include} directory, prepending that path onto the +value of the {@code LOCAL_C_INCLUDES} for the module dependent on it.

      + +

      This operation allows the build system to find the necessary headers.

      + +

      Debugging Prebuilt Libraries

      +

      We recommend that you provide prebuilt shared libraries containing debug symbols. The NDK build +system always strips the symbols from the version of the library that it installs into +{@code $PROJECT/libs/<abi>/}, but you can use the debug version for debugging with +{@code ndk-gdb}.

      + +

      Selecting ABIs for Prebuilt Libraries

      +

      You must make sure to select the right version of your prebuilt shared library for your targeted +ABI. The +{@code TARGET_ARCH_ABI} variable in the +{@code Android.mk} file can point the build system at the appropriate version of the library. +

      + +

      For example, assume that your project contains two versions of library {@code libfoo.so}:

      + +
      +armeabi/libfoo.so
+x86/libfoo.so
+
      + +

      The following snippet shows how to use {@code TARGET_ARCH_ABI} so that the build system selects + the appropriate version of the library:

      + +
      +include $(CLEAR_VARS)
+LOCAL_MODULE := foo-prebuilt
+LOCAL_SRC_FILES := $(TARGET_ARCH_ABI)/libfoo.so
+LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include
+include $(PREBUILT_SHARED_LIBRARY)
+
      + +

      If you have specified {@code armeabi} as the value of {@code TARGET_ARCH_ABI}, the build system +uses the version of {@code libfoo.so} located in the {@code armeabi} directory. If you have +specified {@code x86} as the value {@code TARGET_ARCH_ABI}, the build system uses the version in the +{@code x86} directory.

      \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/sample.jd b/docs/html-ndk/ndk/guides/sample.jd new file mode 100644 index 000000000000..18ca0b82a0b0 --- /dev/null +++ b/docs/html-ndk/ndk/guides/sample.jd @@ -0,0 +1,11 @@ +page.title=Sample Walkthroughs +@jd:body + +
      +

      This section explains several of the sample apps provided with the NDK. It assumes that you already have a working knowledge of programming in Java and native code, and focuses on issues particular to working with the NDK.

      +

      It discusses the following samples:

      +
        +
      • hello-jni: A very basic app that illustrates core workings of the NDK.
        • +
      • native-activity: An app that shows the fundamentals of how to construct a purely native app. It places particular emphasis on the android_native_app_glue library.
        • +
      • Teapot: A simple OpenGL demo, showcasing the ndk_helper class.
        • +
      \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/sample_hellojni.jd b/docs/html-ndk/ndk/guides/sample_hellojni.jd new file mode 100644 index 000000000000..f05f042d4fe8 --- /dev/null +++ b/docs/html-ndk/ndk/guides/sample_hellojni.jd @@ -0,0 +1,122 @@ +page.title=Sample: HelloJNI +@jd:body + + + +

      This sample provides a bare-bones look at a minimal +application built with the NDK.

      + +

      Android.mk

      + +

      The following two lines provide the name of the native source file, along +with the name of the shared library to build. The full name of the built +library is {@code libhello-jni.so}, but you should omit the +{@code lib} prefix and the {@code .so} extension.

      + +
      +LOCAL_SRC_FILES := hello-jni.c
+LOCAL_MODULE    := hello-jni
+
      + +

      For more information on what this file does, and how to use it, see +Android.mk.

      + +

      Application.mk

      +

      This line tells the build system the architecture against which to build. If +you don't specify anything, the build system defaults to {@code armeabi}.

      + +
      +APP_ABI := all
+
      + +

      For more information on what this file does, and how to use it, see +Application.mk.

      + +

      Java-side implementation

      +

      This file calls a function to retrieve a string from the native side, then +displays it on the screen.

      + +

      The source code contains three lines of particular interest to the NDK user. +They are presented here in the order in which they are used, rather than by +line order.

      + +

      This function call loads the {@code .so} file upon application startup.

      + +
      +System.loadLibrary("hello-jni");
+
      + +

      The {@code native} keyword in this method declaration tells the +virtual machine that the function is in the shared library (i.e., implemented on the native side). +

      + +
      +public native String stringFromJNI();
+
      + +

      The Android framework calls the function loaded and declared in the +previous steps, displaying the string on the screen.

      + +
      +tv.setText( stringFromJNI() );
+
      + +

      C-side implementation

      +

      This file contains a function that returns a string that the Java side +requested (see Java-side implementation). The function declaration is as +follows:

      + +
      +jstring Java_com_example_hellojni_HelloJni_stringFromJNI(
+JNIEnv* env,
+                                              jobject x )
+
      + +

      This declaration corresponds to the native function declared in the +Java source code. The return type, {@code jstring}, is a data type defined +in the +Java Native +Interface Specification. It is not actually a string, but a +pointer to a Java string.

      + +

      After {@code jstring} comes the function name, which is based on the +Java function name and and the path to the file containing it. Construct it +according to the following rules:

      + +
        +
      • Prepend {@code Java_} to it.
        • +
      • Describe the filepath relative to the top-level source directory.
        • +
      • Use underscores in place of forward slashes.
        • +
      • Omit the {@code .java} file extension.
        • +
      • After the last underscore, append the function name.
        • +
      + +

      Based on these rules, in this example, the function name +{@code Java_com_example_hellojni_HelloJni_stringFromJNI} refers to a Java +function called {@code stringFromJNI()}, which resides in +{@code hellojni/src/com/example/hellojni/HelloJni.java}.

      + +

      Finally, {@code JNIEnv*} is the pointer to the VM, and +{@code jobject} is a pointer to the implicit {@code this} object passed from +the Java side.

      + +

      The following line calls the VM API {@code (*env)}, and passes it a return value: +that is, the string that the function on the Java side had requested.

      + +
      +return (*env)->NewStringUTF(env, "Hello from JNI !
+Compiled with ABI " ABI ".");
+
      \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/sample_na.jd b/docs/html-ndk/ndk/guides/sample_na.jd new file mode 100644 index 000000000000..e6f36ba19f29 --- /dev/null +++ b/docs/html-ndk/ndk/guides/sample_na.jd @@ -0,0 +1,194 @@ +page.title=Sample: Native Activity +@jd:body + + + +

      This is a very simple example of a purely native +application, with no Java source code. In the absence of any Java source, the +Java compiler still creates an executable stub for the Dalvik Virtual Machine +("DVM") to run. The stub serves as a wrapper for the actual, native program, +which lives in the .so file.

      +

      The application itself simply renders a color onto the entire screen, and +then changes the color partly in response to detected movement.

      +

      AndroidManifest.xml

      +

      Make sure not to specify an Android API level lower than 9.

      +
      <uses-sdk android:minSdkVersion="9" />
+

      Because this application has only native code, specify +android:hasCode as false.

      +
      <application android:label="@string/app_name"
+android:hasCode="false">
+

      Declare the NativeActivity class.

      +
          <activity android:name="android.app.NativeActivity"
+

      For android:value, provide the name of the shared library +to be built, minus the initial lib and the .so +extension. This value must be the same as the one you described for +LOCAL_MODULE in Android.mk.

      +
              <meta-data android:name="android.app.lib_name"
+                android:value="native-activity" />
+

      Android.mk

      +

      This file tells the build system the following information:

      +

      The name of the shared library to generate.

      +
      LOCAL_MODULE    := native-activity
+

      The name of the native source-code file.

      +
      LOCAL_SRC_FILES := main.c
+

      A list of external libraries that will be used in building the binary, +each preceded by the -l (link-against) option.

      +
        +
      • log is a logging library.
        • +
      • android encompasses the standard Android support APIs for NDK. The Stable APIs +section discusses these in more detail.
        • +
      • EGL, standardized by Khronos, corresponds to the platform-specific portion +of the graphics API.
        • +
      • OpenGL ES, the version of OpenGL for Android, depends on EGL.
        • +
      +

      Note that, for each library:

      +
        +
      • The actual file name starts with lib, and ends with the +.so extension. For example, the actual file name for the +log library is liblog.so.
        • +
      • The library lives in the following directory, relative to the NDK root: +<ndk>/platforms/android-<sdk_version>/arch-<abi>/usr/lib/.
        • +
      +
      LOCAL_LDLIBS    := -llog -landroid -lEGL -lGLESv1_CM
+

      A static library, android_native_app_glue, that the +application uses to manage NativeActivity lifecycle events, along +with touch input.

      +
      LOCAL_STATIC_LIBRARIES := android_native_app_glue
+

      The final line tells the build system to build this static library. +ndk-build places the built library +(libandroid_native_app_glue.a) into the obj directory +generated during the build process. The next sample discusses the +android_native_app_glue in more detail.

      +
      $(call import-module,android/native_app_glue)
+

      For more information about the Application.mk file, consult the Application.mk section of this guide.

      +

      Application.mk

      +

      This line defines the minimum level of Android API Level support.

      +
      APP_PLATFORM := android-10
+

      Because there is no ABI definition, the build system defaults to +building only for armeabi.

      +

      main.c

      +

      This file essentially contains the entire progam.

      +

      The following includes correspond to the libraries, both shared and static, +enumerated in Android.mk.

      +
      #include <EGL/egl.h>
+#include <GLES/gl.h>
+
+
+#include <android/sensor.h>
+#include <android/log.h>
+#include <android_native_app_glue>
+

      android_native_app_glue calls the following function, +passing it a predefined state structure. It also serves as a wrapper that +simplifies handling of NativeActivity callbacks.

      +
      void android_main(struct android_app* state) {
+

      Next, the program handles events queued by the glue library. The event +handler follows the state structure.

      +
      struct engine engine;
+
+
+// Make sure glue isn't stripped by suppressing link-time optimization that
+removes unreferenced code.
+app_dummy();
+
+
+memset(&engine, 0, sizeof(engine));
+state->userData = &engine;
+state->onAppCmd = engine_handle_cmd;
+state->onInputEvent = engine_handle_input;
+engine.app = state;
+

      The application prepares to start monitoring the sensors, using the +APIs in sensor.h.

      +
          engine.sensorManager = ASensorManager_getInstance();
+    engine.accelerometerSensor =
+                    ASensorManager_getDefaultSensor(engine.sensorManager,
+                    ASENSOR_TYPE_ACCELEROMETER);
+    engine.sensorEventQueue =
+                    ASensorManager_createEventQueue(engine.sensorManager,
+                    state->looper, LOOPER_ID_USER, NULL, NULL);
+

      Now, a loop begins, in which the application polls the system for +messages (sensor events). It sends messages to +android_native_app_glue, which checks to see whether they match +any onAppCmd events defined in android_main. When a +match occurs, the message is sent to the handler for execution.

      +
      while (1) {
+        // Read all pending events.
+        int ident;
+        int events;
+        struct android_poll_source* source;
+
+
+        // If not animating, we will block forever waiting for events.
+        // If animating, we loop until all events are read, then continue
+        // to draw the next frame of animation.
+        while ((ident=ALooper_pollAll(engine.animating ? 0 : -1, NULL,
+&events,
+                (void**)&source)) >= 0) {
+
+
+            // Process this event.
+            if (source != NULL) {
+                source->process(state, source);
+            }
+
+
+            // If a sensor has data, process it now.
+            if (ident == LOOPER_ID_USER) {
+                if (engine.accelerometerSensor != NULL) {
+                    ASensorEvent event;
+                    while (ASensorEventQueue_getEvents(engine.sensorEventQueue,
+                            &event, 1) > 0) {
+                        LOGI("accelerometer: x=%f y=%f z=%f",
+                                event.acceleration.x, event.acceleration.y,
+                                event.acceleration.z);
+                    }
+                }
+            }
+
+
+        // Check if we are exiting.
+        if (state->destroyRequested != 0) {
+            engine_term_display(&engine);
+            return;
+        }
+    }
+

      Once the queue is empty, and the program exits the polling loop, the +program calls OpenGL to draw the screen.

      +
          if (engine.animating) {
+        // Done with events; draw next animation frame.
+        engine.state.angle += .01f;
+        if (engine.state.angle > 1) {
+            engine.state.angle = 0;
+        }
+
+
+        // Drawing is throttled to the screen update rate, so there
+        // is no need to do timing here.
+        engine_draw_frame(&engine);
+    }
+}
      +
    + + + + diff --git a/docs/html-ndk/ndk/guides/sample_teapot.jd b/docs/html-ndk/ndk/guides/sample_teapot.jd new file mode 100644 index 000000000000..6a321bb67980 --- /dev/null +++ b/docs/html-ndk/ndk/guides/sample_teapot.jd @@ -0,0 +1,236 @@ +page.title=Sample: Teapot +@jd:body + + + +

    This sample uses the OpenGL library to render the +iconic Utah +teapot. It particularly showcases the ndk_helper helper class, +a collection of native helper functions required for implementing games and +similar applications as native applications. This class provides:

    +
      +
    • an abstraction layer that handles certain NDK-specific behaviors (e.g., +GLContext).
      • +
    • some helper functions that are useful but not present in the NDK, itself +(e.g., tap detection).
      • +
    • wrappers for JNI calls for certain platform features (e.g., texture +loading).
      • +
    +

    AndroidManifest.xml

    +

    The activity declaration here is not NativeActivity itself, but +a subclass: TeapotNativeActivity.

    +
        <activity
+android:name="com.sample.teapot.TeapotNativeActivity"
+            android:label="@string/app_name"
+            android:configChanges="orientation|keyboardHidden">
+

    The name of the .so file is +libTeapotNativeActivity.so; the lib and +.so are stripped off from the value assigned to +android:value.

    +
            <meta-data android:name="android.app.lib_name"
+                android:value="TeapotNativeActivity" />
+

    Application.mk

    +

    Define the minimum level of Android API Level support.

    +
    APP_PLATFORM := android-9
+

    Build for all supported architectures.

    +
    APP_ABI := all
+

    Specify the C++ + runtime support library to use.

    +
    APP_STL := stlport_static
+

    Java-side implementation: TeapotNativeActivity.java

    +

    This file handles activity lifecycle events, as well as displaying text on +the screen.

    +
    // Our popup window, you will call it from your C/C++
+code later
+
+
+void setImmersiveSticky() {
+    View decorView = getWindow().getDecorView();
+    decorView.setSystemUiVisibility(View.SYSTEM_UI_FLAG_FULLSCREEN
+            | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
+            | View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY
+            | View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
+            | View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
+            | View.SYSTEM_UI_FLAG_LAYOUT_STABLE);
+}
+

    Native-side implementation

    + +

    This section explores the C++ part of the Teapot app.

    + +

    TeapotRenderer.*

    + +

    This code does the actual rendering of the teapot. It uses +ndk_helper for matrix calculation, and to reposition the camera +based on where the user taps:

    + +
    +ndk_helper::Mat4 mat_projection_;
+ndk_helper::Mat4 mat_view_;
+ndk_helper::Mat4 mat_model_;
+
+
+ndk_helper::TapCamera* camera_;
+
    + +

    TeapotNativeActivity.cpp

    + +

    Include ndk_helper in your native source file, and define the +helper-class name:

    +
    #include "NDKHelper.h"
+
+
+//-------------------------------------------------------------------------
+//Preprocessor
+//-------------------------------------------------------------------------
+#define HELPER_CLASS_NAME "com/sample/helper/NDKHelper" //Class name of helper
+function
+

    The first use of the ndk_helper class is to handle the +EGL-related lifecycle, associating EGL context states (created/lost) with +Android lifecycle events. It enables the application to preserve context +information so that a destroyed activity can be restored. This is useful, for +example, when the target machine is rotated (causing an activity to be +destroyed, then immediately restored in the new orientation), or when the lock +screen appears.

    +
    ndk_helper::GLContext* gl_context_; // handles
+EGL-related lifecycle.
+

    Next, ndk_helper provides touch control.

    +
    ndk_helper::DoubletapDetector doubletap_detector_;
+ndk_helper::PinchDetector pinch_detector_;
+ndk_helper::DragDetector drag_detector_;
+ndk_helper::PerfMonitor monitor_;
+

    And camera control (openGL view frustum).

    +
    ndk_helper::TapCamera tap_camera_;
+

    As in the native-activity sample, the application prepares to use the +sensors, using the native APIs provided in the NDK.

    +
    ASensorManager* sensor_manager_;
+const ASensor* accelerometer_sensor_;
+ASensorEventQueue* sensor_event_queue_;
+

    The following functions are called in response to various Android +lifecycle events and EGL context state changes, using various functionalities +provided by ndk_helper via the Engine class.

    +
    void LoadResources();
+void UnloadResources();
+void DrawFrame();
+void TermDisplay();
+void TrimMemory();
+bool IsReady();
+

    This function calls back to the Java side to update the UI display.

    +
    void Engine::ShowUI()
+{
+    JNIEnv *jni;
+    app_->activity->vm->AttachCurrentThread( &jni, NULL );
+
+
+    //Default class retrieval
+    jclass clazz = jni->GetObjectClass( app_->activity->clazz );
+    jmethodID methodID = jni->GetMethodID( clazz, "showUI", "()V" );
+    jni->CallVoidMethod( app_->activity->clazz, methodID );
+
+
+    app_->activity->vm->DetachCurrentThread();
+    return;
+}
+

    And this one calls back to the Java side to draw a text box +superimposed on the screen rendered on the native side, and showing frame +count.

    +
    void Engine::UpdateFPS( float fFPS )
+{
+    JNIEnv *jni;
+    app_->activity->vm->AttachCurrentThread( &jni, NULL );
+
+
+    //Default class retrieval
+    jclass clazz = jni->GetObjectClass( app_->activity->clazz );
+    jmethodID methodID = jni->GetMethodID( clazz, "updateFPS", "(F)V" );
+    jni->CallVoidMethod( app_->activity->clazz, methodID, fFPS );
+
+
+    app_->activity->vm->DetachCurrentThread();
+    return;
+}
+

    The application gets the system clock and supplies it to the renderer +for time-based animation based on real-time clock. For example, calculating +momentum, where speed declines as a function of time.

    +
    renderer_.Update( monitor_.GetCurrentTime() );
+

    Having earlier been set up to preserve context information, the +application now checks whether GLcontext is still valid. If not, +ndk-helper swaps the buffer, reinstantiating the GL context.

    +
    if( EGL_SUCCESS != gl_context_->Swap() )  // swaps
+buffer.
+

    The program passes touch-motion events to the gesture detector defined +in the ndk_helper class. The gesture detector tracks multitouch +gestures, such as pinch-and-drag, and sends a notification when triggered by +any of these events.

    +
    if( AInputEvent_getType( event ) ==
+AINPUT_EVENT_TYPE_MOTION )
+{
+    ndk_helper::GESTURE_STATE doubleTapState =
+eng->doubletap_detector_.Detect( event );
+    ndk_helper::GESTURE_STATE dragState = eng->drag_detector_.Detect( event
+);
+    ndk_helper::GESTURE_STATE pinchState = eng->pinch_detector_.Detect(
+event );
+
+
+    //Double tap detector has a priority over other detectors
+    if( doubleTapState == ndk_helper::GESTURE_STATE_ACTION )
+    {
+        //Detect double tap
+        eng->tap_camera_.Reset( true );
+    }
+    else
+    {
+        //Handle pinch state
+        if( pinchState & ndk_helper::GESTURE_STATE_START )
+        {
+            //Start new pinch
+            ndk_helper::Vec2 v1;
+            ndk_helper::Vec2 v2;
+            eng->pinch_detector_.GetPointers( v1, v2 );
+

    ndk_helper also provides access to a vector-math library +(vecmath.h), using it here to transform touch coordinates.

    +
    void Engine::TransformPosition( ndk_helper::Vec2& vec
+) { vec = ndk_helper::Vec2( 2.0f, 2.0f ) * vec / ndk_helper::Vec2(
+gl_context_->GetScreenWidth(), gl_context_->GetScreenHeight() )
+
+ndk_helper::Vec2( 1.f, 1.f ); }
    + +

    HandleCmd() handles commands posted from the +android_native_app_glue library. For more information about what the messages +mean, refer to the comments in the android_native_app_glue.h and +.c source files.

    + +
    +void Engine::HandleCmd( struct android_app* app, int32_t
+cmd ) { Engine* eng = (Engine*) app->userData; switch( cmd ) { case
+APP_CMD_SAVE_STATE: break; case APP_CMD_INIT_WINDOW: // The window is being
+shown, get it ready. if( app->window != NULL )
+
    + +

    ndk_helper posts APP_CMD_INIT_WINDOW when android_app_glue +receives an onNativeWindowCreated() callback from the system. +Applications can normally perform window initializations, such as EGL +initialization. They do this outside of the activity lifecycle, since the +activity is not yet ready.

    +
    ndk_helper::JNIHelper::Init( state->activity,
+HELPER_CLASS_NAME );
+
+
+state->userData = &g_engine;
+state->onAppCmd = Engine::HandleCmd;
+state->onInputEvent = Engine::HandleInput;
    \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/setup.html b/docs/html-ndk/ndk/guides/setup.html new file mode 100644 index 000000000000..0b441323b35b --- /dev/null +++ b/docs/html-ndk/ndk/guides/setup.html @@ -0,0 +1,520 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Setup | Android Developers + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + + + + + +
    + + + + + + +
    + + + + + + +
    + + + + + + + +

    Setup

    + + + + + + +
    + + +
    +
    +
    +

    On this page

    + +
      +
    1. Installation
      2. +
    2. Configuring Eclipse
      3. +
    3. Verification
      4. +
    + + +
    +
    + + +
    +

    This document explains how to:

    +
      +
    • Get and install the NDK.
      • +
    • Configure your system and the Eclipse and the Android Development Tool +(ADT) for use with it.
      • +
    • Verify, using a simple sample, that everything is working as expected. +
      • +
    +

    This document assumes that you are already familiar with Java-based Android development. For more +information on that topic, see the +Android developer site.

    + +

    Installation

    +

    To install and configure the NDK, follow these steps:

    +
      +
    1. Get and install the Android SDK.if you +have not already done so.
      2. +
    2. Download and unzip the NDK, +making sure to download the correct version for your development platform. You may place the +unzipped directory anywhere on your local drive.
      3. +
    3. Update your PATH environment variable with the location of the directory that +contains the NDK.
      4. +
    + + +

    Configuring Eclipse

    +

    Eclipse must know where the NDK is in order to use it when building your app. Follow these steps +to set the location of the NDK.

    +
      +
    1. Launch Eclipse, which is installed as part of the Android SDK.
      2. +
    2. Open Window > Preferences.
      3. +
    3. In the pane on the left side of the Preferences window, select Android. +The Android section expands, revealing a number of subsections.
      4. +
    4. Select NDK. In the pane on the right side of the Preferences window, browse to +the directory that contains the NDK.
      5. +
    5. Click OK to return to the Package Explorer display.
      6. +
    + +

    Verification

    +

    Eclipse

    +

    To confirm that you have installed the NDK, set it up correctly, and properly configured Eclipse, +follow these steps:

    +
      +
    1. Import the hello-jni sample from <ndk>/samples/, as you would any other Android +project.
      2. +
    2. In the Project Explorer pane, right-click the project name (HelloJni). A +context menu appears.
      3. +
    3. From the context menu, select Android Tools > Add Native Support. The +Add Android Native Support window appears.
      4. +
    4. Accept the default library name (“hello-jni”), and click Finish.
      5. +
    5. Build and execute the application.
      6. +
    +

    Command line

    +

    Follow these steps to build from the command line:

    +
      +
    1. Change to the root directory of your project.
      2. +
    2. Execute ndk-build to build the native component of your app. do this by +typing ndk-build at the command prompt.
      3. +
    3. Build and install your project as you would a regular Android app written in Java. For more +information, see +Building and Running and +Building and Running +from the Command Line.
      4. +
    + +

    If you have successfully installed and configured the NDK, the screen on your target device looks +as shown in Figure 1.

    + +Output: Hello from JNI! + +

    +Figure 1. Target-device screen after successful launch. +

    + +
    + +
    + +
    + +
    +
    + +
    + +
    + +
    + +
    + + +
    + +
    + + + + + + + + + + + + + + + + diff --git a/docs/html-ndk/ndk/guides/stable_apis.jd b/docs/html-ndk/ndk/guides/stable_apis.jd new file mode 100644 index 000000000000..a3fedcc86926 --- /dev/null +++ b/docs/html-ndk/ndk/guides/stable_apis.jd @@ -0,0 +1,501 @@ +page.title=Android NDK Native APIs +@jd:body + + + +

    The Android NDK provides a set of native headers and shared library files that has gradually +increased with successive releases of new Android API levels. This page explains these headers and +files, and maps them to specific + Android API levels. +

    + +

    Overview

    +

    There are two basic steps to enable your app to use the libraries that the NDK provides: +

    + +
      +
    1. Include in your code the headers associated with the libraries you wish to use.
      2. + +
    2. Tell the build system that your native module needs to link against the libraries at load time. +For example, to link against {@code /system/lib/libfoo.so}, add the following line to your +Android.mk file:
      3. + +
      +LOCAL_LDLIBS := -lfoo
+
      + +

      To list multiple libraries, use a space as a delimiter. For more information about using the +{@code LOCAL_LDLIBS} variable, see Android.mk. +

      + +
    + +

    For all API levels, the build system automatically links the standard C libraries, the +standard C++ libraries, real-time extensions, and {@code pthread}; you do not need +to include them when defining your {@code LOCAL_LDLIBS} variable. For more information about +the C and C++ libraries, see Android API level 3.

    + +

    The NDK often provides new headers and libraries for new Android releases. These files reside +under {@code $NDK/platforms/android-<level>/<abi>/usr/include}. When the NDK does not +have a specific new group of headers and libraries for an Android API level, it means that +an app targeting that level should use the most recently released NDK assets. For example, +there was no new release of NDK headers or libraries for Android API levels 6 and 7. Therefore, +when developing an app targeting Android API level 7, you would use the headers and libraries +located under {@code android-5/}.

    + +

    Table 1 shows the correspondence between NDK-supported API levels and Android releases.

    + +

    + Table 1. NDK-supported API levels and corresponding Android releases.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NDK-supported API levelAndroid release
    31.5
    41.6
    52.0
    82.2
    92.3 through 3.0.x
    123.1.x
    133.2
    144.0 through 4.0.2
    154.0.3 and 4.0.4
    164.1 and 4.1.1
    174.2 and 4.2.2
    184.3
    194.4
    214.4W and 5.0
    + +

    Each new release of NDK headers and libraries for a given Android API level is cumulative; you +are nearly always safe if you use the most recently released headers when building your app. For +example, you can use the NDK headers for Android API level 21 for an app targeting API level 16. By doing so, however, you increase your APK's footprint.

    + +

    +For more information about Android API levels, see +What is API Level?. +

    + +

    Major Native API Updates

    + +

    Android API level 3

    +

    The NDK provides the following APIs for developing native code that runs on Android 1.5 system +images and above.

    + +

    C library

    +

    The C library headers for Android 1.5 are available through their standard names, such as +{@code stdlib.h} and {@code stdio.h}. If a header is missing at build time, it's because the +header is not available on the 1.5 system image.

    + +

    C++ library

    +

    An extremely minimal C++ support API is available. For more +information on C++ library support, see +C++ Library Support.

    + +

    Android-specific log support

    + +

    {@code <android/log.h>} contains various definitions that an app can use to send log +messages to the kernel from native code. For more information about these definitions, see the +comments in {@code $NDK/platforms/android-3/arch-arm/usr/include/android/log.h}, where {@code $NDK} +is the root of your NDK installation.

    + +

    You can write your own wrapper macros to access this functionality. If you wish to perform +logging, your native module should link to {@code /system/lib/liblog.so}. Implement this +linking by including the following line in your +{@code Android.mk} file:

    + +
    +LOCAL_LDLIBS := -llog
+
    + +

    ZLib compression library

    +

    You can use the Zlib compression library +by including {@code zlib.h} and {@code zconf.h}. You must also link your native +module against {@code /system/lib/libz.so} by including the following line in your +{@code Android.mk} file:

    + +
    +LOCAL_LDLIBS := -lz
+
    + +

    Dynamic linker library

    +

    You can access the Android dynamic linker's {@code dlopen()}, {@code dlsym()}, and +{@code dlclose()} functions by including {@code dlfcn.h}. You must also link against +{@code /system/lib/libdl.so} by including the following line in your +{@code Android.mk} file:

    + +
    +LOCAL_LDLIBS := -ldl
+
    + +

    Android API level 4

    +

    The NDK provides the following APIs for developing native code that runs on Android 1.6 system +images and above.

    + +

    OpenGL ES 1.x Library

    +

    The standard OpenGL ES headers {@code gl.h} and {@code glext.h} contain +the declarations necessary for performing OpenGL ES 1.x rendering calls from native code.

    + +

    To use these headers, link your native module to {@code /system/lib/libGLESv1_CM.so} by +including the following line in your +{@code Android.mk} file:

    +

    + +
    +LOCAL_LDLIBS := -lGLESv1_CM
+
    +

    All Android-based devices support OpenGL ES 1.0, because Android provides an Open GL 1.0-capable +software renderer that can be used on devices without GPUs.

    +

    Only Android devices that have the necessary GPU fully support OpenGL ES 1.1. An app can +query the OpenGL ES version string and extension string to determine whether the current device +supports the features it needs. For information on how to perform this query, see the description of +{@code glGetString()} +in the OpenGL specification.

    + +

    Additionally, you must put a +{@code +<uses-feature>} tag in your manifest file to indicate the version of +OpenGL ES +that your application requires.

    + +

    The EGL APIs are only available starting from API level 9. You can, however, +use the VM to perform some of the operations that you would get from those APIS. These operations +include surface creation and flipping. For an example of how to use {@code GLSurfaceView}, see + +Introducing GLSurfaceView.

    + +

    The san-angeles sample application provides an example of how to perform these operations, +rendering each frame in native code. This sample is a small Android port of the excellent +San Angeles Observation demo +program.

    + +

    Android API level 5

    +

    The NDK provides the following APIs for developing native code that runs on Android 2.0 system +images and above.

    + +

    OpenGL ES 2.0 library:

    +

    The standard OpenGL ES 2.0 headers {@code <GLES2/gl2.h>} and {@code <GLES2/gl2ext.h>} +contain the declarations needed for performing OpenGL ES 2.0 rendering calls from native code. +These rendering calls provide the ability to use the GLSL language to define and use vertex and +fragment shaders.

    + +

    To use OpenGL ES 2.0, link your native module to {@code /system/lib/libGLESv2.so} by +including the following line in your +{@code Android.mk} file:

    + +
    +LOCAL_LDLIBS := -lGLESv2
+
    + +

    Not all devices support OpenGL ES 2.0. An app can query the OpenGL +ES version string and extension string to determine whether the current device +supports the features it needs. For information on how to perform this query, see the description of + +{@code glGetString()} in the OpenGL specification.

    + +

    Additionally, you must put a +{@code +<uses-feature>} tag in your manifest file to indicate which version of OpenGL ES your +application requires. For more information about the OpenGL ES settings for +{@code <uses-feature>}, see +OpenGL ES.

    + +

    The hello-gl2 sample application provies a basic example of how to use OpenGL ES 2.0 with the +NDK.

    + +

    The EGL APIs are only available starting from API level 9. You can, however, +use the VM to perform some of the operations that you would get from those APIs. These operations +include surface creation and flipping. For an example of how to use {@code GLSurfaceView}, see + +Introducing GLSurfaceView.

    + +

    Note: The Android emulator does not support OpenGL ES 2.0 hardware +emulation. Running and testing code that uses this API requires a real device with hardware that can +support OpenGL ES 2.0.

    + +

    Android API level 8

    +

    The NDK provides the following APIs for developing native code that runs on Android 2.2 system +images and above.

    + +

    jnigraphics

    +

    The {@code jnigraphics} library exposes a C-based interface that allows native code to reliably access +the pixel buffers of Java bitmap objects. The workflow for using {@code jnigraphics} is as follows: +

    + +
      +
    1. Use {@code AndroidBitmap_getInfo()} to retrieve information from JNI, such as width and height, +about a given bitmap handle.
      2. + +
    2. Use {@code AndroidBitmap_lockPixels()} to lock the pixel buffer and retrieve a pointer to it. +Doing so ensures that the pixels do not move until the app calls +{@code AndroidBitmap_unlockPixels()}.
      3. + +
    3. In native code, modify the pixel buffer as appropriate for its pixel format, width, and other +characteristics.
      4. + +
    4. Call {@code AndroidBitmap_unlockPixels()} to unlock the buffer.
      5. +
    + +

    To use {@code jnigraphics}, include the {@code <bitmap.h>} header in your source code, and +link against {@code jnigraphics} by including the following line in your +{@code Android.mk} file:

    + +
    +LOCAL_LDLIBS += -ljnigraphics
+
    + +

    Additional details about this feature are in the comments of the {@code bitmap.h} file. + +

    Android API level 9

    +

    The NDK provides the following APIs for developing native code that runs on Android 2.3 system +images and above.

    + +

    EGL

    +

    EGL provides a native platform interface for allocating and managing OpenGLES surfaces. +For more information about its features, see +EGL Native Platform Interface.

    + +

    EGL allows you to perform the following operations from native code:

    + +
      +
    • List supported EGL configurations.
      • +
    • Allocate and release OpenGLES surfaces.
      • +
    • Swap or flip surfaces.
      • +
    + +

    The following headers provide EGL functionality:

    +
      +
    • {@code EGL/egl.h}: the main EGL API definitions.
      • +
    • {@code EGL/eglext.h}: EGL extension-related definitions.
      • +
    + +

    To link against the system's EGL library, add the following line to your +{@code Android.mk} file:

    + +
    +LOCAL_LDLIBS += -lEGL
+
    + +

    OpenSL ES

    +

    Android native audio handling is based on the Khronos Group OpenSL ES 1.0.1 API.

    + +

    The standard OpenSL ES headers {@code OpenSLES.h} and {@code OpenSLES_Platform.h} contain +the declarations necessary for performing audio input and output from the native side of Android. +The NDK distribution of the OpenSL ES also provides Android-specific extensions. For information +about these extensions, see the comments in {@code OpenSLES_Android.h} and +{@code OpenSLES_AndroidConfiguration.h}.

    + + +

    The system library {@code libOpenSLES.so} implements the public native audio functions. Link +against it by adding the following line to your +{@code Android.mk} file:

    + +
    +LOCAL_LDLIBS += -lOpenSLES
+
    + +

    For more information about the OpenSL ES API, refer to +{@code $NDK/docs/Additional_library_docs/opensles/index.html}, where {@code $NDK} is your NDK +installation root directory.

    + +

    Android native application APIs

    +

    Starting from API level 9, you can write an entire Android app with native code, without using +any Java.

    + +

    Note: Writing your app in native code is not, in itself, enough +for your app to run in the VM. Moreover, your app must still access most features of the Android +platform via JNI.

    + +

    This release provides the following native headers:

    +
      +
    • {@code <native_activity.h>}
      • +
    • {@code <looper.h>}
      • +
    • {@code <input.h>}
      • +
    • {@code <keycodes.h>}
      • +
    • {@code <sensor.h>}
      • +
    • {@code <rect.h>}
      • +
    • {@code <window.h>}
      • +
    • {@code <native_window.h>}
      • +
    • {@code <native_window_jni.h>}
      • +
    • {@code <configuration.h>}
      • +
    • {@code <asset_manager.h>}
      • +
    • {@code <storage_manager.h>}
      • +
    • {@code <obb.h>}
      • +
    + +

    For more information about these headers, see the +NDK API Reference documentation, as well as +the comments in the headers, themselves. Also, for more information about the larger topic of +writing native apps, see +Native Activities and Applications. + +

    When you include one or more of these headers, you must also link against the +{@code libandroid.so} library. To link against {@code libandroid.so}, include the following line in +your {@code Android.mk} file:

    + +
    +LOCAL_LDLIBS += -landroid
+
    + +

    Android API level 14

    +

    The NDK provides the following APIs for developing native code that runs on Android 4.0 system +images and above.

    + +

    OpenMAX AL

    +

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

    +

    The standard OpenMAX AL headers {@code <OMXAL/OpenMAXAL.h>} and +{@code <OMXAL/OpenMAXAL_Platform.h>} contain the declarations necessary for performing +multimedia output from the native side of Android.

    + +

    The NDK distribution of OpenMAX AL also provides Android-specific extensions. For information +about these extensions, see the comments in {@code OpenMAXAL_Android.h}.

    + +

    The system library {@code libOpenMAXAL.so} implements the public native multimedia functions. +To link against this library, include the following line in your + {@code Android.mk} file:

    + +
        LOCAL_LDLIBS += -lOpenMAXAL
+

    For more information about this topic, see {@code $NDK/docs/openmaxal/index.html}, +where {@code $NDK} is the root directory of your NDK installation.

    + +

    OpenSL ES

    +

    OpenSL ES support for this Android API level adds PCM support. For more information about +OpenSL ES support in the NDK, see OpenSL ES.

    + +

    Android API level 18

    +

    The NDK provides the following APIs for developing native code that runs on Android 4.3 system +images and above.

    + +

    OpenGL ES 3.0

    + +

    The standard OpenGL ES 3.0 headers {@code gl3.h} and {@code gl3ext.h} contain the declarations +needed for performing OpenGL ES 3.0 rendering calls from native code. These rendering calls provide +the ability to use the GLSL language to define and use vertex and fragment shaders. + +

    To use OpenGL ES 3.0, link your native module against {@code /system/lib/libGLESv3.so} by +including the following line in your +{@code Android.mk} file:

    + +
    +LOCAL_LDLIBS := -lGLESv3
+
    + +

    Not all devices support OpenGL ES 3.0. An app can query the OpenGL +ES version string and extension string to determine whether the current device +supports the features it needs. For information on how to perform this query, see the description of + +{@code glGetString()} in the OpenGL specification.

    + +

    Additionally, you must put a +{@code +<uses-feature>} tag in your manifest file to indicate which version of OpenGL ES your +application requires. For more information about the OpenGL ES settings for +{@code <uses-feature>}, see +OpenGL ES.

    + +

    The gles3jni sample application provides a basic example of how to use OpenGL ES 3.0 with the +NDK.

    + +

    Note: The Android emulator does not support OpenGL ES 3.0 hardware +emulation. Running and testing code that uses this API requires a real device with hardware that can +support OpenGL ES 3.0.

    + + +

    Android API level 21

    +

    The NDK provides the following APIs for developing native code that runs on Android 4.3 system +images and above.

    + +

    OpenGL ES 3.1

    + +

    The standard OpenGL ES 3.1 headers {@code gl31.h} and {@code gl3ext.h} contain the declarations +needed for performing OpenGL ES 3.1 rendering calls from native code. These rendering calls provide +the ability to use the GLSL language to define and use vertex and fragment shaders. + +

    To use OpenGL ES 3.1, link your native module against {@code /system/lib/libGLESv3.so} by +including the following line in your +{@code Android.mk} file:

    + +
    +LOCAL_LDLIBS := -lGLESv3
+
    + +

    Not all devices support OpenGL ES 3.1. An app can query the OpenGL +ES version string and extension string to determine whether the current device +supports the features it needs. For information on how to perform this query, see the description of + +{@code glGetString()} in the OpenGL specification.

    + +

    Additionally, you must put a +{@code +<uses-feature>} tag in your manifest file to indicate which version of OpenGL ES your +application requires. For more information about the OpenGL ES settings for +{@code <uses-feature>}, see +OpenGL ES.

    + +

    The gles3jni sample application provides a basic example of how to use OpenGL ES 3.1 with the +NDK.

    + +

    Note: The Android emulator does not support OpenGL ES 3.1 hardware +emulation. Running and testing code that uses this API requires a real device with hardware that can +support OpenGL ES 3.1.

    + diff --git a/docs/html-ndk/ndk/guides/standalone_toolchain.jd b/docs/html-ndk/ndk/guides/standalone_toolchain.jd new file mode 100644 index 000000000000..f3777f3fa17b --- /dev/null +++ b/docs/html-ndk/ndk/guides/standalone_toolchain.jd @@ -0,0 +1,575 @@ +page.title=Standalone Toolchain +@jd:body + + + +

    You can use the toolchains provided with the Android NDK independently, or as plug-ins +with an existing IDE, such as Eclipse. This flexibility +can be useful if you already have your own build system, and only need the ability to invoke the +cross-compiler in order to add support to Android for it.

    + +

    A typical use case is invoking the configure script of an open-source library that expects a +cross-compiler in the {@code CC} environment variable.

    + +

    Note: This page assumes significant understanding of +compiling, linking, and low-level architecture. In addition, the techniques it describes are +unnecessary for most use cases. In most cases, we recommend that you forego using a standalone +toolchain, and instead stick to the NDK build system.

    + +

    Selecting your Toolchain

    +

    Before anything else, you need to decide which processing architecture your standalone toolchain +is going to target. Each architecture corresponds to a different toolchain name, as Table 1 +shows.

    + +

    + Table 1. {@code APP_ABI} settings for different instruction sets.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ArchitectureToolchain name
    ARM-based{@code arm-linux-androideabi-<gcc-version>}
    x86-based{@code x86-<gcc-version>}
    MIPS-based{@code mipsel-linux-android-<gcc-version>}
    ARM64-based{@code aarch64-linux-android-<gcc-version>}
    X86-64-based{@code x86_64-<gcc-version>}
    MIPS64-based{@code mips64el-linux-android--<gcc-version>}
    + + + +

    Selecting your Sysroot

    +

    The next thing you need to do is define your sysroot (A sysroot is a directory containing +the system headers and libraries for your target). To define the sysroot, you must must know the +Android API level you want to target for native support; available native APIs vary by Android API +level.

    + +

    Native APIs for the respective +Android API levels reside under {@code $NDK/platforms/}; each API-level +directory, in turn, contains subdirectories for the various CPUs and architectures. The +following example shows how to define a sysroot for a build targeting Android 5.1 +(API level 22), for ARM architecture:

    + +
    +SYSROOT=$NDK/platforms/android-22/arch-arm
+
    + +For more detail about the Android API levels and the respective native APIs they support, see +Stable APIs. + +

    Invoking the Compiler

    + +

    There are two ways to invoke the compiler. One method is simple, and leaves most of the lifting +to the build system. The other is more advanced, but provides more flexibility.

    + +

    Simple method

    +

    The simplest way to build is by invoking the appropriate compiler directly from the command +line, using the {@code --sysroot} option to indicate the location of the system files for the +platform you're targeting. For example:

    + +
    +export CC="$NDK/toolchains/arm-linux-androideabi-4.8/prebuilt/ \
+linux-x86/bin/arm-linux-androideabi-gcc-4.8 --sysroot=$SYSROOT"
+$CC -o foo.o -c foo.c
+
    + +

    While this method is simple, it lacks in flexibility: It does not allow you to use any C++ STL +(STLport, libc++, or the GNU libstdc++) with it. It also does not support exceptions or RTTI.

    + +

    For Clang, you need to perform an additional two steps:

    +
      +
        +
      1. Add the appropriate {@code -target} for the target architecture, as Table 2 shows.
        2. + +

        + Table 2. Architectures and corresponding values for {@code -target}.

        + + + + + + + + + + + + + + + + + + + + + +
        ArchitectureValue
        armeabi-v7a{@code -target armv7-none-linux-androideabi}
        armeabi{@code -target armv5te-none-linux-androideabi}
        x86{@code -target i686-none-linux-android}
        MIPS{@code -target mipsel-none-linux-android}
        + +
      2. Add assembler and linker support by adding the {@code -gcc-toolchain} option, as in the +following example:
        3. +
        +-gcc-toolchain $NDK/toolchains/arm-linux-androideabi-4.8/prebuilt/linux-x86_64
+
        +
      + +Ultimately, a command to compile using Clang might look like this: + +
      +export CC="export CC="$NDK/toolchains/arm-linux-androideabi-4.8/prebuilt/ \
+linux-x86/bin/arm-linux-androideabi-gcc-4.8 --sysroot=$SYSROOT" -target \
+armv7-none-linux-androideabi \
+-gcc-toolchain $NDK/toolchains/arm-linux-androideabi-4.8/prebuilt/linux-x86_64"
+$CC -o foo.o -c foo.c
+
      +
    + +

    Advanced method

    +

    The NDK provides the {@code make-standalone-toolchain.sh} shell script to allow you to perform a +customized toolchain installation from the command line. This approach affords you more flexibility +than the procedure described in Simple method.

    + +

    The script is located in the {@code $NDK/build/tools/} directory, where {@code $NDK} is the +installation root for the NDK. An example of the use of this script appears below:

    + +
    +$NDK/build/tools/make-standalone-toolchain.sh \
+--arch=arm --platform=android-22 --install-dir=/tmp/my-android-toolchain
+
    + +

    This command creates a directory named {@code /tmp/my-android-toolchain/}, containing a copy of +the {@code android-22/arch-arm} sysroot, and of the toolchain binaries for a 32-bit ARM +architecture.

    + +

    Note that the toolchain binaries do not depend on or contain host-specific paths, in other words, +you can install them in any location, or even move them if you need to.

    + +

    By default, the build system uses the 32-bit, ARM-based GCC 4.8 toolchain. You can specify a +different value, however, by specifying {@code --arch=<toolchain>} as an option. +Table 3 shows the values to use for other toolchains: + +

    + Table 3. Toolchains and corresponding values, using {@code --arch}.

    + + + + + + + + + + + + + + + + + +
    ToolchainValue
    x86 GCC 4.8 compiler{@code --arch=x86}
    x86_64 GCC 4.8 compiler{@code --arch=x86_64}
    MIPS GCC 4.8 compiler{@code --arch=mips}
    + +

    Alternatively, you can use the {@code --toolchain=<toolchain>} option. Table 4 shows the +values you can specify for {@code <toolchain>}:

    + +

    + Table 4. Toolchains and corresponding values, using {@code --toolchain}.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ToolchainValue
    arm +
  • {@code --toolchain=arm-linux-android-4.6}
    • +
  • {@code --toolchain=arm-linux-android-4.7}
    • +
  • {@code --toolchain=arm-linux-android-4.8}
    • +
  • {@code --toolchain=arm-linux-android-4.9}
    • +
  • {@code --toolchain=arm-linux-android-clang3.4}
    • +
  • {@code --toolchain=arm-linux-android-clang3.5}
    • +
    x86 +
  • {@code --toolchain=x86-linux-android-4.6}
    • +
  • {@code --toolchain=x86-linux-android-4.7}
    • +
  • {@code --toolchain=x86-linux-android-4.8}
    • +
  • {@code --toolchain=x86-linux-android-4.9}
    • +
  • {@code --toolchain=x86-linux-android-clang3.4}
    • +
  • {@code --toolchain=x86-linux-android-clang3.5}
    • +
    mips +
  • {@code --toolchain=mips-linux-android-4.6}
    • +
  • {@code --toolchain=mips-linux-android-4.7}
    • +
  • {@code --toolchain=mips-linux-android-4.8}
    • +
  • {@code --toolchain=mips-linux-android-4.9}
    • +
  • {@code --toolchain=mips-linux-android-clang3.4}
    • +
  • {@code --toolchain=mips-linux-android-clang3.5}
    • +
    arm64 +
  • {@code --toolchain=aarch64-linux-android-4.9}
    • +
  • {@code --toolchain=aarch64-linux-android-clang3.4}
    • +
  • {@code --toolchain=aarch64-linux-android-clang3.5}
    • +
    x86_64 +
  • {@code --toolchain=x86_64-linux-android-4.9}
    • +
  • {@code --toolchain=x86_64-linux-android-clang3.4}
    • +
  • {@code --toolchain=x86_64-linux-android-clang3.5}
    • +
    mips64 +
  • {@code --toolchain=mips64el-linux-android-4.9}
    • +
  • {@code --toolchain=mips64el-linux-android-clang3.4}
    • +
  • {@code --toolchain=mips64el-linux-android-clang3.5}
    • +
    + +

    Note: Table 4 is not an exhaustive list. Other combinations may +also be valid, but are unverified.

    + +

    You can also copy Clang/LLVM 3.3, using one of two methods: You can append {@code -clang3.3} to +the {@code --toolchain} option, so that the {@code --toolchain} option looks like the following +example: + +

    +--toolchain=arm-linux-androideabi-clang3.3
+
    + +

    Alternatively, you can add {@code -llvm-version=3.3} as a separate option on the command +line.

    + +

    By default, the build system builds for a 32-bit host toolchain. You can specify a 64-bit +host toolchain instead. Table 5 shows the value to use with {@code -system} for different +platforms.

    + +

    + Table 5. Host toolchains and corresponding values, using {@code -system}.

    + + + + + + + + + + + + + +
    Host toolchainValue
    64-bit Linux{@code -system=linux-x86_64}
    64-bit MacOSX{@code -system=darwin-x86_64}
    + +For more information on specifying a 32- or 64-bit instruction host toolchain, see +ndk-build. + +

    You may specify {@code stl=stlport} to copy {@code libstlport} instead of the default +{@code libgnustl}. If you do so, and you wish to link against the shared library, you must +explicitly use {@code -lstlport_shared}. This requirement is similar to having to use +{@code -lgnustl_shared} for GNU {@code libstdc++}.

    + +

    Similarly, you can specify {@code -stl=libc++} to copy the LLVM libc++ headers and libraries. +To link against the shared library, you must explicitly use -lc++_shared.

    + +

    You can make these settings directly, as in the following example:

    + +
    +export PATH=/tmp/my-android-toolchain/bin:$PATH
+export CC=arm-linux-androideabi-gcc   # or export CC=clang
+export CXX=arm-linux-androideabi-g++  # or export CXX=clang++
+
    + +

    Note that if you omit the {@code -install-dir} option, the {@code make-standalone-toolchain.sh} +shell script creates a tarball in {@code tmp/ndk/<toolchain-name>.tar.bz2}. This tarball makes +it easy to archive, as well as to redistribute the binaries.

    + +

    This standalone toolchain provides an additional benefit, as well, in that it contains a working +copy of a C++ STL library, with working exceptions and RTTI support.

    + +

    For more options and details, use {@code --help}.

    + +

    Working with Clang

    +

    You can install Clang binaries in the standalone installation by using the +{@code --llvm-version=<version>} option. {@code <version>} is a LLVM/Clang version +number, such as {@code 3.4} or {@code 3.5}. For example: + +

    +build/tools/make-standalone-toolchain.sh \
+--install-dir=/tmp/mydir \
+--toolchain=arm-linux-androideabi-4.7 \
+--llvm-version=3.5
+
    + +

    Note that Clang binaries are copied along with the GCC ones, because they rely on the same +assembler, linker, headers, libraries, and C++ STL implementation.

    + +

    This operation also installs two scripts, named {@code clang} and {@code clang++}, under +{@code <install-dir>/bin/@}. These scripts invoke the real {@code clang} binary with default +target architecture flags. In other words, they should work without any modification, and you should +be able to use them in your own builds by just setting the {@code CC} and {@code CXX} environment +variables to point to them.

    + +

    Invoking Clang

    +

    In an ARM standalone installation built with {@code llvm-version=3.3}, invoking +Clang on a Unix system takes the form of a single line. For +instance:

    + +
    +dirname $0 /clang31 -target armv5te-none-linux-androideabi "$@"
+
    + +

    clang++ invokes clang++31 in the same way.

    + +

    Clang targets with ARM

    + +

    When building for ARM, Clang changes the target based on the presence of the +{@code -march=armv7-a} and/or {@code -mthumb} options:

    + +

    + Table 5. Specifiable {@code -march} values and their resulting targets.

    + + + + + + + + + + + + + + + + + +
    {@code -march} valueResulting target
    {@code -march=armv7-a}{@code armv7-none-linux-androideabi}
    {@code -mthumb}{@code thumb-none-linux-androideabi}
    Both {@code -march=armv7-a} and {@code -mthumb}{@code thumbv7-none-linux-androideabi}
    + +

    You may also override with your own {@code -target} if you wish.

    + +

    The {@code -gcc-toolchain} option is unnecessary because, in a standalone package, +Clang locates {@code as} and {@code ld} in a predefined relative location.

    + +

    {@code clang} and {@code clang++} should be easy drop-in replacements for {@code gcc} and +{@code g++} in a makefile. When in doubt, add the following options to verify that they are +working properly:

    + +
      +
    • {@code -v} to dump commands associated with compiler driver issues
      • +
    • {@code -###} to dump command line options, including implicitly predefined ones.
      • +
    • {@code -x c /dev/null -dM -E} to dump predefined preprocessor definitions
      • +
    • {@code -save-temps} to compare {@code *.i} or {@code *.ii} preprocessed files.
      • +
    + +

    For more information about Clang, see +http://clang.llvm.org/, especially the GCC compatibility +section.

    + + +

    ABI Compatibility

    +

    The machine code that the ARM toolchain generates should be compatible with the official Android +armeabi ABI by default.

    + +

    We recommend use of the {@code -mthumb} compiler flag to force the generation of 16-bit Thumb-1 +instructions (the default being 32-bit ARM instructions).

    + +

    If you want to target the armeabi-v7a ABI, you must set the following flags:

    + +
    +CFLAGS= -march=armv7-a -mfloat-abi=softfp -mfpu=vfpv3-d16
+
    + +

    The first flag enables Thumb-2 instructions. The second flag enables hardware-FPU instructions +while ensuring that the system passes floating-point parameters in core registers, which is critical +for ABI compatibility.

    + +

    Note: In versions of the NDK prior to r9b, do not use these flags +separately. You must set all or none of them. Otherwise, unpredictable behavior and crashes may +result.

    + +

    To use NEON instructions, you must change the {@code -mfpu} compiler flag:

    + +
    +CFLAGS= -march=armv7-a -mfloat-abi=softfp -mfpu=neon
+
    + +

    Note that this setting forces the use of {@code VFPv3-D32}, per the ARM specification.

    + +

    Also, make sure to provide the following two flags to the linker:

    + +
    +LDFLAGS= -march=armv7-a -Wl,--fix-cortex-a8
+
    + +

    The first flag instructs the linker to pick {@code libgcc.a}, {@code libgcov.a}, and +{@code crt*.o}, which are tailored for armv7-a. The 2nd flag is required as a workaround for a CPU +bug in some Cortex-A8 implementations.

    + +

    Since NDK version r9b, all Android native APIs taking or returning double or float values have +{@code attribute((pcs("aapcs")))} for ARM. This makes it possible to compile user code in +{@code -mhard-float} (which implies {@code -mfloat-abi=hard}), and still link with the Android +native APIs that comply with the softfp ABI. For more information on this, see the comments in +{@code $NDK/tests/device/hard-float/jni/Android.mk}.

    + +

    If you want to use NEON intrinsics on x86, the build system can translate them to the native x86 +SSE intrinsics using a special C/C++ language header with the same name, {@code arm_neon.h}, as the +standard ARM NEON intrinsics header.

    + +

    By default, the x86 ABI supports SIMD up to SSSE3, and the header covers ~93% of (1869 of 2009) +NEON functions.

    + +

    You don't have to use any specific compiler flag when targeting the MIPS ABI.

    + +

    To learn more about ABI support, see x86.

    + +

    Warnings and Limitations

    +

    Windows support

    +

    The Windows binaries do not depend on Cygwin. This lack of dependency makes them faster. The +cost, however, is that they do not understand Cygwin path specifications like +{@code cygdrive/c/foo/bar}, as opposed to {@code C:/foo/bar}.

    + +

    The NDK build system ensures that all paths passed to the compiler from Cygwin are automatically +translated, and manages other complexities, as well. If you have a custom build system, +you may need to resolve these complexities yourself.

    + +

    For information on contributing to support for Cygwin/MSys, visit the android-ndk +forum.

    + +

    wchar_t support

    + +

    The Android platform did not really support {@code wchar_t} until Android 2.3 (API level 9). This +fact has several ramifications:

    +
      +
    • If you target platform Android 2.3 or higher, the size of {@code wchar_t} is 4 bytes, and most +{@code wide-char} functions are available in the C library (with the exception of multi-byte +encoding/decoding functions and {@code wsprintf}/{@code wsscanf}).
      • + +
    • If you target any lower API level, the size of {@code wchar_t} is 1 byte, and none of the +wide-char functions works.
      • +
    + +

    We recommend that you get rid of any dependencies on the {@code wchar_t} type, and switch to +better representations. The support provided in Android is only there to help you migrate existing +code.

    + +

    Exceptions, RTTI, and STL

    +

    The toolchain binaries support C++ exceptions and RTTI by default. To disable C++ exceptions +and RTTI when building sources (to generate lighter-weight machine code, for example), use +{@code -fno-exceptions} and {@code -fno-rtti}.

    + +

    To use these features in conjunction with GNU libstdc++, you must explicitly link with libsupc++. +To do so, use {@code -lsupc++} when linking binaries. For example:

    + +
    +arm-linux-androideabi-g++ .... -lsupc++
+
    + +

    You do not need to do this when using the STLport or libc++ library.

    + +

    C++ STL support

    +

    The standalone toolchain includes a copy of a C++ Standard Template Library implementation. This +implementation is either for GNU libstdc++, STLport, or libc++, depending on what you specify for the +{@code -stl=<name>} option described previously. To use this implementation of STL, you need +to link your project with the proper library:

    + +
      +
    • +Use {@code -lstdc++} to link against the static library version of any implementation. Doing so +ensures that all required C++ STL code is included into your final binary. This method is ideal if +you are only generating a single shared library or executable.

      + +

      This is the method that we recommend.

      +
      • + +
    • Alternatively, use {@code -lgnustl_shared} to link against the shared library version of GNU +{@code libstdc++}. If you use this option, you must also make sure to copy +{@code libgnustl_shared.so} to your device in order for your code to load properly. Table 6 shows +where this file is for each toolchain type. +
      • + +

      Note: GNU libstdc++ is licensed under the GPLv3 license, with a +linking exception. If you cannot comply with its requirements, you cannot redistribute the +shared library in your project.

      + + +
    • Use {@code -lstlport_shared} to link against the shared library version of STLport. When you do +so, you need to make sure that you also copy {@code libstlport_shared.so} to your device in order +for your code to load properly. Table 6 shows where this file is for each toolchain:
      • + +

      + Table 6. Specifiable {@code -march} values and their resulting targets.

      + + + + + + + + + + + + + + + + + +
      ToolchainLocation
      ARM{@code $TOOLCHAIN/arm-linux-androideabi/lib/}
      x86{@code $TOOLCHAIN/i686-linux-android/lib/}
      MIPS{@code $TOOLCHAIN/mipsel-linux-android/lib/}
      + +

      Note: If your project contains multiple shared libraries or +executables, you must link against a shared-library STL implementation. Otherwise, the build +system does not define certain global uniquely, which can result in unpredictable runtime behavior. +This behavior may include crashes and failure to properly catch exceptions.

      + +

      The reason the shared version of the libraries is not simply called {@code libstdc++.so} is that +this name would conflict at runtime with the system's own minimal C++ runtime. For this reason, +the build system enforces a new name for the GNU ELF library. The static library does not have +this problem.

      diff --git a/docs/html-ndk/ndk/guides/x86-64.jd b/docs/html-ndk/ndk/guides/x86-64.jd new file mode 100644 index 000000000000..22f3aaa15a78 --- /dev/null +++ b/docs/html-ndk/ndk/guides/x86-64.jd @@ -0,0 +1,52 @@ +page.title=Support for 64-bit x86 +@jd:body + +
      +
      +

      On this page

      + +
        +
      1. Overview
        2. +
      2. Standalone Toolchain
        3. +
      3. Compatibilty
        4. +
      + + +
      +
      + +

      The Android NDK supports the {@code x86_64} ABI. This ABI allows native code to run on +Android-based devices using CPUs that support the 64-bit x86 instruction set.

      + +

      Overview

      +

      To generate 64-bit machine code for x86, add {@code x86_64} to the {@code APP_ABI} definition in +your {@code Application.mk} file. For example: + +

      +APP_ABI := x86_64
+
      + +For more information on how to specify values for {@code APP_ABI}, see +Application.mk.

      + +

      The build system places libraries generated for the {@code x86_64} ABI into +{@code $PROJECT/libs/x86_64/} on your host machine, where {@code $PROJECT} is the root directory +of your project. It also embeds them in your APK, under {@code /lib/x86_64/}.

      + +

      The Android package manager extracts these libraries when installing your APK on a compatible +64-bit, x86-powered device, placing them under your app's private data directory.

      + +

      In the Google Play store, the server filters applications so that a consumer sees only the native +libraries that run on the CPU powering his or her device.

      + +

      Standalone Toolchain

      + +

      It is possible to use the 64-bit x86 toolchain in standalone mode with the NDK. For more +information about doing so, see +Standalone Toolchain, under the "Advanced method" section. + +

      Compatibility

      +

      The NDK provides native versions of Android APIs for 64-bit x86 machine code starting from +Android 5.0 (Android API level 21). If your project files target an older API level, but include +{@code x86_64} as a targeted platform, the NDK build script automatically selects the right set of +native platform headers and libraries for you.

      \ No newline at end of file diff --git a/docs/html-ndk/ndk/guides/x86.jd b/docs/html-ndk/ndk/guides/x86.jd new file mode 100644 index 000000000000..e112a56fd166 --- /dev/null +++ b/docs/html-ndk/ndk/guides/x86.jd @@ -0,0 +1,215 @@ +page.title=x86 Support +@jd:body + + + +

      The NDK includes support for the {@code x86} ABI, which allows native code to run on +Android-based devices running on CPUs supporting the IA-32 instruction set.

      + +

      Overview

      +

      To generate x86 machine code, add {@code x86} to the {@code APP_ABI} definition in your +{@code Application.mk} file. For example:

      + +
      +APP_ABI := armeabi armeabi-v7a x86
+
      For more information about defining the {@code APP_ABI} variable, see +{@code Application.mk}.

      + +

      The build system places generated libraries into {@code $PROJECT/libs/x86/}, where +{@code $PROJECT} represents your project's root directory, and embeds them in your APK under +{@code /lib/mips/}.

      + +

      The Android package extracts these libraries when installing your APK on a compatible x86-based +device, placing them under your app's private data directory.

      + +

      In the Google Play store, the server filters applications so that a consumer sees only the native +libraries that run on the CPU powering his or her device.

      + +

      x86 Support for ARM NEON Intrinsics

      +

      Support for ARM NEON intrinsics is provided in the form of C/C++ language headers with the same +name as the standard ARM NEON intrinsics header, {@code arm_neon.h}. These headers are available for +all NDK x86 toolchains. They translate NEON intrinsics to native x86 SSE ones.

      + +

      Characteristics of this solution include the following:

      +
        +
      • Default use of SSE through SSSE3 for porting ARM NEON to Intel SSE, covering ~93% +(1869 of total 2009) of all NEON functions.
        • +
      • Redefinition of ARM NEON 128 bit vectors into the equivalent x86 SIMD data.
        • +
      • Redefinition of some functions from ARM NEON to Intel SSE if a 1:1 correspondence exists.
        • +
      • Implementation of some ARM NEON functions using Intel SIMD if it will yield a performant result. +
        • +
      • Implementation of some of the remaining NEON functions using the serial solution, and issuing +the corresponding "low performance" compiler warning.
        • +
      + + +

      Performance

      +

      In most cases, you should be able to attain performance similar to what you would get from ARM +NEON code. Recommendations for best results include:

      + +
        +
      • Use 16-byte data alignment for faster load and store.
        • +
      • Avoid using constants with NEON functions. Using constants results in a performance penalty due +to having to load constants. If you must use constants, try to initialize them outside of hotspot +loops. If possible, replace them with logical and compare operations.
        • +
      • Try to avoid functions marked as "serially implemented" because they need to store data from +registers to memory. Instead, process them serially and reload them. You may be able to change the +data type or algorithm used to vectorize the whole port instead of leaving it as a serial one.
        • +
      + +

      For more information on this topic, see + +From ARM NEON to Intel SSE– the automatic porting solution, tips and tricks.

      + +

      Known differences from ARM version

      +

      In the great majority of cases, x86 implementations produce the same results as ARM +implementations for NEON. x86 implementations pass +NEON tests nearly 100% of the +time. Still, there are several corner cases in which an x86 implementation produces results +different from its ARM counterpart. Known incompatibilities are as follows:

      + + + +

      Sample code

      +

      In your project make sure to include the {@code arm_neon.h} header, and define include +{@code x86} in your definition of {@code APP_ABI}. The build system then ports your code to x86.

      + +

      For an example of how porting ARM NEON to x86 SSE works, see the hello-neon sample.

      + +

      Standalone Toolchain

      +

      You can incorporate the {@code x86} ABI into your own toolchain. For more information, see +Standalone Toolchain.

      + +

      Compatibility

      +

      x86 support requires, at minimum, Android 2.3 (Android API level 9). If your project files +target an older API level, but include x86 as a targeted platform, the NDK build script +automatically selects the right set of native platform headers/libraries for you.

      \ No newline at end of file -- cgit v1.2.3-59-g8ed1b