Add support for prebuilt shared libraries.

Change-Id: I56de52c9206741c8300fb84e92602f75765f44a4

build/core/build-all.mk

@@ -46,6 +46,7 @@ BUILD_HOST_STATIC_LIBRARY := $(BUILD_SYSTEM)/build-host-static-library.mk
 BUILD_STATIC_LIBRARY      := $(BUILD_SYSTEM)/build-static-library.mk
 BUILD_SHARED_LIBRARY      := $(BUILD_SYSTEM)/build-shared-library.mk
 BUILD_EXECUTABLE          := $(BUILD_SYSTEM)/build-executable.mk
+PREBUILT_SHARED_LIBRARY   := $(BUILD_SYSTEM)/prebuilt-shared-library.mk
 
 ANDROID_MK_INCLUDED := \
   $(CLEAR_VARS) \

build/core/build-binary.mk

@@ -202,12 +202,10 @@ LOCAL_STATIC_LIBRARIES := $(call strip-lib-prefix,$(LOCAL_STATIC_LIBRARIES))
 LOCAL_SHARED_LIBRARIES := $(call strip-lib-prefix,$(LOCAL_SHARED_LIBRARIES))
 
 static_libraries := $(call map,static-library-path,$(LOCAL_STATIC_LIBRARIES))
-shared_libraries := $(call map,shared-library-path,$(LOCAL_SHARED_LIBRARIES)) \
+shared_libraries := $(call map,shared-library-path,$(LOCAL_SHARED_LIBRARIES))\
+                    $(call map,module-get-built,$(LOCAL_PREBUILTS))\
                     $(TARGET_PREBUILT_SHARED_LIBRARIES)
 
-$(call module-add-static-depends,$(LOCAL_MODULE),$(LOCAL_STATIC_LIBRARIES))
-$(call module-add-shared-depends,$(LOCAL_MODULE),$(LOCAL_SHARED_LIBRARIES))
-
 $(LOCAL_BUILT_MODULE): $(static_libraries) $(shared_libraries)
 
 # If LOCAL_LDLIBS contains anything like -l<library> then

build/core/definitions.mk

@@ -163,6 +163,7 @@ modules-LOCALS := \
     CPPFLAGS \
     STATIC_LIBRARIES \
     SHARED_LIBRARIES \
+    PREBUILTS \
     LDLIBS \
     ALLOW_UNDEFINED_SYMBOLS \
     ARM_MODE \
@@ -242,6 +243,10 @@ module-add-executable = \
     $(eval LOCAL_INSTALLED := $(NDK_APP_DST_DIR)/$(notdir $(LOCAL_BUILT_MODULE)))\
     $(call module-add,$1,executable)
 
+module-add-prebuilt-shared-library = \
+    $(eval LOCAL_INSTALLED := $(NDK_APP_DST_DIR)/$(notdir $(LOCAL_BUILT_MODULE)))\
+    $(call module-add,$1,prebuilt-shared-library)
+
 # Returns $(true) iff module $1 is of type $2
 module-is-type = $(call seq,$(__ndk_modules.$1.type),$2)
 
@@ -253,8 +258,8 @@ module-get-built = $(__ndk_modules.$1.BUILT_MODULE)
 # Returns $(true) is module $1 is of a given type
 module-is-static-library = $(call module-is-type,$1,static-library)
 module-is-shared-library = $(call module-is-type,$1,shared-library)
-module-is-exectuable     = $(call module-is-type,$1,executable)
-module-is-installable    = $(call or,$(call module-is-type,$1,shared-library),$(call module-is-type,$1,executable))
+module-is-executable     = $(call module-is-type,$1,executable)
+module-is-installable    = $(if $(filter shared-library executable prebuilt-shared-library,$(call module-get-type,$1)),$(true),$(false))
 
 # -----------------------------------------------------------------------------
 # Function : module-get-export
@@ -328,6 +333,9 @@ module-add-static-depends = \
 module-add-shared-depends = \
     $(call module-add-depends-any,$1,$2,depends) \
 
+module-add-prebuilt-depends = \
+    $(call module-add-depends-any,$1,$2,depends) \
+
 # Used internally by module-add-static-depends and module-add-shared-depends
 # NOTE: this function must not modify the existing dependency order when new depends are added.
 #
@@ -343,7 +351,8 @@ modules-compute-dependencies = \
 
 module-compute-depends = \
     $(call module-add-static-depends,$1,$(__ndk_modules.$1.STATIC_LIBRARIES))\
-    $(call module-add-shared-depends,$1,$(__ndk_modules.$1.SHARED_LIBRARIES))
+    $(call module-add-shared-depends,$1,$(__ndk_modules.$1.SHARED_LIBRARIES))\
+    $(call module-add-prebuilt-depends,$1,$(__ndk_modules.$1.PREBUILTS))
 
 module-get-installed = $(__ndk_modules.$1.INSTALLED)
 
@@ -379,11 +388,11 @@ modules-closure = \
 
 # Return the C++ extension of a given module
 #
-module-get-cpp-extension = \
+module-get-cpp-extension = $(strip \
     $(if $(__ndk_modules.$1.CPP_EXTENSION),\
         $(__ndk_modules.$1.CPP_EXTENSION),\
         .cpp\
-    )
+    ))
 
 # Return the list of C++ sources of a given module
 #
@@ -401,6 +410,7 @@ module-has-c++ = $(strip $(call module-get-c++-sources,$1))
 modules-add-c++-dependencies = \
     $(foreach __module,$(__ndk_modules),\
         $(if $(call module-has-c++,$(__module)),\
+            $(call ndk_log,Module '$(__module)' has C++ sources)\
             $(call module-add-c++-deps,$(__module),$1,$2),\
         )\
     )

build/core/prebuilt-shared-library.mk

+# Copyright (C) 2010 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# this file is included from Android.mk files to build a target-specific
+# shared library
+#
+
+LOCAL_BUILD_SCRIPT := PREBUILT_SHARED_LIBRARY
+LOCAL_MAKEFILE     := $(local-makefile)
+
+$(call check-defined-LOCAL_MODULE,$(LOCAL_BUILD_SCRIPT))
+$(call check-LOCAL_MODULE,$(LOCAL_MAKEFILE))
+
+# Check that LOCAL_SRC_FILES contains only paths to shared libraries
+ifneq ($(words $(LOCAL_SRC_FILES)),1)
+$(call __ndk_info,ERROR:$(LOCAL_MAKEFILE):$(LOCAL_MODULE): The LOCAL_SRC_FILES for a prebuilt shared library should only contain one item))
+$(call __ndk_error,Aborting)
+endif
+
+bad_prebuilts := $(filter-out %.so,$(LOCAL_SRC_FILES))
+ifdef bad_prebuilts
+$(call __ndk_info,ERROR:$(LOCAL_MAKEFILE):$(LOCAL_MODULE): LOCAL_SRC_FILES should point to a prebuilt shared library)
+$(call __ndk_info,The following files are unsupported: $(bad_prebuilts))
+$(call __ndk_error,Aborting)
+endif
+
+prebuilt := $(strip $(wildcard $(LOCAL_SRC_FILES)))
+ifndef prebuilt
+$(call __ndk_info,ERROR:$(LOCAL_MAKEFILE):$(LOCAL_MODULE): LOCAL_SRC_FILES points to a missing file)
+$(call __ndk_info,Check that $(LOCAL_SRC_FILES) exists, or that its path is correct)
+$(call __ndk_error,Aborting)
+endif
+
+LOCAL_BUILT_MODULE := $(LOCAL_SRC_FILES)
+LOCAL_SRC_FILES    :=
+LOCAL_OBJS_DIR     := $(TARGET_OBJS)/$(LOCAL_MODULE)
+
+$(call module-add-prebuilt-shared-library,$(LOCAL_MODULE))

docs/ANDROID-MK.TXT

@@ -202,6 +202,16 @@ BUILD_STATIC_LIBRARY
 
     Note that this will generate a file named lib$(LOCAL_MODULE).a
 
+PREBUILT_SHARED_LIBRARY
+    Points to a build script used to specify a prebuilt shared library.
+    Unlike BUILD_SHARED_LIBRARY and BUILD_STATIC_LIBRARY, the value
+    of LOCAL_SRC_FILES must be a single path to a prebuilt shared
+    library (e.g. $(LOCAL_PATH)/libfoo.so), instead of a source file.
+
+    You can reference the prebuilt library in another module using
+    the LOCAL_PREBUILTS variable (see docs/PREBUILTS.TXT for more
+    information).
+
 TARGET_ARCH
     Name of the target CPU architecture as it is specified by the
     full Android open-source build. This is 'arm' for any ARM-compatible
@@ -448,9 +458,12 @@ LOCAL_SHARED_LIBRARIES
     This is necessary at link time and to embed the corresponding information
     in the generated file.
 
-    Note that this does not append the listed modules to the build graph,
-    i.e. you should still add them to your application's required modules
-    in your Application.mk
+LOCAL_PREBUILTS
+    The list of prebuild shared library *modules* this module depends on at
+    runtime. This is necessary at link time and to embed the corresponding
+    information in the generated file.
+
+    See docs/PREBUILTS.TXT for more information.
 
 LOCAL_LDLIBS
     The list of additional linker flags to be used when building your

docs/CHANGES.TXT

@@ -35,6 +35,9 @@ IMPORTANT CHANGES:
     Note that they still correspond to our minimal C++ runtime, no new feature
     was introduced here.
 
+- Add support for prebuilt shared libraries with the PREBUILT_SHARED_LIBRARY
+  build script (instead of BUILD_SHARED_LIBRARY). See the new documentation
+  file named docs/PREBUILTS.TXT for explanations and usage examples.
 
 OTHER FIXES & CHANGES:
 

docs/PREBUILTS.TXT

+NDK Prebuilt library support:
+-----------------------------
+
+Android NDK r5 introduced support for prebuilt shared libraries, i.e.
+the ability to include and use, in your applications, prebuilt version
+of libraries. This document explains how this support works.
+
+
+I. Declaring a prebuilt shared library module:
+----------------------------------------------
+
+Each prebuilt library must be declared as an independent module to the
+build system. Here is a trivial example:
+
+   LOCAL_PATH := $(call my-dir)
+
+   include $(CLEAR_VARS)
+   LOCAL_MODULE := foo-prebuilt
+   LOCAL_SRC_FILES := $(LOCAL_PATH)/libfoo.so
+   include $(PREBUILT_SHARED_LIBRARY)
+
+Notice that, to declare such a module, you really only need the following:
+
+1. Give the module a name (here 'foo-prebuilt'). This does not need to
+   correspond to the name of the prebuilt shared library itself.
+
+2. Assign to LOCAL_SRC_FILES the path to the prebuilt library you are
+   providing.
+
+   IMPORTANT: You *must* ensure that the prebuilt library corresponds
+              to the target ABI you are using. More on this later.
+
+3. Include PREBUILT_SHARED_LIBRARY, instead of BUILD_SHARED_LIBRARY
+
+A prebuilt module does not build anything. However, a copy of your prebuilt
+shared library will be copied and stripped into $PROJECT/libs/<abi>.
+
+
+II. Referencing the prebuilt library in other modules:
+------------------------------------------------------
+
+If you are building code that depends on symbols provided by the prebuilt
+library, you can reference it through the LOCAL_PREBUILTS variable. It must
+contain a list of prebuilt module names that your module depends on.
+
+For example, a naive example of a module using libfoo.so would be:
+
+    include $(CLEAR_VARS)
+    LOCAL_MODULE := foo-user
+    LOCAL_SRC_FILES := foo-user.c
+    LOCAL_PREBUILTS := foo-prebuilt
+    include $(BUILD_SHARED_LIBRARY)
+
+
+III. Exporting headers for prebuilt libraries:
+----------------------------------------------
+
+The example above was called 'naive' because, in practice, the code in
+foo-user.c is going to depend on specific declarations that are normally
+found in a header file distributed with the prebuilt library (e.g. "foo.h").
+
+In other words, foo-user.c is going to have a line like:
+
+  #include <foo.h>
+
+And you need to provide the header and its include path to the compiler
+when building the foo-user module.
+
+A simple way to deal with that is to use exports in the prebuilt module
+definition. For example, assuming that a file "foo.h" is located under
+the 'include' directory relative to the prebuilt module, we can write:
+
+   include $(CLEAR_VARS)
+   LOCAL_MODULE := foo-prebuilt
+   LOCAL_SRC_FILES := $(LOCAL_PATH)/libfoo.so
+   LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include
+   include $(PREBUILT_SHARED_LIBRARY)
+
+The LOCAL_EXPORT_C_INCLUDES definition here ensures that any module that
+depends on the prebuilt one will have its LOCAL_C_INCLUDES automatically
+prepended with the path to the prebuilt's include directory, and will thus
+be able to find headers inside that.
+
+
+IV. Debugging prebuilt binaries:
+--------------------------------
+
+We recommend you to provide prebuilt shared libraries that contain debug
+symbols. The version that is installed into $PROJECT/libs/<abi>/ is always
+stripped by the NDK build system, but the debug version will be used for
+debugging purposes with ndk-gdb.
+
+
+V. ABI Selection of prebuilt binaries:
+--------------------------------------
+
+As said previously, it is crucial to provide a prebuilt shared library
+that is compatible with the targetted ABI during the build. To do that,
+check for the value of TARGET_ARCH_ABI, its value will be:
+
+   armeabi     => when targetting ARMv5TE or higher CPUs
+   armeabi-v7a => when targetting ARMv7 or higher CPUs
+   x86         => when targetting x86 CPUs
+
+Note that armeabi-v7a systems can run armeabi binaries just fine.
+
+Here's an example where we provide two versions of a prebuilt library
+and select which one to copy based on the target ABI:
+
+    include $(CLEAR_VARS)
+    LOCAL_MODULE := foo-prebuilt
+    LOCAL_SRC_FILES := $(LOCAL_PATH)/$(TARGET_ARCH_ABI)/libfoo.so
+    LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include
+    include $(PREBUILT_SHARED_LIBRARY)
+
+Here. we assume that the prebuilt libraries to copy are under the
+following directory hierarchy:
+
+    Android.mk            --> the file above
+    armeabi/libfoo.so     --> the armeabi prebuilt shared library
+    armeabi-v7a/libfoo.so --> the armeabi-v7a prebuilt shared library
+    include/foo.h         --> the exported header file
+
+NOTE: Remember that you don't need to provide an armeabi-v7a prebuilt
+      library, since an armeabi one can easily run on the corresponding
+      devices.