1<html><body><pre>NDK Prebuilt library support: 2----------------------------- 3 4Android NDK r5 introduced support for prebuilt libraries (shared and 5static), i.e. the ability to include and use, in your applications, 6prebuilt version of libraries. 7 8This feature can be useful for two things: 9 101/ You want to distribute your own libraries to third-party NDK developers 11 without distributing your sources. 12 132/ You want to use a prebuilt version of your own libraries to speed up 14 your build. 15 16This document explains how this support works. 17 18 19I. Declaring a prebuilt library module: 20--------------------------------------- 21 22Each prebuilt library must be declared as a *single* independent module to 23the build system. Here is a trivial example where we assume that the file 24"libfoo.so" is located in the same directory than the Android.mk below: 25 26 LOCAL_PATH := $(call my-dir) 27 28 include $(CLEAR_VARS) 29 LOCAL_MODULE := foo-prebuilt 30 LOCAL_SRC_FILES := libfoo.so 31 include $(PREBUILT_SHARED_LIBRARY) 32 33Notice that, to declare such a module, you really only need the following: 34 351. Give the module a name (here 'foo-prebuilt'). This does not need to 36 correspond to the name of the prebuilt library itself. 37 382. Assign to LOCAL_SRC_FILES the path to the prebuilt library you are 39 providing. As usual, the path is relative to your LOCAL_PATH. 40 41 IMPORTANT: You *must* ensure that the prebuilt library corresponds 42 to the target ABI you are using. More on this later. 43 443. Include PREBUILT_SHARED_LIBRARY, instead of BUILD_SHARED_LIBRARY, if 45 you are providing a shared, library. For static ones, use 46 PREBUILT_STATIC_LIBRARY. 47 48A prebuilt module does not build anything. However, a copy of your prebuilt 49shared library will be copied into $PROJECT/obj/local, and another will be 50copied and stripped into $PROJECT/libs/<abi>. 51 52II. Referencing the prebuilt library in other modules: 53------------------------------------------------------ 54 55Simply list your prebuilt module's name in the LOCAL_STATIC_LIBRARIES or 56LOCAL_SHARED_LIBRARIES declaration in the Android.mk of any module that 57depends on them. 58 59For example, a naive example of a module using libfoo.so would be: 60 61 include $(CLEAR_VARS) 62 LOCAL_MODULE := foo-user 63 LOCAL_SRC_FILES := foo-user.c 64 LOCAL_SHARED_LIBRARIES := foo-prebuilt 65 include $(BUILD_SHARED_LIBRARY) 66 67 68III. Exporting headers for prebuilt libraries: 69---------------------------------------------- 70 71The example above was called 'naive' because, in practice, the code in 72foo-user.c is going to depend on specific declarations that are normally 73found in a header file distributed with the prebuilt library (e.g. "foo.h"). 74 75In other words, foo-user.c is going to have a line like: 76 77 #include <foo.h> 78 79And you need to provide the header and its include path to the compiler 80when building the foo-user module. 81 82A simple way to deal with that is to use exports in the prebuilt module 83definition. For example, assuming that a file "foo.h" is located under 84the 'include' directory relative to the prebuilt module, we can write: 85 86 include $(CLEAR_VARS) 87 LOCAL_MODULE := foo-prebuilt 88 LOCAL_SRC_FILES := libfoo.so 89 LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include 90 include $(PREBUILT_SHARED_LIBRARY) 91 92The LOCAL_EXPORT_C_INCLUDES definition here ensures that any module that 93depends on the prebuilt one will have its LOCAL_C_INCLUDES automatically 94prepended with the path to the prebuilt's include directory, and will thus 95be able to find headers inside that. 96 97 98IV. Debugging prebuilt binaries: 99-------------------------------- 100 101We recommend you to provide prebuilt shared libraries that contain debug 102symbols. The version that is installed into $PROJECT/libs/<abi>/ is always 103stripped by the NDK build system, but the debug version will be used for 104debugging purposes with ndk-gdb. 105 106 107V. ABI Selection of prebuilt binaries: 108-------------------------------------- 109 110As said previously, it is crucial to provide a prebuilt shared library 111that is compatible with the targeted ABI during the build. To do that, 112check for the value of TARGET_ARCH_ABI, its value will be: 113 114 armeabi => when targeting ARMv5TE or higher CPUs 115 armeabi-v7a => when targeting ARMv7 or higher CPUs 116 x86 => when targeting x86 CPUs 117 mips => when targeting MIPS CPUs 118 119Note that armeabi-v7a systems can run armeabi binaries just fine. 120 121Here's an example where we provide two versions of a prebuilt library 122and select which one to copy based on the target ABI: 123 124 include $(CLEAR_VARS) 125 LOCAL_MODULE := foo-prebuilt 126 LOCAL_SRC_FILES := $(TARGET_ARCH_ABI)/libfoo.so 127 LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include 128 include $(PREBUILT_SHARED_LIBRARY) 129 130Here. we assume that the prebuilt libraries to copy are under the 131following directory hierarchy: 132 133 Android.mk --> the file above 134 armeabi/libfoo.so --> the armeabi prebuilt shared library 135 armeabi-v7a/libfoo.so --> the armeabi-v7a prebuilt shared library 136 include/foo.h --> the exported header file 137 138NOTE: Remember that you don't need to provide an armeabi-v7a prebuilt 139 library, since an armeabi one can easily run on the corresponding 140 devices. 141</pre></body></html> 142