1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
page.title=Using Prebuilt Libraries
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>On this page</h2>
<ol>
<li><a href="#dm">Declaring a Prebuilt Library</a></li>
<li><a href="#rp">Referencing the Prebuilt Library from Other Modules</a></li>
<li><a href="#dp">Debugging Prebuilt Libraries</a></li>
<li><a href="#sa">Selecting ABIs for Prebuilt Libraries</a></li>
</ol>
</div>
</div>
<p>The NDK supports the use of prebuilt libraries, both static and shared. There are two principal
use cases for this functionality:</p>
<ul>
<li>Distributing your own libraries to third-party NDK developers without distributing your
sources.</li>
<li>Using a prebuilt version of your own libraries to speed up your build.</li>
</ul>
<p>This page explains how to use prebuilt libraries.</p>
<h2 id="dm">Declaring a Prebuilt Library</h2>
<p>You must declare each prebuilt library you use as a <em>single</em> independent module. To do
so, perform the following steps:
<ol type="1">
<li>Give the module a name. This name does not need to be the same as that of the prebuilt
library, itself.</li>
<li>In the module's <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a>
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.</p>
<p class="note"><strong>Note: </strong> 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 <a href="#sa">Selecting ABIs for Prebuilt Libraries.</a></p></li>
<li>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.</li>
</ol>
<p>Here is a trivial example that assumes the prebuilt library {@code libfoo.so} resides in
the same directory as the <a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a>
file that describes it.</p>
<pre>
LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := foo-prebuilt
LOCAL_SRC_FILES := libfoo.so
include $(PREBUILT_SHARED_LIBRARY)
</pre>
<p>In this example, the name of the module is the same as that of the prebuilt library.</p>
<p>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.</p>
<h2 id="rp">Referencing the Prebuilt Library from Other Modules</h2>
<p>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
<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> files associated with those
other modules.</p>
<p>For example, the description of a module using {@code libfoo.so} might be as follows:</p>
<pre>
include $(CLEAR_VARS)
LOCAL_MODULE := foo-user
LOCAL_SRC_FILES := foo-user.c
LOCAL_SHARED_LIBRARIES := foo-prebuilt
include $(BUILD_SHARED_LIBRARY)
</pre>
<p>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.</p>
<h2>Exporting Headers for Prebuilt Libraries</h2>
<p>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:</p>
<pre>
#include <foo.h>
</pre>
<p>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:</p>
<pre>
include $(CLEAR_VARS)
LOCAL_MODULE := foo-prebuilt
LOCAL_SRC_FILES := libfoo.so
LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include
include $(PREBUILT_SHARED_LIBRARY)
</pre>
<p>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.</p>
<p>This operation allows the build system to find the necessary headers.</p>
<h2 id="dp">Debugging Prebuilt Libraries</h2>
<p>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}.</p>
<h2 id="sa">Selecting ABIs for Prebuilt Libraries</h2>
<p>You must make sure to select the right version of your prebuilt shared library for your targeted
ABI. The <a href="{@docRoot}ndk/guides/android_mk.html#taa">
{@code TARGET_ARCH_ABI}</a> variable in the <a href="{@docRoot}ndk/guides/android_mk.html">
{@code Android.mk}</a> file can point the build system at the appropriate version of the library.
</p>
<p>For example, assume that your project contains two versions of library {@code libfoo.so}:</p>
<pre class="no-pretty-print">
armeabi/libfoo.so
x86/libfoo.so
</pre>
<p>The following snippet shows how to use {@code TARGET_ARCH_ABI} so that the build system selects
the appropriate version of the library:</p>
<pre>
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)
</pre>
<p>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.</p>
|
