在 Windows 上使用 Bazel

回報問題 查看原始碼 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

本頁面說明在 Windows 上使用 Bazel 的最佳做法。如需安裝操作說明，請參閱「在 Windows 上安裝 Bazel」。

已知問題

在 GitHub 上，Windows 相關的 Bazel 問題會標示為「team-Windows」標籤。您可以在這裡查看待解決的問題。

最佳做法

避免長路徑問題

部分工具在 Windows 上有路徑長度上限限制，包括 MSVC 編譯器。為避免發生這個問題，您可以使用 --output_user_root 標記，為 Bazel 指定短輸出目錄。

例如，在 bazelrc 檔案中加入下列程式碼行：

startup --output_user_root=C:/tmp

啟用 8.3 檔案名稱支援功能

Bazel 會嘗試為長檔案路徑建立簡稱版本。不過，您必須為長路徑檔案所在的磁碟區啟用 8.3 檔案名稱支援功能，才能執行這項操作。您可以執行下列指令，在所有磁碟分割區中啟用 8.3 名稱建立功能：

fsutil 8dot3name set 0

某些功能需要 Bazel 能夠在 Windows 上建立檔案符號連結，方法是啟用開發人員模式 (在 Windows 10 1703 以上版本)，或以系統管理員身分執行 Bazel。這麼做可啟用下列功能：

為簡化操作，請在 bazelrc 檔案中加入下列程式碼行：

startup --windows_enable_symlinks
build --enable_runfiles

注意：在 Windows 上建立符號連結的作業成本高昂。--enable_runfiles 標記可能會建立大量檔案符號連結。請只在需要時啟用這項功能。

執行 Bazel：MSYS2 殼層與命令提示字元與 PowerShell

建議：請透過命令提示字元 (cmd.exe) 或 PowerShell 執行 Bazel。

自 2020 年 1 月 15 日起，請勿從 bash 執行 Bazel，包括從 MSYS2 shell、Git Bash、Cygwin 或任何其他 Bash 變體執行。雖然 Bazel 可能適用於大多數用途，但有些功能無法正常運作，例如使用 MSYS2 的 Ctrl+C 中斷建構作業。此外，如果您選擇在 MSYS2 下執行，則必須停用 MSYS2 的自動路徑轉換功能，否則 MSYS 會將「類似」Unix 路徑的命令列引數 (例如 //foo:bar) 轉換為 Windows 路徑。詳情請參閱 這個 Stack Overflow 解答。

在沒有 Bash 的情況下使用 Bazel (MSYS2)

在沒有 Bash 的情況下使用 bazel 建構

1.0 之前的 Bazel 版本需要使用 Bash 建構部分規則。

從 Bazel 1.0 開始，您可以不使用 Bash 建構任何規則，除非是：

  • genrule，因為 genrules 會執行 Bash 指令
  • sh_binary 或 sh_test 規則，因為這兩者本質上需要 Bash
  • 使用 ctx.actions.run_shell() 或 ctx.resolve_command() 的 Starlark 規則

不過，genrule 通常用於簡單的工作，例如複製檔案或寫入文字檔案。您可以改用 genrule (並依賴 Bash)，或在 bazel-skylib 存放區中尋找合適的規則。在 Windows 上建構時，這些規則不需要 Bash。

在沒有 Bash 的情況下使用 Bazel 測試

1.0 之前的 Bazel 版本需要使用 Bash bazel test 執行任何操作。

從 Bazel 1.0 開始，您可以不使用 Bash 測試任何規則，但以下情況除外：

  • 您使用 --run_under
  • 測試規則本身需要 Bash (因為其可執行檔為 Shell 指令碼)

在不使用 Bash 的情況下使用 bazel run

1.0 之前的 Bazel 版本需要使用 Bash bazel run 執行任何操作。

從 Bazel 1.0 開始，您可以不使用 Bash 執行任何規則，但以下情況除外：

  • 您使用 --run_under 或 --script_path
  • 測試規則本身需要 Bash (因為其可執行檔為 Shell 指令碼)

使用 shbinary 和 sh* 規則，以及不含 Bash 的 ctx.actions.run_shell()

您需要使用 Bash 建構及測試 sh_* 規則，以及建構及測試使用 ctx.actions.run_shell() 和 ctx.resolve_command() 的 Starlark 規則。這項功能不僅適用於專案中的規則，也適用於專案依附的任何外部存放區中的規則 (甚至是間接依附的規則)。

日後可能會提供使用適用於 Linux 的 Windows 子系統 (WSL) 建構這些規則的選項，但目前這並非 Bazel-on-Windows 子團隊的優先事項。

設定環境變數

您在 Windows 指令提示 (cmd.exe) 中設定的環境變數，只會在該指令提示工作階段中設定。如果您啟動新的 cmd.exe，就必須再次設定變數。如要一律在 cmd.exe 啟動時設定變數，您可以將這些變數新增至 Control Panel > System Properties > Advanced > Environment Variables... 對話方塊中的「使用者變數」或「系統變數」。

在 Windows 上建構

使用 MSVC 建構 C++

如要使用 MSVC 建構 C++ 目標，您需要：

  • Visual C++ 編譯器。

  • (選用) BAZEL_VC 和 BAZEL_VC_FULL_VERSION 環境變數。

    Bazel 會自動偵測系統上的 Visual C++ 編譯器。如要告知 Bazel 使用特定的 VC 安裝，您可以設定下列環境變數：

    針對 Visual Studio 2017 和 2019，請設定 BAZEL_VC 之一。此外，您也可以設定 BAZEL_VC_FULL_VERSION。

    • BAZEL_VC Visual C++ Build Tools 安裝目錄

      set BAZEL_VC=C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC

    • BAZEL_VC_FULL_VERSION (選用) 僅適用於 Visual Studio 2017 和 2019，Visual C++ Build Tools 的完整版本號碼。如果安裝了多個版本的 Visual C++ Build Tools，您可以透過 BAZEL_VC_FULL_VERSION 選擇確切的版本，否則 Bazel 會選擇最新版本。

      set BAZEL_VC_FULL_VERSION=14.16.27023

    如果是 Visual Studio 2015 或更舊版本，請設定 BAZEL_VC。(系統不支援 BAZEL_VC_FULL_VERSION)。

    • BAZEL_VC Visual C++ Build Tools 安裝目錄

      set BAZEL_VC=C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC

  • Windows SDK。

    Windows SDK 包含建構 Windows 應用程式 (包括 Bazel 本身) 時所需的標頭檔案和程式庫。根據預設，系統會使用已安裝的最新 Windows SDK。您也可以設定 BAZEL_WINSDK_FULL_VERSION 來指定 Windows SDK 版本。您可以使用完整的 Windows 10 SDK 編號，例如 10.0.10240.0，也可以指定 8.1 來使用 Windows 8.1 SDK (只有一個版本的 Windows 8.1 SDK 可供使用)。請確認您已安裝指定的 Windows SDK。

    需求條件：VC 2017 和 2019 支援此功能。獨立的 VC 2015 建構工具不支援選取 Windows SDK，您必須安裝完整的 Visual Studio 2015，否則 BAZEL_WINSDK_FULL_VERSION 會遭到忽略。

    set BAZEL_WINSDK_FULL_VERSION=10.0.10240.0

如果一切設定都完成，您現在就可以建構 C++ 目標了！

請嘗試使用其中一個範例專案建構目標：

bazel build //examples/cpp:hello-world
bazel-bin\examples\cpp\hello-world.exe

根據預設，建構的二進位檔會指定 x64 架構。如要指定不同的目標架構，請為目標架構設定 --cpu 建構選項： * x64 (預設)：--cpu=x64_windows 或無選項 * x86：--cpu=x64_x86_windows * ARM：--cpu=x64_arm_windows * ARM64：--cpu=arm64_windows

舉例來說，如要建構 ARM 架構的目標，請執行：

bazel build //examples/cpp:hello-world --cpu=x64_arm_windows

如要建構及使用動態連結程式庫 (DLL 檔案)，請參閱這個範例。

指令列長度限制：如要避免 Windows 指令列長度限制問題，請透過 --features=compiler_param_file 啟用編譯器參數檔案功能。

使用 Clang 建構 C++

從 0.29.0 開始，Bazel 支援使用 LLVM 的 MSVC 相容編譯器驅動程式 (clang-cl.exe) 進行建構作業。

需求條件：如要使用 Clang 進行建構，您必須同時安裝 LLVM 和 Visual C++ 建構工具，因為即使您使用 clang-cl.exe 做為編譯器，仍需連結至 Visual C++ 程式庫。

Bazel 可自動偵測系統上的 LLVM 安裝作業，您也可以透過 BAZEL_LLVM 明確告知 Bazel LLVM 的安裝位置。

  • BAZEL_LLVM LLVM 安裝目錄

    set BAZEL_LLVM=C:\Program Files\LLVM

如要啟用 Clang 工具鍊來建構 C++，有幾種情況。

  • 在 bazel 0.28 以下版本中：不支援 Clang。

  • 沒有 --incompatible_enable_cc_toolchain_resolution：您可以透過建構標記 --compiler=clang-cl 啟用 Clang 工具鍊。

  • 使用 --incompatible_enable_cc_toolchain_resolution：您必須在 BUILD file (例如頂層 BUILD 檔案) 中新增平台目標：

    platform(
    name = "x64_windows-clang-cl",
    constraint_values = [
        "@platforms//cpu:x86_64",
        "@platforms//os:windows",
        "@bazel_tools//tools/cpp:clang-cl",
    ],
)

    接著，您可以透過下列任一方式啟用 Clang 工具鍊：

    • 指定下列建構標記：
    --extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows-clang-cl --extra_execution_platforms=//:x64_windows-clang-cl
    • 在 MODULE.bazel 檔案中註冊平台和工具鍊：
    register_execution_platforms(
    ":x64_windows-clang-cl"
)

register_toolchains(
    "@local_config_cc//:cc-toolchain-x64_windows-clang-cl",
)

    --incompatible_enable_cc_toolchain_resolution 標記預計會在日後的 Bazel 版本中預設啟用。因此，建議您使用第二種方法啟用 Clang 支援功能。

建構 Java

如要建構 Java 目標，您需要：

在 Windows 上，Bazel 會為 java_binary 規則建構兩個輸出檔案：

  • .jar 檔案
  • 可設定 JVM 環境並執行二進位檔的 .exe 檔案

請嘗試使用其中一個範例專案建構目標：

  bazel build //examples/java-native/src/main/java/com/example/myproject:hello-world
  bazel-bin\examples\java-native\src\main\java\com\example\myproject\hello-world.exe

建構 Python

如要建構 Python 目標，您需要：

在 Windows 上，Bazel 會為 py_binary 規則建構兩個輸出檔案：

  • 自我解壓縮的 ZIP 檔案
  • 可執行檔案，可啟動 Python 轉譯器，並將自解壓縮檔案做為引數

您可以執行可執行檔案 (具有 .exe 副檔名)，也可以將自解壓縮檔案做為引數，執行 Python。

請嘗試使用其中一個範例專案建構目標：

  bazel build //examples/py_native:bin
  bazel-bin\examples\py_native\bin.exe
  python bazel-bin\examples\py_native\bin.zip

如想進一步瞭解 Bazel 如何在 Windows 上建構 Python 目標，請參閱這份設計文件。