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/&lt;abi&gt;.
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 &lt;foo.h&gt;
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/&lt;abi&gt;/ 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     =&gt; when targeting ARMv5TE or higher CPUs
115   armeabi-v7a =&gt; when targeting ARMv7 or higher CPUs
116   x86         =&gt; when targeting x86 CPUs
117   mips        =&gt; 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            --&gt; the file above
134    armeabi/libfoo.so     --&gt; the armeabi prebuilt shared library
135    armeabi-v7a/libfoo.so --&gt; the armeabi-v7a prebuilt shared library
136    include/foo.h         --&gt; 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