在本機上成功的 Bazel 建構作業,在遠端執行時可能會失敗,因為不影響本機建構作業的限制和要求。有關這類故障的最常見原因,請參閱調整 Remote Execution 的 Bazel 規則。
本頁說明如何使用 Docker 沙箱功能,找出並解決遠端執行作業時最常發生的問題。此功能會對建構作業施加與遠端執行作業相同的限制。這樣一來,您就能排除建構問題,而無需使用遠端執行服務。
Docker 沙箱功能會模擬遠端執行的限制,如下所示:
建構動作在工具鍊容器中執行。您可以使用相同的工具鍊容器,透過支援容器化遠端執行作業的服務,在本機和遠端執行建構作業。
沒有任何多餘的資料超出容器邊界。只有明確宣告的輸入和輸出內容才會進入並離開容器,而且只有在相關聯的建構動作成功完成後才會進入容器。
每個動作都會在新的容器中執行。系統會為每個產生的建構動作建立新的不重複容器。
您可以使用下列其中一種方法排解這些問題:
原生疑難排解。使用此方法時,Bazel 及其建構動作會在本機電腦中以原生方式執行。Docker 沙箱功能對建構作業設有與遠端執行同等的限制。不過,此方法不會偵測進入建構作業的本機工具、狀態和資料外洩,而這會導致遠端執行發生問題。
排解 Docker 容器中的問題。使用這種方法時,Bazel 及其建構動作會在 Docker 容器中執行,讓您能夠偵測從本機電腦流入建構作業的工具、狀態和資料,並且強制執行與遠端執行作業相同的限制。即使部分建構作業失敗,這個方法仍可提供建構作業的深入分析資訊。這個方法屬於實驗性質,並未獲得官方支援。
必要條件
開始排解問題前,請先完成下列步驟 (如果尚未完成):
- 安裝 Docker 並設定執行所需的權限。
- 安裝 Bazel 0.14.1 以上版本。較舊版本不支援 Docker 沙箱功能。
- 按照這個頁面所述,將固定在最新版本中的 bazel-toolchains 存放區新增至建構作業的
WORKSPACE
檔案。 - 在
.bazelrc
檔案中新增標記以啟用這項功能。如果檔案不存在,請在 Bazel 專案的根目錄中建立該檔案。以下標記是參考範例。請參閱 bazel-toolchains 存放區中的最新.bazelrc
檔案,並複製其中定義的設定檔docker-sandbox
旗標值。
# Docker Sandbox Mode
build:docker-sandbox --host_javabase=<...>
build:docker-sandbox --javabase=<...>
build:docker-sandbox --crosstool_top=<...>
build:docker-sandbox --experimental_docker_image=<...>
build:docker-sandbox --spawn_strategy=docker --strategy=Javac=docker --genrule_strategy=docker
build:docker-sandbox --define=EXECUTOR=remote
build:docker-sandbox --experimental_docker_verbose
build:docker-sandbox --experimental_enable_docker_sandbox
如果您的規則需要其他工具,請執行下列操作:
使用 Dockerfile 安裝工具,並在本機建構映像檔,藉此建立自訂 Docker 容器。
將上述
--experimental_docker_image
標記的值替換為自訂容器映像檔的名稱。
原生疑難排解
這個方法會直接在本機電腦上執行 Bazel 和所有建構動作,是確認遠端執行作業是否成功的安全方法。
不過,使用這個方法時,本機安裝的工具、二進位檔和資料可能會洩漏到建構作業中,尤其是在使用設定樣式的 WORKSPACE 規則時。此類外洩將導致遠端執行發生問題;如要偵測,除了原生疑難排解之外,也應在 Docker 容器中進行疑難排解。
步驟 1:執行版本
將
--config=docker-sandbox
標記新增至執行建構的 Bazel 指令。例如:bazel --bazelrc=.bazelrc build --config=docker-sandbox target
執行版本,然後等待建構完成。由於 Docker 沙箱功能,建構作業的執行速度最多會比平常慢四倍。
您可能會遇到下列錯誤:
ERROR: 'docker' is an invalid value for docker spawn strategy.
如果是這樣,請再次使用 --experimental_docker_verbose
標記執行建構作業。這個標記可啟用詳細的錯誤訊息。這個錯誤通常是因為 Docker 安裝錯誤,或是在目前使用者帳戶下執行 Docker 時缺少權限。詳情請參閱 Docker 說明文件。如果問題仍未解決,請直接跳到「在 Docker 容器中疑難排解」一節。
步驟 2:解決系統偵測到的問題
以下是最常見的問題及解決方法。
Bazel 執行檔案樹狀結構參照的檔案、工具、二進位檔或資源消失了。確認受影響目標的所有依附元件均已明確宣告。詳情請參閱「管理隱含依附元件」一文。
缺少絕對路徑或
PATH
變數參照的檔案、工具、二進位檔或資源。確認已在工具鍊容器中安裝所有必要工具,並使用工具鍊規則,以正確宣告指向缺少資源的依附元件。詳情請參閱透過工具鍊規則叫用建構工具。二進位檔執行失敗。其中一個建構規則參照的二進位檔與執行環境 (Docker 容器) 不相容。詳情請參閱管理平台相依的二進位檔。如果無法解決問題,請與 bazel-discuss@google.com 聯絡尋求協助。
「
@local-jdk
」中的某個檔案遺失或導致錯誤。您本機電腦上的 Java 二進位檔外洩到建構作業中,但與建構作業不相容。請在規則和目標中使用java_toolchain
,而非@local_jdk
。如需進一步協助,請聯絡 bazel-discuss@google.com。其他錯誤。如需協助,請與 bazel-discuss@google.com 聯絡。
在 Docker 容器中排解問題
透過此方法,Bazel 會在主機 Docker 容器中執行,而 Bazel 的建構動作會在 Docker 沙箱功能產生的個別工具鍊容器中執行。沙箱會為每個建構動作產生全新的工具鍊容器,每個工具鍊容器中也只會執行一個動作。
這種方法可讓您更精細地控管主機環境中安裝的工具。只要將建構作業的執行作業與建構動作的執行作業分開,並將安裝的工具數量降到最低,您就能驗證建構作業是否在本機執行環境中具有任何依附元件。
步驟 1:建構容器
建立
Dockerfile
,以便建立 Docker 容器,並安裝 Bazel 和最少的建構工具:FROM debian:stretch RUN apt-get update && apt-get install -y apt-transport-https curl software-properties-common git gcc gnupg2 g++ openjdk-8-jdk-headless python-dev zip wget vim RUN curl -fsSL https://download.docker.com/linux/debian/gpg | apt-key add - RUN add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" RUN apt-get update && apt-get install -y docker-ce RUN wget https://releases.bazel.build/<latest Bazel version>/release/bazel-<latest Bazel version>-installer-linux-x86_64.sh -O ./bazel-installer.sh && chmod 755 ./bazel-installer.sh RUN ./bazel-installer.sh
以
bazel_container
建構容器:docker build -t bazel_container - < Dockerfile
步驟 2:啟動容器
使用以下顯示的指令啟動 Docker 容器。在該指令中,以您要建構的主機原始碼取代路徑。
docker run -it \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /tmp:/tmp \
-v your source code directory:/src \
-w /src \
bazel_container \
/bin/bash
這個指令會讓容器以 root 的身分執行,對應 Docker 通訊端,並掛接 /tmp
目錄。這樣一來,Bazel 就能產生其他 Docker 容器,並使用 /tmp
下的目錄,與這些容器共用檔案。您可以在容器內的 /src
取得原始碼。
這個指令刻意從 debian:stretch
基本容器開始,這個容器包含與用於工具鏈容器的 rbe-ubuntu16-04
容器不相容的二進位檔。如果本機環境的二進位檔外洩到工具鏈容器中,就會導致建構錯誤。
步驟 3:測試容器
從 Docker 容器中執行下列指令來進行測試:
docker ps
bazel version
步驟 4:執行版本
如下所示執行建構。輸出使用者為 root,因此會對應至可透過相同絕對路徑存取的目錄,包括 Bazel 執行所在的主機容器、Docker 沙箱功能產生的工具鏈容器 (其中執行 Bazel 的建構動作),以及主機和動作容器執行所在的本機。
bazel --output_user_root=/tmp/bazel_docker_root --bazelrc=.bazelrc \ build --config=docker-sandbox target
步驟 5:解決系統偵測到的問題
您可以按照下列步驟解決建構失敗問題:
如果建構作業因「磁碟空間不足」錯誤而失敗,您可以使用標記
--memory=XX
啟動主機容器,藉此提高此限制,其中XX
是分配的磁碟空間 (以 GB 為單位)。這項功能仍在實驗階段,可能會導致無法預測的行為。如果在分析或載入階段中建構失敗,表示 WORKSPACE 檔案中宣告的一或多個建構規則與遠端執行作業不相容。如要瞭解可能原因和解決方法,請參閱調整 Remote Execution 的 Bazel 規則。
如因其他原因導致建構失敗,請參閱步驟 2:解決偵測到的問題中的疑難排解步驟。