Using a library as a prebuilt library

The previous recipe described how to build an existing library with its own build system. We obtained a compiled static library libbmp.a of the open source libbmp library. This recipe will discuss how to use a prebuilt library.

How to do it...

The following steps build an Android NDK application which uses prebuilt library. Note that the sample project is based on what we have done in the previous recipe. If you have not gone through previous recipe, you should do it now.

  1. Open the PortingWithBuildSystem project that you created in previous recipe. Add a Java file MainActivity.java under the cookbook.chapter8.portingwithbuildsystem package. This Java file simply loads the shared library PortingWithBuildSystem, and calls the native method naCreateABmp.
  2. Add the mylog.h and PortingWithBuildSystem.c files under it. PortingWithBuildSystem.c implements the native method naCreateABmp.
  3. Create an Android.mk file under the jni folder to compile PortingWithBuildSystem.c as a shared library libPortingWithBuildSystem.so. The content of this Android.mk file is as follows:
    LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := libbmp-prebuilt
LOCAL_SRC_FILES := libbmp-0.1.3/lib/libbmp.a
LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/libbmp-0.1.3/include/
include $(PREBUILT_STATIC_LIBRARY)
include $(CLEAR_VARS)
LOCAL_MODULE    := PortingWithBuildSystem
LOCAL_SRC_FILES := PortingWithBuildSystem.c
LOCAL_STATIC_LIBRARIES := libbmp-prebuilt
LOCAL_LDLIBS := -llog
include $(BUILD_SHARED_LIBRARY)
  4. Add the WRITE_EXTERNAL_STORAGE permission to the AndroidManifest.xml file as follows:
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
  5. Build and run the Android project. A bitmap file test_bs_static.bmp should be created at the sdcard folder of the Android device. We can use the following command to get the file:
    $ adb pull /sdcard/test_bs_static.bmp .

    The file is the same as test_static.bmp shown in the Porting a library as shared library module with Android NDK build system recipe of this chapter.

How it works...

There are two common use cases for prebuilt libraries:

  • You want to use a library from a third-party developer and only the library binary is provided
  • You have already built a library and want to use the library without recompiling it

Your sample project belongs to the second case. Let's look at the things to consider when using a prebuilt library in Android NDK:

  1. Declare a prebuilt library module: In Android NDK, a build module can either be a static or shared library. You have seen how a module is declared with source code. It is similar when a module is based on a prebuilt library.

    i. Declare the module name: This is done with the LOCAL_MODULE module description variable. In your sample project, define the module name with the following line:

    	LOCAL_MODULE := libbmp-prebuilt

    ii. List the source for the prebuilt library: You will provide the path of the prebuilt library to the LOCAL_SRC_FILES variable. Note that the path is relative to LOCAL_PATH. In your sample project, list the path to the libbmp.a static library as follows:

    	LOCAL_SRC_FILES := libbmp-0.1.3/lib/libbmp.a

    iii. Export the library headers: This is done through the LOCAL_EXPORT_C_INCLUDES module description variable. The variable ensures that any modules that depend on the prebuilt library module will have the path to the library headers appended to LOCAL_C_INCLUDES automatically. Note that this step is optional, as we can also explicitly add the path to library headers to any modules that depend on the prebuilt library module. However, it is a better practice to export the headers instead of adding the path on every module that depends on the prebuilt library module.

    In your sample project, export the library headers with the following line in the Android.mk file:

    LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/libbmp-0.1.3/include/

    iv. Export the compiler and/or linker flags: This can be done with LOCAL_EXPORT_CFLAGS, LOCAL_EXPORT_CPPFLAGS, and LOCAL_EXPORT_LDLIBS. This step is also optional and we won't use them in your sample project. You can refer to docs/ANDROID-MK.html at Android NDK for more detailed information about these module description variables.

    v. Declare a build type: You will need to include PREBUILT_SHARED_LIBRARY for the shared prebuilt library and PREBUILT_STATIC_LIBRARY for the static prebuilt library. In your sample project, use the following line to declare that you want to build a prebuilt static library module:

    	include $(PREBUILT_STATIC_LIBRARY)
  2. Use the prebuilt library module: Once you have the prebuilt library module in place, you can simply list the module name in the LOCAL_STATIC_LIBRARIES or LOCAL_SHARED_LIBRARIES declaration of any module that depends on the prebuilt library. This is shown in your sample project's Android.mk file:
    LOCAL_STATIC_LIBRARIES := libbmp-prebuilt
  3. Prebuilt library for debugging: It is recommended by Android NDK that you provide the prebuilt library binaries that contain debug symbols, to facilitate debugging with ndk-gdb. When you package the library into an apk file, a stripped version created by Android NDK (at the project's libs/<abi>/ folder) will be used.

    Tip

    We don't discuss how to generate the debug version of a library because it depends on how the library is built. Normally, the library documentation will contain instructions of how to generate a debug build. If you're building the library using GCC directly, then you can refer to http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html for various options for debugging.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset