1page.title=Using Prebuilt Libraries
2@jd:body
3
4<div id="qv-wrapper">
5    <div id="qv">
6      <h2>On this page</h2>
7
8      <ol>
9        <li><a href="#dm">Declaring a Prebuilt Library</a></li>
10        <li><a href="#rp">Referencing the Prebuilt Library from Other Modules</a></li>
11        <li><a href="#dp">Debugging Prebuilt Libraries</a></li>
12        <li><a href="#sa">Selecting ABIs for Prebuilt Libraries</a></li>
13      </ol>
14    </div>
15  </div>
16
17<p>The NDK supports the use of prebuilt libraries, both static and shared. There are two principal
18use cases for this functionality:</p>
19
20<ul>
21   <li>Distributing your own libraries to third-party NDK developers without distributing your
22    sources.</li>
23   <li>Using a prebuilt version of your own libraries to speed up your build.</li>
24</ul>
25
26<p>This page explains how to use prebuilt libraries.</p>
27
28<h2 id="dm">Declaring a Prebuilt Library</h2>
29<p>You must declare each prebuilt library you use as a <em>single</em> independent module. To do
30  so, perform the following steps:
31
32<ol type="1">
33   <li>Give the module a name. This name does not need to be the same as that of the prebuilt
34    library, itself.</li>
35   <li>In the module's <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a>
36   file, assign to {@code LOCAL_SRC_FILES} the path to the prebuilt library you are providing.
37   Specify the path relative to the value of your {@code LOCAL_PATH} variable.</p>
38   <p class="note"><strong>Note: </strong> You must make sure to select the version of your prebuilt
39    library appropriate to your target ABI. For more information on ensuring library support for
40    ABIs, see <a href="#sa">Selecting ABIs for Prebuilt Libraries.</a></p></li>
41   <li>Include {@code PREBUILT_SHARED_LIBRARY} or {@code PREBUILT_STATIC_LIBRARY}, depending on
42    whether you are using a shared ({@code .so}) or static ({@code .a}) library.</li>
43</ol>
44
45  <p>Here is a trivial example that assumes the prebuilt library {@code libfoo.so} resides in
46  the same directory as the <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a>
47  file that describes it.</p>
48
49<pre>
50LOCAL_PATH := $(call my-dir)
51
52include $(CLEAR_VARS)
53LOCAL_MODULE := foo-prebuilt
54LOCAL_SRC_FILES := libfoo.so
55include $(PREBUILT_SHARED_LIBRARY)
56</pre>
57
58<p>In this example, the name of the module is the same as that of the prebuilt library.</p>
59
60<p>The build system places a copy of your prebuilt shared library into {@code $PROJECT/obj/local},
61and another copy, stripped of debug information, into {@code $PROJECT/libs/<abi>}. Here,
62{@code $PROJECT} is the root directory of your project.</p>
63
64<h2 id="rp">Referencing the Prebuilt Library from Other Modules</h2>
65<p>To reference a prebuilt library from other modules, specify its name as the value
66of the {@code LOCAL_STATIC_LIBRARIES} or {@code LOCAL_SHARED_LIBRARIES} variable in the
67<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> files associated with those
68other modules.</p>
69
70<p>For example, the description of a module using {@code libfoo.so} might be as follows:</p>
71
72<pre>
73include $(CLEAR_VARS)
74LOCAL_MODULE := foo-user
75LOCAL_SRC_FILES := foo-user.c
76LOCAL_SHARED_LIBRARIES := foo-prebuilt
77include $(BUILD_SHARED_LIBRARY)
78</pre>
79
80<p>Here, {@code LOCAL_MODULE} is the name of the module referring to the prebuilt; {@code
81  LOCAL_SHARED_LIBRARIES} is the name of the prebuilt, itself.</p>
82
83<h2>Exporting Headers for Prebuilt Libraries</h2>
84<p>The code in {@code foo-user.c} depends on specific declarations that normally
85reside in a header file, such as {@code foo.h}, distributed with the prebuilt library.
86For example, {@code foo-user.c} might have a line like the following:</p>
87
88<pre>
89#include &lt;foo.h&gt;
90</pre>
91
92<p>In such a case, you need to provide the header and its include path to the compiler when you
93build the {@code foo-user} module. A simple way to accomplish this task is to use exports in the
94prebuilt module definition. For example, as long as header {@code foo.h} is located under the
95{@code include} directory associated with the prebuilt module, you can declare it as follows:</p>
96
97<pre>
98include $(CLEAR_VARS)
99LOCAL_MODULE := foo-prebuilt
100LOCAL_SRC_FILES := libfoo.so
101LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include
102include $(PREBUILT_SHARED_LIBRARY)
103</pre>
104
105<p>The {@code LOCAL_EXPORT_C_INCLUDES} definition here ensures that the build system
106exports the path to the prebuilt library's {@code include} directory, prepending that path onto the
107value of the {@code LOCAL_C_INCLUDES} for the module dependent on it.</p>
108
109<p>This operation allows the build system to find the necessary headers.</p>
110
111<h2 id="dp">Debugging Prebuilt Libraries</h2>
112<p>We recommend that you provide prebuilt shared libraries containing debug symbols. The NDK build
113system always strips the symbols from the version of the library that it installs into
114{@code $PROJECT/libs/<abi>/}, but you can use the debug version for debugging with
115{@code ndk-gdb}.</p>
116
117<h2 id="sa">Selecting ABIs for Prebuilt Libraries</h2>
118<p>You must make sure to select the right version of your prebuilt shared library for your targeted
119ABI. The <a href="{@docRoot}ndk/guides/android_mk.html#taa">
120{@code TARGET_ARCH_ABI}</a> variable in the <a href="{@docRoot}ndk/guides/android_mk.html">
121{@code Android.mk}</a> file can point the build system at the appropriate version of the library.
122</p>
123
124<p>For example, assume that your project contains two versions of library {@code libfoo.so}:</p>
125
126<pre class="no-pretty-print">
127armeabi/libfoo.so
128x86/libfoo.so
129</pre>
130
131<p>The following snippet shows how to use {@code TARGET_ARCH_ABI} so that the build system selects
132  the appropriate version of the library:</p>
133
134<pre>
135include $(CLEAR_VARS)
136LOCAL_MODULE := foo-prebuilt
137LOCAL_SRC_FILES := $(TARGET_ARCH_ABI)/libfoo.so
138LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include
139include $(PREBUILT_SHARED_LIBRARY)
140</pre>
141
142<p>If you have specified {@code armeabi} as the value of {@code TARGET_ARCH_ABI}, the build system
143uses the version of {@code libfoo.so} located in the {@code armeabi} directory. If you have
144specified {@code x86} as the value {@code TARGET_ARCH_ABI}, the build system uses the version in the
145{@code x86} directory.</p>
146