1 NDK Prebuilt library support: 2 === 3 4 Android NDK r5 introduced support for prebuilt libraries (shared and 5 static), i.e. the ability to include and use, in your applications, 6 prebuilt version of libraries. 7 8 This feature can be useful for two things: 9 10 1. You want to distribute your own libraries to third-party NDK developers 11 without distributing your sources. 12 13 2. You want to use a prebuilt version of your own libraries to speed up 14 your build. 15 16 This document explains how this support works. 17 18 19 I. Declaring a prebuilt library module: 20 --------------------------------------- 21 22 Each prebuilt library must be declared as a *single* independent module to 23 the 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 33 Notice that, to declare such a module, you really only need the following: 34 35 1. Give the module a name (here '`foo-prebuilt`'). This does not need to 36 correspond to the name of the prebuilt library itself. 37 38 2. 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 44 3. 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 48 A prebuilt module does not build anything. However, a copy of your prebuilt 49 shared library will be copied into $PROJECT/obj/local, and another will be 50 copied and stripped into `$PROJECT/libs/<abi>`. 51 52 II. Referencing the prebuilt library in other modules: 53 ------------------------------------------------------ 54 55 Simply list your prebuilt module's name in the LOCAL_STATIC_LIBRARIES or 56 LOCAL_SHARED_LIBRARIES declaration in the Android.mk of any module that 57 depends on them. 58 59 For 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 68 III. Exporting headers for prebuilt libraries: 69 ---------------------------------------------- 70 71 The example above was called 'naive' because, in practice, the code in 72 foo-user.c is going to depend on specific declarations that are normally 73 found in a header file distributed with the prebuilt library (e.g. "foo.h"). 74 75 In other words, foo-user.c is going to have a line like: 76 77 #include <foo.h> 78 79 And you need to provide the header and its include path to the compiler 80 when building the foo-user module. 81 82 A simple way to deal with that is to use exports in the prebuilt module 83 definition. For example, assuming that a file "foo.h" is located under 84 the '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 92 The LOCAL_EXPORT_C_INCLUDES definition here ensures that any module that 93 depends on the prebuilt one will have its LOCAL_C_INCLUDES automatically 94 prepended with the path to the prebuilt's include directory, and will thus 95 be able to find headers inside that. 96 97 98 IV. Debugging prebuilt binaries: 99 -------------------------------- 100 101 We recommend you to provide prebuilt shared libraries that contain debug 102 symbols. The version that is installed into `$PROJECT/libs/<abi>/` is always 103 stripped by the NDK build system, but the debug version will be used for 104 debugging purposes with ndk-gdb. 105 106 107 V. ABI Selection of prebuilt binaries: 108 -------------------------------------- 109 110 As said previously, it is crucial to provide a prebuilt shared library 111 that is compatible with the targeted ABI during the build. To do that, 112 check 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 119 Note that armeabi-v7a systems can run armeabi binaries just fine. 120 121 Here's an example where we provide two versions of a prebuilt library 122 and 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 130 Here. we assume that the prebuilt libraries to copy are under the 131 following 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 138 NOTE: 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 142
