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 <foo.h> 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