在專案中新增 C 和 C++ 程式碼

將程式碼放入專案模組的 cpp 目錄中,即可將 C 和 C++ 程式碼新增至 Android 專案。當您建構專案時,這個程式碼會編譯為 Gradle 可封裝至應用程式的原生程式庫。您的 Java 或 Kotlin 程式碼可以透過 Java Native Interface (例如 JNI)。如要進一步瞭解如何使用 JNI 架構,請參閱 Android 適用的 JNI 提示

Android Studio 支援 CMake (適合跨平台專案),以及 ndk-build,速度比 CMake 快,但僅支援 Android。目前不支援在相同模組中使用 CMake 和 ndk-build。

如果您想將現有的 ndk-build 程式庫匯入 Android Studio 專案,請參閱這篇文章,瞭解如何將 Gradle 連結至原生資料庫專案。

本頁面將說明如何使用必要的建構工具設定 Android Studio、透過 C/C++ 支援功能建立新專案,以及在您的專案中新增 C/C++ 檔案

如要在現有專案中新增原生程式碼,請按照下列步驟操作:

  1. 建立新的原生來源檔案,並將其新增至您的 Android Studio 專案。
    • 如果您已有原生程式碼,或想要匯入預先建立的原生資料庫,請略過這個步驟。
  2. 設定 CMake,將原生原始碼建構到資料庫中。如要匯入預先建構或使用的平台資料庫並建立連結,您也需要這個建構指令碼。
    • 如果現有的原生資料庫已擁有 CMakeLists.txt 建構指令碼,或者使用 ndk-build 並包含 Android.mk 建構指令碼,可以略過這個步驟。
  3. 提供 CMake 或 ndk-build 指令碼檔案的路徑,設定 Gradle。Gradle 會使用建構指令碼將原始碼匯入您的 Android Studio 專案,並將原生資料庫 (SO 檔案) 封裝到應用程式中。

設定專案後,您可以使用 JNI 架構從 Java 或 Kotlin 程式碼存取原生函式。如要建構並執行應用程式,只要按一下「執行」 從選單列執行並執行應用程式 即可。

注意:如果現有專案使用的是已淘汰的 ndkCompile 工具,請改用 CMake 或 ndk-build。詳情請參閱如何從 ndkCompile 遷移一節。

注意 Gradle 實驗版使用者:請考慮 遷移至 2.2.0 以上版本外掛程式,並使用 CMake 或 ndk-build 建構原生程式庫 (如果有的話)適用於您的情況:您的原生專案已使用 CMake 或 ndk-build;建議使用穩定版的 Gradle 建構系統;或是取得 CCache 等外掛程式工具的支援。 或者,您可以使用 Gradle 和 Android 外掛程式的實驗版本

下載 NDK 並建構工具

如要針對應用程式編譯及偵錯原生程式碼,您必須具備下列元件:

  • Android Native Development Kit (NDK):這個工具組可讓您搭配 Android 使用 C 和 C++ 程式碼,並且提供平台程式庫,讓您管理原生活動,以及存取實體裝置元件 (例如感應器和觸控輸入)。
  • CMake:一種外部建構工具,可與 Gradle 搭配使用來建構原生資料庫。如果您只打算使用 ndk-build,就不需要這個元件。
  • LLDB:Android Studio 用來為原生程式碼進行偵錯的偵錯工具。

如要進一步瞭解如何安裝這些元件,請參閱安裝並設定 NDK、CMake 和 LLDB

建立支援 C/C++ 的新專案

建立支援原生程式碼的新專案,方法與建立任何其他 Android Studio 專案很類似,但還有其他步驟:

  1. 在精靈的「Choose your project」(選擇專案) 部分,選取 「Native C++」 原生專案類型。
  2. 按一下「繼續」。
  3. 在精靈的下一個區段中填寫所有其他欄位。
  4. 按一下「繼續」。
  5. 在精靈的「自訂 C++ 支援」部分,您可以使用「C++ 標準」欄位自訂專案。在下拉式清單中,選取要使用的 C++ 標準化。選取 「工具鏈預設」 並使用預設的 CMake 設定。
  6. 按一下「完成」

Android Studio 專案建立完成後,請開啟 IDE 左側的「專案」窗格,然後選取「Android」 檢視畫面。如圖 2 所示,Android Studio 新增了 cpp 群組:

圖 2. 適用於原生來源和外部建構指令碼的 Android 檢視表群組。

注意:這個畫面不會反映磁碟中實際的檔案階層,但會將類似的檔案分組以簡化專案瀏覽作業。

cpp 群組可讓您找到所有原生來源檔案、標頭、CMake 或 ndk-build 的建構指令碼,以及屬於您專案的預先建構程式庫。如果是新專案,Android Studio 則會建立 C++ 來源檔案範例 native-lib.cpp,並放置在應用程式模組的 src/main/cpp/ 目錄中。這個程式碼範例會提供簡易的 C++ 函式 stringFromJNI(),會傳回「Hello from C++」字串。如要瞭解如何將其他來源檔案新增至專案,請參閱「建立新的原生來源檔案」一節。

就像 build.gradle 檔案是如何向 Gradle 宣告應用程式一樣,CMake 與 ndk-build 都需要建構指令碼來瞭解如何建構原生程式庫。如果是新專案,Android Studio 會建立 CMake 建構指令碼 CMakeLists.txt,並放置在模組的根目錄中。如要進一步瞭解此版本指令碼的內容,請參閱設定 CMake

建構並執行範例應用程式

按一下「執行」 從選單列執行並執行應用程式 後,Android Studio 就會建構並啟動應用程式,並在您的 Android 裝置或模擬器上顯示「Hello C++」的訊息。以下總覽說明建構和執行範例應用程式時所發生的事件:

  1. Gradle 呼叫外部建構指令碼 CMakeLists.txt
  2. CMake 按照建構指令碼中的指令將 C++ 來源檔案 native-lib.cpp 編譯成共用物件程式庫,並將其命名為 libnative-lib.so,Gradle 隨後將套件封裝至應用程式。
  3. 在執行階段,應用程式的 MainActivity 會使用 System.loadLibrary() 載入原生資料庫。應用程式現在可以使用程式庫的原生函式 stringFromJNI()
  4. MainActivity.onCreate() 會呼叫 stringFromJNI(),其會傳回「Hello from C++」,然後用來更新 TextView

注意事項:「即時執行」不適用於以原生程式碼編寫的專案元件。

如要驗證 Gradle 是否在應用程式中封裝原生資料庫,請使用 APK 分析工具

  1. 依序選取「建立」>「版本組合/APK」>「建立 APK」
  2. 依序選取「建立」>「分析 APK」
  3. app/build/outputs/ 目錄中選取 APK 或 AAB,然後按一下「確定」
  4. 如圖 3 所示,您可以在 APK 視窗視窗中的 lib/<ABI>/ 之下看到 libnative-lib.so

    圖 3. 使用 APK 分析工具找出原生資料庫。

提示:如要測試使用其他原生程式碼的 Android 應用程式,請依序按一下「檔案」>「新增」>「匯入樣本」,然後從Ndk 清單。

建立新 C/C++ 來源檔案

如要在現有專案中新增 C/C++ 來源檔案,請按照下列步驟操作:

  1. 如果應用程式的主要來源集中沒有 cpp/ 目錄,請按照下列步驟操作:
    1. 開啟 IDE 左側的「專案」窗格,然後從下拉式選單中選取 「專案」 檢視畫面。
    2. 前往 your-module > src,在 main 目錄中按一下滑鼠右鍵,然後選取「新增」 > 「Directory」
    3. 輸入 cpp 做為目錄名稱,然後按一下「OK」 (確定)

  2. cpp/ 目錄上按一下滑鼠右鍵,然後選取「新增」 > 「C/C++ 來源檔案」
  3. 輸入來源檔案的名稱,例如 native-lib
  4. 在「類型」下拉式選單中,選取來源檔案的副檔名,例如 .cpp
    • 如要在其他下拉式選單中新增檔案類型 (例如 .cxx.hxx),請按一下 「編輯檔案類型」 。在彈出的「C/C++」對話方塊中,從「Source Extension」和「Header Extension」下拉式選單選取其他副檔名下拉式選單,然後按一下 「OK」 (確定)
  5. 如要一併建立標頭檔案,請勾選 「建立相關標頭」 核取方塊。
  6. 按一下「確定」

在專案中新增 C/C++ 檔案之後,您還是需要設定 CMake,將其納入原生程式庫中。

其他資源

如要進一步瞭解如何在應用程式中支援 C/C++ 程式碼,請使用下列資源。

Codelab