Android Studio 2.3使用CMake方式NDK入門
- 在嚮導的 Configure your new project 部分,選中 Include C++ Support 複選框。
- 點選 Next。
- 正常填寫所有其他欄位並完成嚮導接下來的幾個部分。
- 在嚮導的 Customize C++ Support 部分,您可以使用下列選項自定義專案:
- C++ Standard:使用下拉列表選擇您希望使用哪種 C++ 標準。選擇 Toolchain Default 會使用預設的 CMake 設定。
- Exceptions Support:如果您希望啟用對 C++ 異常處理的支援,請選中此複選框。如果啟用此複選框,Android Studio 會將
-fexceptions
標誌新增到模組級build.gradle
cppFlags
中,Gradle 會將其傳遞到 CMake。 - Runtime Type Information Support:如果您希望支援 RTTI,請選中此複選框。如果啟用此複選框,Android Studio 會將
-frtti
標誌新增到模組級build.gradle
檔案的cppFlags
中,Gradle 會將其傳遞到 CMake。
- 點選 Finish。
在 Android Studio 完成新專案的建立後,請從 IDE 左側開啟 Project 窗格並選擇 Android 檢視。如圖 中所示,Android Studio 將新增 cpp 和 External Build Files
注:此檢視無法反映磁碟上的實際檔案層次結構,而是將相似檔案分到一組中,簡化專案導航。
在 cpp 組中,您可以找到屬於專案的所有原生原始檔、標頭和預構建庫。對於新專案,Android Studio 會建立一個示例 C++ 原始檔native-lib.cpp
,並將其置於應用模組的 src/main/cpp/
目錄中。本示例程式碼提供了一個簡單的 C++ 函式 stringFromJNI()
,此函式可以返回字串“Hello
from C++”。要了解如何向專案新增其他原始檔,請參閱介紹如何建立新的原生原始檔的部分。在 External Build Filesbuild.gradle
檔案指示 Gradle 如何構建應用一樣,CMake 和 ndk-build 需要一個構建指令碼來了解如何構建您的原生庫。對於新專案,Android Studio 會建立一個 CMake 構建指令碼 CMakeLists.txt
,並將其置於模組的根目錄中。要詳細瞭解此構建指令碼的內容,請參閱介紹如何建立
Cmake 構建指令碼的部分。構建和執行示例應用
點選 Run 後,Android Studio 將在您的 Android 裝置或者模擬器上構建並啟動一個顯示文字“Hello from C++”的應用。下面的概覽介紹了構建和執行示例應用時會發生的事件:
- Gradle 呼叫您的外部構建指令碼
CMakeLists.txt
。 - CMake 按照構建指令碼中的命令將 C++ 原始檔
native-lib.cpp
編譯到共享的物件庫中,並命名為libnative-lib.so
,Gradle 隨後會將其封裝到 APK 中。 - 執行時,應用的
MainActivity
會使用System.loadLibrary()
載入原生庫。現在,應用可以使用庫的原生函式stringFromJNI()
。 MainActivity.onCreate()
呼叫stringFromJNI()
,這將返回“Hello from C++”並使用這些文字更新TextView
。
注:Instant Run 與使用原生程式碼的專案不相容。Android Studio 會自動停用此功能。
如果您想要驗證 Gradle 是否已將原生庫封裝到 APK 中,可以使用 APK 分析器:
- 選擇 Build > Analyze APK。
- 從
app/build/outputs/apk/
目錄中選擇 APK 並點選 OK。 - 如圖 3 中所示,您會在 APK 分析器視窗的
lib/<ABI>/
下看到libnative-lib.so
。
提示:如果您想要試驗使用原生程式碼的其他 Android 應用,請點選 File > New > Import Sample 並從 Ndk 列表中選擇示例專案。
也可以到目錄app\build\intermediates\cmake\debug\obj中檢視so檔案,如下圖
同時可以通過在gradle中指定abi
ndk { // Specifies the ABI configurations of your native // libraries Gradle should build and package with your APK. abiFilters 'x86', 'x86_64', 'armeabi', 'armeabi-v7a', 'arm64-v8a' }
生成多個so檔案,參考部落格:http://blog.csdn.net/b2259909/article/details/58591898
向現有專案新增 C/C++ 程式碼
如果您希望向現有專案新增原生程式碼,請執行以下步驟:
- 建立新的原生原始檔並將其新增到您的 Android Studio 專案中。
- 如果您已經擁有原生程式碼或想要匯入預構建的原生庫,則可以跳過此步驟。
- 建立 CMake 構建指令碼,將您的原生原始碼構建到庫中。如果匯入和關聯預構建庫或平臺庫,您也需要此構建指令碼。
- 如果您的現有原生庫已經擁有
CMakeLists.txt
構建指令碼或者使用 ndk-build 幷包含Android.mk
構建指令碼,則可以跳過此步驟。
- 如果您的現有原生庫已經擁有
- 提供一個指向您的 CMake 或 ndk-build 指令碼檔案的路徑,將 Gradle 關聯到您的原生庫。Gradle 使用構建指令碼將原始碼匯入您的 Android Studio 專案並將原生庫(SO 檔案)封裝到 APK 中。
配置完專案後,您可以使用 JNI 框架從 Java 程式碼中訪問您的原生函式。要構建和執行應用,只需點選 Run 。Gradle 會以依賴項的形式新增您的外部原生構建流程,用於編譯、構建原生庫並將其隨 APK 一起封裝。
建立新的原生原始檔
要在應用模組的主原始碼集中建立一個包含新建原生原始檔的 cpp/
目錄,請按以下步驟操作:
- 從 IDE 的左側開啟 Project 窗格並從下拉選單中選擇 Project 檢視。
- 導航到您的模組 > src,右鍵點選 main 目錄,然後選擇 New > Directory。
- 為目錄輸入一個名稱(例如
cpp
)並點選 OK。 - 右鍵點選您剛剛建立的目錄,然後選擇 New > C/C++ Source File。
- 為您的原始檔輸入一個名稱,例如
native-lib
。 - 從 Type 下拉選單中,為您的原始檔選擇副檔名,例如
.cpp
。- 點選 Edit File Types ,您可以向下拉選單中新增其他檔案型別,例如
.cxx
或.hxx
。在彈出的 C/C++ 對話方塊中,從 Source Extension 和 Header Extension 下拉選單中選擇另一個副檔名,然後點選 OK。
- 點選 Edit File Types ,您可以向下拉選單中新增其他檔案型別,例如
- 如果您還希望建立一個標標頭檔案,請選中 Create an associated header 複選框。
- 點選 OK。
建立 CMake 構建指令碼
如果您的原生原始檔還沒有 CMake 構建指令碼,則您需要自行建立一個幷包含適當的 CMake 命令。CMake 構建指令碼是一個純文字檔案,您必須將其命名為 CMakeLists.txt
。本部分介紹了您應包含到構建指令碼中的一些基本命令,用於在建立原生庫時指示 CMake 應使用哪些原始檔。
注:如果您的專案使用 ndk-build,則不需要建立 CMake 構建指令碼。提供一個指向您的 Android.mk
檔案的路徑,將
Gradle 關聯到您的原生庫。
要建立一個可以用作 CMake 構建指令碼的純文字檔案,請按以下步驟操作:
- 從 IDE 的左側開啟 Project 窗格並從下拉選單中選擇 Project 檢視。
- 右鍵點選您的模組的根目錄並選擇 New > File。
注:您可以在所需的任意位置建立構建指令碼。不過,在配置構建指令碼時,原生原始檔和庫的路徑將與構建指令碼的位置相關。
- 輸入“CMakeLists.txt”作為檔名並點選 OK。
現在,您可以新增 CMake 命令,對您的構建指令碼進行配置。要指示 CMake 從原生原始碼建立一個原生庫,請將 cmake_minimum_required()
和 add_library()
命令新增到您的構建指令碼中:
# Sets the minimum version of CMake required to build your native library. # This ensures that a certain set of CMake features is available to # your build. cmake_minimum_required(VERSION 3.4.1) # Specifies a library name, specifies whether the library is STATIC or # SHARED, and provides relative paths to the source code. You can # define multiple libraries by adding multiple add.library() commands, # and CMake builds them for you. When you build your app, Gradle # automatically packages shared libraries with your APK. add_library( # Specifies the name of the library. native-lib # Sets the library as a shared library. SHARED # Provides a relative path to your source file(s). src/main/cpp/native-lib.cpp )
使用 add_library()
向您的 CMake 構建指令碼新增原始檔或庫時,Android Studio 還會在您同步專案後在 Project 檢視下顯示關聯的標標頭檔案。不過,為了確保 CMake 可以在編譯時定位您的標標頭檔案,您需要將 include_directories()
命令新增到
CMake 構建指令碼中並指定標頭的路徑:
add_library(...) # Specifies a path to native header files. include_directories(src/main/cpp/include/)
CMake 使用以下規範來為庫檔案命名:
lib庫名稱.so
例如,如果您在構建指令碼中指定“native-lib”作為共享庫的名稱,CMake 將建立一個名稱為 libnative-lib.so
的檔案。不過,在 Java 程式碼中載入此庫時,請使用您在 CMake 構建指令碼中指定的名稱:
static{System.loadLibrary(“native-lib”);}
注:如果您在 CMake 構建指令碼中重新命名或移除某個庫,您需要先清理專案,Gradle 隨後才會應用更改或者從 APK 中移除舊版本的庫。要清理專案,請從選單欄中選擇 Build > Clean Project。
Android Studio 會自動將原始檔和標頭新增到 Project 窗格的 cpp 組中。使用多個 add_library()
命令,您可以為 CMake 定義要從其他原始檔構建的更多庫。
新增 NDK API
Android NDK 提供了一套實用的原生 API 和庫。通過將 NDK 庫包含到專案的 CMakeLists.txt
指令碼檔案中,您可以使用這些 API 中的任意一種。
預構建的 NDK 庫已經存在於 Android 平臺上,因此,您無需再構建或將其封裝到 APK 中。由於 NDK 庫已經是 CMake 搜尋路徑的一部分,您甚至不需要在您的本地 NDK 安裝中指定庫的位置 - 只需要向 CMake 提供您希望使用的庫的名稱,並將其關聯到您自己的原生庫。
將 find_library()
命令新增到您的 CMake 構建指令碼中以定位
NDK 庫,並將其路徑儲存為一個變數。您可以使用此變數在構建指令碼的其他部分引用 NDK 庫。以下示例可以定位 Android 特定的日誌支援庫並將其路徑儲存在 log-lib
中:
find_library( # Defines the name of the path variable that stores the # location of the NDK library. log-lib # Specifies the name of the NDK library that # CMake needs to locate. log )
為了確保您的原生庫可以在 log
庫中呼叫函式,您需要使用 CMake 構建指令碼中的 target_link_libraries()
命令關聯庫:
find_library(...) # Links your native library against one or more other native libraries. target_link_libraries( # Specifies the target library. native-lib # Links the log library to the target library. ${log-lib} )
NDK 還以原始碼的形式包含一些庫,您在構建和關聯到您的原生庫時需要使用這些程式碼。您可以使用 CMake 構建指令碼中的 add_library()
命令,將原始碼編譯到原生庫中。要提供本地 NDK 庫的路徑,您可以使用 ANDROID_NDK
路徑變數,Android Studio 會自動為您定義此變數。
以下命令可以指示 CMake 構建 android_native_app_glue.c
,後者會將 NativeActivity
生命週期事件和觸控輸入置於靜態庫中並將靜態庫關聯到 native-lib
:
add_library( app-glue STATIC ${ANDROID_NDK}/sources/android/native_app_glue/android_native_app_glue.c ) # You need to link static libraries against your shared native library. target_link_libraries( native-lib app-glue ${log-lib} )
新增其他預構建庫
新增預構建庫與為 CMake 指定要構建的另一個原生庫類似。不過,由於庫已經預先構建,您需要使用 IMPORTED
標誌告知
CMake 您只希望將庫匯入到專案中:
add_library( imported-lib SHARED IMPORTED )
某些庫為特定的 CPU 架構(或應用二進位制介面 (ABI))提供了單獨的軟體包,並將其組織到單獨的目錄中。此方法既有助於庫充分利用特定的 CPU 架構,又能讓您僅使用所需的庫版本。要向 CMake 構建指令碼中新增庫的多個
ABI 版本,而不必為庫的每個版本編寫多個命令,您可以使用 ANDROID_ABI
路徑變數。此變數使用 NDK 支援的一組預設 ABI,或者您手動配置
Gradle 而讓其使用的一組經過篩選的 ABI。例如:
add_library(...) set_target_properties( # Specifies the target library. imported-lib # Specifies the parameter you want to define. PROPERTIES IMPORTED_LOCATION # Provides the path to the library you want to import. imported-lib/src/${ANDROID_ABI}/libimported-lib.so )
為了確保 CMake 可以在編譯時定位您的標標頭檔案,您需要使用 include_directories()
命令,幷包含標標頭檔案的路徑:
include_directories( imported-lib/include/ )
注:如果您希望封裝一個並不是構建時依賴項的預構建庫(例如在新增屬於 imported-lib
依賴項的預構建庫時),則不需要執行以下說明來關聯庫。
要將預構建庫關聯到您自己的原生庫,請將其新增到 CMake 構建指令碼的 target_link_libraries()
命令中:
target_link_libraries( native-lib imported-lib app-glue ${log-lib} )
在您構建應用時,Gradle 會自動將匯入的庫封裝到 APK 中。您可以使用 APK 分析器驗證 Gradle 將哪些庫封裝到您的 APK 中。如需瞭解有關 CMake 命令的詳細資訊,請參閱 CMake 文件。
將 Gradle 關聯到您的原生庫
要將 Gradle 關聯到您的原生庫,您需要提供一個指向 CMake 或 ndk-build 指令碼檔案的路徑。在您構建應用時,Gradle 會以依賴項的形式執行 CMake 或 ndk-build,並將共享的庫封裝到您的 APK 中。Gradle 還使用構建指令碼來了解要將哪些檔案新增到您的 Android Studio 專案中,以便您可以從 Project 視窗訪問這些檔案。如果您的原生原始檔沒有構建指令碼,則需要先建立 CMake 構建指令碼,然後再繼續。
將 Gradle 關聯到原生專案後,Android Studio 會更新 Project 窗格以在 cpp 組中顯示您的原始檔和原生庫,在 External Build Files 組中顯示您的外部構建指令碼。
注:更改 Gradle 配置時,請確保通過點選工具欄中的 Sync Project 應用更改。此外,如果在將 CMake 或 ndk-build 指令碼檔案關聯到 Gradle 後再對其進行更改,您應當從選單欄中選擇 Build > Refresh Linked C++ Projects,將 Android Studio 與您的更改同步。
使用 Android Studio UI
您可以使用 Android Studio UI 將 Gradle 關聯到外部 CMake 或 ndk-build 專案:
- 從 IDE 左側開啟 Project 窗格並選擇 Android 檢視。
- 右鍵點選您想要關聯到原生庫的模組(例如 app 模組),並從選單中選擇 Link C++ Project with Gradle。您應看到一個如圖 4 所示的對話方塊。
- 從下拉選單中,選擇 CMake 或 ndk-build。
- 如果您選擇 CMake,請使用 Project Path 旁的欄位為您的外部 CMake 專案指定
CMakeLists.txt
指令碼檔案。 - 如果您選擇 ndk-build,請使用 Project Path 旁的欄位為您的外部 ndk-build 專案指定
Android.mk
指令碼檔案。如果Application.mk
檔案與您的Android.mk
檔案位於相同目錄下,Android Studio 也會包含此檔案。
- 如果您選擇 CMake,請使用 Project Path 旁的欄位為您的外部 CMake 專案指定
- 點選 OK。
手動配置 Gradle
要手動配置 Gradle 以關聯到您的原生庫,您需要將 externalNativeBuild {}
塊新增到模組級 build.gradle
檔案中,並使用 cmake {}
或 ndkBuild {}
對其進行配置:
android {... defaultConfig {...} buildTypes {...}// Encapsulates your external native build configurations. externalNativeBuild {// Encapsulates your CMake build configurations. cmake {// Provides a relative path to your CMake build script. path "CMakeLists.txt"}}}
注:如果您想要將 Gradle 關聯到現有 ndk-build 專案,請使用 ndkBuild {}
塊而不是 cmake {}
,並提供 Android.mk
檔案的相對路徑。如果 Application.mk
檔案與您的 Android.mk
檔案位於相同目錄下,Gradle
也會包含此檔案。
指定可選配置
您可以在模組級 build.gradle
檔案的 defaultConfig {}
塊中配置另一個 externalNativeBuild {}
塊,為 CMake 或 ndk-build 指定可選引數和標誌。與 defaultConfig {}
塊中的其他屬性類似,您也可以在構建配置中為每個產品風味重寫這些屬性。
例如,如果您的 CMake 或 ndk-build 專案定義多個原生庫,您可以使用 targets
屬性僅為給定產品風味構建和封裝這些庫中的一部分。以下程式碼示例說明了您可以配置的部分屬性:
android {... defaultConfig {...// This block is different from the one you use to link Gradle// to your CMake or ndk-build script. externalNativeBuild {// For ndk-build, instead use ndkBuild {} cmake {// Passes optional arguments to CMake. arguments "-DANDROID_ARM_NEON=TRUE","-DANDROID_TOOLCHAIN=clang"// Sets optional flags for the C compiler. cFlags "-D_EXAMPLE_C_FLAG1","-D_EXAMPLE_C_FLAG2"// Sets a flag to enable format macro constants for the C++ compiler. cppFlags "-D__STDC_FORMAT_MACROS"}}} buildTypes {...} productFlavors {... demo {... externalNativeBuild { cmake {...// Specifies which native libraries to build and package for this// product flavor. If you don't configure this property, Gradle// builds and packages all shared object libraries that you define// in your CMake or ndk-build project. targets "native-lib-demo"}}} paid {... externalNativeBuild { cmake {... targets "native-lib-paid"}}}}// Use this block to link Gradle to your CMake or ndk-build script. externalNativeBuild { cmake {...}// or ndkBuild {...}}}
要詳細瞭解配置產品風味和構建變體,請參閱配置構建變體。如需瞭解您可以使用 arguments
屬性為 CMake 配置的變數列表,請參閱使用
CMake 變數。
指定 ABI
預設情況下,Gradle 會針對 NDK 支援的 ABI 將您的原生庫構建到單獨的 .so
檔案中,並將其全部封裝到您的 APK 中。如果您希望 Gradle 僅構建和封裝原生庫的特定
ABI 配置,您可以在模組級 build.gradle
檔案中使用 ndk.abiFilters
標誌指定這些配置,如下所示:
android {... defaultConfig {... externalNativeBuild { cmake {...}// or ndkBuild {...}} ndk {// Specifies the ABI configurations of your native// libraries Gradle should build and package with your APK. abiFilters 'x86','x86_64','armeabi','armeabi-v7a','arm64-v8a'}} buildTypes {...} externalNativeBuild {...}}
在大多數情況下,您只需要在 ndk {}
塊中指定 abiFilters
(如上所示),因為它會指示 Gradle 構建和封裝原生庫的這些版本。不過,如果您希望控制 Gradle 應當構建的配置,並獨立於您希望其封裝到 APK 中的配置,請在 defaultConfig.externalNativeBuild.cmake {}
塊(或 defaultConfig.externalNativeBuild.ndkBuild
{}
塊中)配置另一個 abiFilters
標誌。Gradle 會構建這些 ABI 配置,不過僅會封裝您在 defaultConfig.ndk{}
塊中指定的配置。
為了進一步降低 APK 的大小,請考慮配置 ABI APK 拆分,而不是建立一個包含原生庫所有版本的大型 APK,Gradle 會為您想要支援的每個
ABI 建立單獨的 APK,並且僅封裝每個 ABI 需要的檔案。如果您配置 ABI 拆分,但沒有像上面的程式碼示例一樣指定 abiFilters
標誌,Gradle 會構建原生庫的所有受支援 ABI 版本,不過僅會封裝您在 ABI 拆分配置中指定的版本。為了避免構建您不想要的原生庫版本,請為 abiFilters
標誌和 ABI 拆分配置提供相同的 ABI 列表。