Bazel 教學課程:建構 Android 應用程式

回報問題 查看來源 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

注意:使用 Bazel 建構 Android 應用程式時,會遇到一些已知限制。請前往 Github team-Android hotlist 查看已知問題清單。Bazel 團隊和開放原始碼軟體 (OSS) 貢獻者正積極解決已知問題,但請注意,Android Studio 並未正式支援 Bazel 專案。

本教學課程說明如何使用 Bazel 建構簡單的 Android 應用程式。

Bazel 支援使用 Android 規則建構 Android 應用程式。

本教學課程適用於 Windows、macOS 和 Linux 使用者,不需具備 Bazel 或 Android 應用程式開發經驗。在本教學課程中,您不需要編寫任何 Android 程式碼。

課程內容

在本教學課程中,您將瞭解如何:

  • 安裝 Bazel 和 Android Studio,並下載範例專案,設定開發環境。
  • 設定 Bazel 工作區,其中包含應用程式的原始碼,以及可識別工作區目錄頂層的 WORKSPACE 檔案。
  • 更新 WORKSPACE 檔案,加入必要外部依附元件 (例如 Android SDK) 的參照。
  • 建立 BUILD 檔案。
  • 使用 Bazel 建構應用程式。
  • 在 Android 模擬器或實體裝置上部署及執行應用程式。

事前準備

安裝 Bazel

開始本教學課程前,請先安裝下列軟體:

  • Bazel。如要安裝,請按照安裝說明操作。
  • Android Studio。如要安裝,請按照步驟下載 Android Studio。 執行設定精靈,下載 SDK 並設定環境。
  • (選用) Git。使用 git 下載 Android 應用程式專案。

取得範例專案

對於範例專案,請使用 Bazel 範例存放區中的基本 Android 應用程式專案。

這個應用程式只有一個按鈕,點選後會顯示問候語:

按鈕問候語

圖 1. Android 應用程式按鈕問候語。

使用 git 複製存放區 (或直接下載 ZIP 檔案):

git clone https://github.com/bazelbuild/examples

本教學課程的範例專案位於 examples/android/tutorial。在本教學課程的其餘部分,您將在這個目錄中執行指令。

查看來源檔案

查看應用程式的來源檔案。

.
├── README.md
└── src
    └── main
        ├── AndroidManifest.xml
        └── java
            └── com
                └── example
                    └── bazel
                        ├── AndroidManifest.xml
                        ├── Greeter.java
                        ├── MainActivity.java
                        └── res
                            ├── layout
                            │   └── activity_main.xml
                            └── values
                                ├── colors.xml
                                └── strings.xml

重要檔案和目錄如下:

名稱 位置
Android 資訊清單檔案 src/main/AndroidManifest.xmlsrc/main/java/com/example/bazel/AndroidManifest.xml
Android 來源檔案 src/main/java/com/example/bazel/MainActivity.javaGreeter.java
資源檔案目錄 src/main/java/com/example/bazel/res/

使用 Bazel 建構

設定工作區

工作區是包含一或多個軟體專案來源檔案的目錄,且根目錄中含有 WORKSPACE 檔案。

WORKSPACE 檔案可能為空白,也可能包含建構專案所需的外部依附元件參照。

首先,請執行下列指令來建立空白的 WORKSPACE 檔案:

作業系統 指令
Linux、macOS touch WORKSPACE
Windows (命令提示字元) type nul > WORKSPACE
Windows (PowerShell) New-Item WORKSPACE -ItemType file

執行 Bazel

現在可以使用下列指令,檢查 Bazel 是否正常運作:

bazel info workspace

如果 Bazel 列印目前目錄的路徑,就表示一切正常!如果 WORKSPACE檔案不存在,系統可能會顯示類似以下的錯誤訊息:

ERROR: The 'info' command is only supported from within a workspace.

與 Android SDK 整合

Bazel 需要執行 Android SDK 建構工具來建構應用程式。因此,您需要在 WORKSPACE 檔案中新增一些資訊,讓 Bazel 知道這些工具的位置。

WORKSPACE 檔案中新增下列程式碼:

android_sdk_repository(name = "androidsdk")

這會使用 ANDROID_HOME 環境變數參照路徑中的 Android SDK,並自動偵測該位置安裝的最高 API 級別和最新版建構工具。

您可以將 ANDROID_HOME 變數設為 Android SDK 的位置。使用 Android Studio 的 SDK Manager 找出已安裝 SDK 的路徑。假設 SDK 安裝在預設位置,您可以使用下列指令設定 ANDROID_HOME 變數:

作業系統 指令
Linux export ANDROID_HOME=$HOME/Android/Sdk/
macOS export ANDROID_HOME=$HOME/Library/Android/sdk
Windows (命令提示字元) set ANDROID_HOME=%LOCALAPPDATA%\Android\Sdk
Windows (PowerShell) $env:ANDROID_HOME="$env:LOCALAPPDATA\Android\Sdk"

上述指令只會為目前的殼層工作階段設定變數。如要永久啟用這些設定,請執行下列指令:

作業系統 指令
Linux echo "export ANDROID_HOME=$HOME/Android/Sdk/" >> ~/.bashrc
macOS echo "export ANDROID_HOME=$HOME/Library/Android/Sdk/" >> ~/.bashrc
Windows (命令提示字元) setx ANDROID_HOME "%LOCALAPPDATA%\Android\Sdk"
Windows (PowerShell) [System.Environment]::SetEnvironmentVariable('ANDROID_HOME', "$env:LOCALAPPDATA\Android\Sdk", [System.EnvironmentVariableTarget]::User)

您也可以加入 pathapi_levelbuild_tools_version 屬性,明確指定 Android SDK 的絕對路徑、API 級別和要使用的建構工具版本。如果未指定 api_levelbuild_tools_versionandroid_sdk_repository 規則會使用 SDK 中可用的最新版本。只要 SDK 中有這些屬性,您就可以指定任何組合,例如:

android_sdk_repository(
    name = "androidsdk",
    path = "/path/to/Android/sdk",
    api_level = 25,
    build_tools_version = "30.0.3"
)

在 Windows 上,請注意 path 屬性必須使用混合樣式的路徑,也就是含有正斜線的 Windows 路徑:

android_sdk_repository(
    name = "androidsdk",
    path = "c:/path/to/Android/sdk",
)

選用:如要將原生程式碼編譯至 Android 應用程式,您也需要下載 Android NDK,並在 WORKSPACE 檔案中加入下列程式碼,告知 Bazel NDK 的位置:

android_ndk_repository(name = "androidndk")

android_sdk_repository 類似,Android NDK 的路徑預設會從 ANDROID_NDK_HOME 環境變數推斷而來。您也可以在 android_ndk_repository 上使用 path 屬性,明確指定路徑。

詳情請參閱「透過 Bazel 使用 Android Native Development Kit」。

api_level 是 SDK 和 NDK 指定的 Android API 版本,例如 Android 6.0 為 23,Android 7.1 為 25。如果未明確設定,api_level 預設會是 android_sdk_repositoryandroid_ndk_repository 可用的最高 API 級別。

SDK 和 NDK 的 API 級別不必設為相同值。 這個頁面包含 Android 版本與 NDK 支援 API 級別的對應關係。

建立 BUILD 檔案

BUILD 檔案會說明一組建構輸出內容 (例如來自 aapt 的已編譯 Android 資源,或來自 javac 的類別檔案) 及其依附元件之間的關係。這些依附元件可能是工作區中的來源檔案 (Java、C++) 或其他建構輸出內容。BUILD 檔案是以 Starlark 語言編寫。

BUILD 檔案是 Bazel 中稱為「套件階層」的概念之一。套件階層是邏輯結構,會覆蓋工作區中的目錄結構。每個「套件」都是目錄 (和子目錄),內含一組相關的來源檔案和 BUILD 檔案。套件也包含任何子目錄,但含有專屬 BUILD 檔案的子目錄除外。套件名稱是相對於 WORKSPACEBUILD 檔案路徑。

請注意,Bazel 的套件階層在概念上與 Android 應用程式目錄的 Java 套件階層不同 (BUILD 檔案位於該目錄中),但目錄的整理方式可能相同。

在本教學課程中,簡單的 Android 應用程式的來源檔案包含單一 Bazel 套件。src/main/較複雜的專案可能會有許多巢狀封裝。

新增 android_library 規則

BUILD 檔案包含 Bazel 的幾種不同型別宣告。最重要的類型是建構規則,可告知 Bazel 如何從一組來源檔案或其他依附元件建構中繼或最終軟體輸出內容。Bazel 提供兩種建構規則:android_libraryandroid_binary,可用於建構 Android 應用程式。

在本教學課程中,您會先使用 android_library 規則,告知 Bazel 從應用程式原始碼和資源檔案建構 Android 程式庫模組。接著,您會使用 android_binary 規則,告知 Bazel 如何建構 Android 應用程式套件。

src/main/java/com/example/bazel 目錄中建立新的 BUILD 檔案,然後宣告新的 android_library 目標:

src/main/java/com/example/bazel/BUILD

package(
    default_visibility = ["//src:__subpackages__"],
)

android_library(
    name = "greeter_activity",
    srcs = [
        "Greeter.java",
        "MainActivity.java",
    ],
    manifest = "AndroidManifest.xml",
    resource_files = glob(["res/**"]),
)

android_library 建構規則包含一組屬性,可指定 Bazel 從來源檔案建構程式庫模組時所需的資訊。另請注意,規則名稱為 greeter_activity。您會在 android_binary 規則中,使用這個名稱做為依附元件,參照該規則。

新增 android_binary 規則

android_binary 規則會為您的應用程式建構 Android 應用程式套件 (.apk 檔案)。

src/main/ 目錄中建立新的 BUILD 檔案,然後宣告新的 android_binary 目標:

src/main/BUILD

android_binary(
    name = "app",
    manifest = "AndroidManifest.xml",
    deps = ["//src/main/java/com/example/bazel:greeter_activity"],
)

這裡的 deps 屬性會參照您在上述 BUILD 檔案中新增的 greeter_activity 規則輸出內容。也就是說,當 Bazel 建構這項規則的輸出內容時,會先檢查greeter_activity程式庫規則的輸出內容是否已建構且為最新版本。如果沒有,Bazel 會建構該檔案,然後使用該輸出內容建構應用程式套件檔案。

現在請儲存並關閉檔案。

建構應用程式

請嘗試建構應用程式!執行下列指令來建構 android_binary 目標:

bazel build //src/main:app

build 子指令會指示 Bazel 建構後續的目標。目標是在 BUILD 檔案中指定為建構規則的名稱,以及相對於工作區目錄的套件路徑。在本例中,目標為 app,而套件路徑為 //src/main/

請注意,有時可以省略套件路徑或目標名稱,視指令列的目前工作目錄和目標名稱而定。如要進一步瞭解目標標籤和路徑,請參閱「標籤」一文。

Bazel 會開始建構範例應用程式。建構期間,輸出內容會類似下列內容:

INFO: Analysed target //src/main:app (0 packages loaded, 0 targets configured).
INFO: Found 1 target...
Target //src/main:app up-to-date:
  bazel-bin/src/main/app_deploy.jar
  bazel-bin/src/main/app_unsigned.apk
  bazel-bin/src/main/app.apk

找出建構輸出內容

Bazel 會將中繼和最終建構作業的輸出內容,放在一組使用者和工作區專屬的輸出目錄中。這些目錄是從專案目錄頂層的下列位置進行符號連結,其中 WORKSPACE 是:

  • bazel-bin 儲存二進位可執行檔和其他可執行的建構輸出內容
  • bazel-genfiles 儲存 Bazel 規則產生的中介來源檔案
  • bazel-out 會儲存其他類型的建構輸出內容

Bazel 會將使用 android_binary 規則產生的 Android .apk 檔案儲存在 bazel-bin/src/main 目錄中,其中子目錄名稱 src/main 是從 Bazel 套件名稱衍生而來。

在命令提示字元中,列出這個目錄的內容,並找出 app.apk 檔案:

作業系統 指令
Linux、macOS ls bazel-bin/src/main
Windows (命令提示字元) dir bazel-bin\src\main
Windows (PowerShell) ls bazel-bin\src\main

執行應用程式

現在您可以使用 bazel mobile-install 指令,透過指令列將應用程式部署至已連線的 Android 裝置或模擬器。這項指令會使用 Android Debug Bridge (adb) 與裝置通訊。您必須先按照「Android Debug Bridge」一文的說明設定裝置,才能使用 adb 進行部署。您也可以選擇在 Android Studio 內建的 Android 模擬器上安裝應用程式。請務必先執行模擬器,再執行下列指令。

輸入下列指令:

bazel mobile-install //src/main:app

接著,找出並啟動「Bazel Tutorial App」:

Bazel 教學課程應用程式

圖 2. Bazel 教學課程應用程式。

恭喜!您剛才安裝了第一個以 Bazel 建構的 Android 應用程式。

請注意,mobile-install 子指令也支援 --incremental 標記,可用於只部署自上次部署以來變更的應用程式部分。

此外,這個工具也支援 --start_app 旗標,可在安裝應用程式後立即啟動。

延伸閱讀

詳情請參閱下列頁面:

祝您建構愉快!