在 Windows 上使用 Bazel

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

已知問題

GitHub 上標示「area-Windows」標籤的 Bazel 問題都與 Windows 相關。 GitHub-Windows。

最佳做法

避免路徑過長的問題

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

舉例來說，在 bazelrc 檔案中新增下列程式碼：

startup --output_user_root=C:/tmp

啟用符號連結支援

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

• --windows_enable_symlinks
• --enable_runfiles

為簡化作業，請在 bazelrc 檔案中新增下列程式碼：

startup --windows_enable_symlinks

build --enable_runfiles

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

執行 Bazel：MSYS2 Shell、命令提示字元或 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 路徑。詳情請參閱這篇 StackOverflow 回答。

不使用 Bash (MSYS2) 的 Bazel

在沒有 Bash 的情況下使用 bazel build

在 1.0 之前的 Bazel 版本中，建構某些規則需要 Bash。

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

• genrule，因為 genrule 會執行 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 (因為其可執行檔是殼層指令碼)

使用 bazel run (不含 Bash)

1.0 之前的 Bazel 版本需要 Bash 才能執行任何作業。bazel run

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

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

使用 sh_binary 和 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 啟動時一律設定變數，可以將變數新增至「User variables」(使用者變數) 或「System variables」(系統變數) 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 的完整版本號碼。如果安裝了多個版本，可以透過 BAZEL_VC_FULL_VERSION 選擇確切的 Visual C++ Build Tools 版本，否則 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 架構為目標。如要建構 ARM64 架構，請使用

--platforms=//:windows_arm64  --extra_toolchains=@local_config_cc//:cc-toolchain-arm64_windows

你可以在 MODULE.bazel 中使用 @local_config_cc，方法如下：

bazel_dep(name = "rules_cc", version = "0.1.1")
cc_configure = use_extension("@rules_cc//cc:extensions.bzl", "cc_configure_extension")
use_repo(cc_configure, "local_config_cc")

如要建構及使用動態連結程式庫 (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 工具鍊，設定方式取決於 Bazel 版本，以及您是否使用 Bzlmod 或 WORKSPACE。

Bazel 8 以上版本：

• 使用 Bzlmod (建議)：

  1. 請確保您已在 MODULE.bazel 中載入 rules_cc，並設定 CC 工具鍊： ```python bazel_dep(name = "rules_cc", version = "0.0.17") # Or newer

     cc_configure = use_extension("@rules_cc//cc:extensions.bzl", "cc_configure_extension") use_repo(cc_configure, "local_config_cc") ```

  2. 在 BUILD 檔案 (例如根 BUILD 檔案) 中定義 platform 目標： python platform( name = "x64_windows-clang-cl", constraint_values = [ "@platforms//cpu:x86_64", "@platforms//os:windows", "@bazel_tools//tools/cpp:clang-cl", # Alias to the @rules_cc constraint in Bazel 8+ ], )

  3. 使用下列標記啟用工具鍊： bash --extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows-clang-cl --extra_execution_platforms=//:x64_windows-clang-cl

• 使用 WORKSPACE：

  1. 在 WORKSPACE 檔案中載入 rules_cc 依附元件和工具鍊： python load("@rules_cc//cc:repositories.bzl", "rules_cc_dependencies", "rules_cc_toolchains") rules_cc_dependencies() rules_cc_toolchains()

  2. 在 BUILD 檔案 (例如根 BUILD 檔案) 中定義 platform 目標： python platform( name = "x64_windows-clang-cl", constraint_values = [ "@platforms//cpu:x86_64", "@platforms//os:windows", "@bazel_tools//tools/cpp:clang-cl", # Alias to the @rules_cc constraint in Bazel 8+ ], )

  3. 使用下列標記啟用工具鍊： bash --extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows-clang-cl --extra_execution_platforms=//:x64_windows-clang-cl

Bazel 7：

注意：在 Bazel 7 中，@bazel_tools//tools/cpp:clang-cl「不是」@rules_cc 限制的別名。如要在 Bazel 7 中正確使用 clang-cl 和 rules_cc，您必須參照 @rules_cc 存放區中的限制。從技術上來說，標籤 @rules_cc//cc/private/toolchain:clang-cl 是私人的，但為了確保 Bazel 7 中 WORKSPACE 和 Bzlmod 設定的行為一致，這個標籤是必要的。

• 使用 Bzlmod：

  1. 如 Bazel 8 範例所示，設定 MODULE.bazel。

  2. 使用 @rules_cc 私人限制定義 platform 目標： python platform( name = "x64_windows-clang-cl", constraint_values = [ "@platforms//cpu:x86_64", "@platforms//os:windows", "@rules_cc//cc/private/toolchain:clang-cl", # Necessary for Bazel 7 ], )

  3. 使用下列標記啟用工具鍊： bash --extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows-clang-cl --extra_execution_platforms=//:x64_windows-clang-cl

• 使用 WORKSPACE：

  1. 在 WORKSPACE 檔案中載入 rules_cc 依附元件和工具鍊： python load("@rules_cc//cc:repositories.bzl", "rules_cc_dependencies", "rules_cc_toolchains") rules_cc_dependencies() rules_cc_toolchains()

  2. 使用 @rules_cc 私人限制定義 platform 目標： python platform( name = "x64_windows-clang-cl", constraint_values = [ "@platforms//cpu:x86_64", "@platforms//os:windows", "@rules_cc//cc/private/toolchain:clang-cl", # Necessary for Bazel 7 ], )

  3. 使用下列標記啟用工具鍊： bash --extra_toolchains=@local_config_cc//:cc-toolchain-x64_windows-clang-cl --extra_execution_platforms=//:x64_windows-clang-cl

Bazel 0.29 至 6.x：

• 透過建構旗標 --compiler=clang-cl 啟用 Clang 工具鍊。

• 如果建構作業將標記 --incompatible_enable_cc_toolchain_resolution 設為 true，請使用 Bazel 7.0.0 的方法。

Bazel 0.28 和更舊版本：

• 不支援 Clang。

建構 Java

如要建構 Java 目標，請備妥下列項目：

• Java SE 開發套件

在 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 目標，您需要：

• Python 解譯器

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

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

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

請嘗試從我們的範例專案建構目標：

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

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