C / C++ 規則

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

規則

cc_binary

查看規則來源 
cc_binary(name, deps, srcs, data, additional_linker_inputs, args, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, dynamic_deps, env, exec_compatible_with, exec_properties, features, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local_defines, malloc, module_interfaces, nocopts, output_licenses, reexport_deps, restricted_to, stamp, tags, target_compatible_with, testonly, toolchains, visibility, win_def_file)

產生可執行的二進位檔。


目標的 name 應與應用程式主要進入點的來源檔案名稱相同 (不含副檔名)。舉例來說，如果您在 main.cc 中設定了進入點，則名稱應為 main。

隱含輸出目標

  • name.stripped (僅在明確要求時建構)：經過精簡的二進位檔版本。strip -g 會在二進位檔上執行，以移除偵錯符號。您可以使用 --stripopt=-foo 在指令列上提供其他去除選項。
  • name.dwp (僅在明確要求時才建構)：如果已啟用 Fission：偵錯資訊套件檔案，適合用於偵錯遠端部署的二進位檔。否則：空白檔案。

引數

屬性
name

名稱；必填

這個目標的專屬名稱。
deps

標籤清單；預設為 []

要連結至二進位目標的其他程式庫清單。

這些可以是 cc_library 或 objc_library 目標。

您也可以將連結器指令碼 (.lds) 放入依附元件，並在 linkopts 中參照這些指令碼。
srcs

標籤清單；預設為 []

用來建立程式庫目標的 C 和 C++ 檔案清單。這些是 C/C++ 來源和標頭檔案，可能是未產生的 (一般來源程式碼) 或已產生的。

系統會編譯所有 .cc、.c 和 .cpp 檔案。這些檔案可能是產生的檔案：如果某個已命名的檔案位於其他規則的 outs 中，這個 cc_library 就會自動依附該規則。

純粹的彙整器檔案 (.s、.asm) 不會經過預先處理，通常會使用彙整器建構。經過預處理的彙整檔案 (.S) 會經過預處理，並通常使用 C/C++ 編譯器建構。

系統不會編譯 .h 檔案，但可供此規則中的來源加入。.cc 和 .h 檔案都能直接納入這些 srcs 或此規則的 hdrs 中列出的標頭，或是 deps 引數中列出的任何規則。

所有已 #include 檔案都必須在這個或參照的 cc_library 規則的 hdrs 屬性中提及，如果這些檔案是此程式庫的私人檔案，則應列在 srcs 中。詳情請參閱「"標頭包含檢查"。

.so、.lo 和 .a 檔案是預先編譯的檔案。如果程式庫使用我們沒有原始碼的第三方程式碼，則可能會以 srcs 的形式顯示。

如果 srcs 屬性包含其他規則的標籤，cc_library 會使用該規則的輸出檔案做為來源檔案進行編譯。這項功能可用於一次性產生原始碼 (如果要經常使用，建議實作 Starlark 規則類別並使用 cc_common API)

允許的 srcs 檔案類型：

  • C 和 C++ 來源檔案：.c、.cc、.cpp、.cxx、.c++、.C
  • C 和 C++ 標頭檔案：.h、.hh、.hpp、.hxx、.inc、.inl、.H
  • 使用 C 前置處理器的組譯器：.S
  • 封存：.a、.pic.a
  • 「一律連結」程式庫：.lo、.pic.lo
  • 共用資料庫 (已分版本或未分版本)：.so、.so.version
  • 物件檔案：.o、.pic.o

... 以及產生這些檔案的任何規則 (例如 cc_embed_data)。 根據 gcc 慣例，不同的副檔名代表不同的程式設計語言。
data

標籤清單；預設為 []

這個程式庫在執行階段所需的檔案清單。如要查看 data 的一般註解，請參閱「大多數建構規則定義的常見屬性」。

如果 data 是產生檔案的名稱，則這個 cc_library 規則會自動依附產生規則。

如果 data 是規則名稱，則這個 cc_library 規則會自動依賴該規則，而該規則的 outs 會自動加入這個 cc_library 的資料檔案。

C++ 程式碼可以存取這些資料檔案，如下所示：


  const std::string path = devtools_build::GetDataDependencyFilepath(
      "my/test/data/file");
additional_linker_inputs

標籤清單；預設為 []

將這些檔案傳遞至 C++ 連結器指令。

例如，您可以在此提供已編譯的 Windows .res 檔案，以便嵌入二進位目標。
conlyopts

字串清單；預設為 []

將這些選項加入 C 編譯指令。適用於 "Make variable" 替換和 Bourne shell 符記化。
copts

字串清單；預設為 []

將這些選項加入 C/C++ 編譯指令。適用於 "Make variable" 替換和 Bourne shell 符記化。

這個屬性中的每個字串都會依照指定順序新增至 COPTS，然後再編譯二進位目標。標記只會影響編譯這個目標，而非其依附元件，因此請留意其他地方是否包含標頭檔案。所有路徑都應以工作區為基準，而非目前套件。在 third_party 以外的情況下，不應需要此屬性。

如果套件宣告功能 no_copts_tokenization，Bourne shell 符記化只會套用至由單一「Make」變數組成的字串。
cxxopts

字串清單；預設為 []

將這些選項新增至 C++ 編譯指令。適用於 "Make variable" 替換和 Bourne shell 符記化。
defines

字串清單；預設為 []

要新增至編譯行中的定義清單。適用於 "Make" 變數替換和 Bourne shell 符記化。每個字串都必須包含單一 Bourne 殼層符記，並在開頭加上 -D，然後新增至這個目標的編譯指令行，以及依附於該目標的每個規則。請務必謹慎操作，因為這可能會造成廣泛的影響。如有疑問，請改為將定義值新增至 local_defines。
dynamic_deps

標籤清單；預設為 []

這些是目前目標依附的其他 cc_shared_library 依附元件。

cc_shared_library 實作會使用 dynamic_deps 清單 (以傳遞方式，也就是目前目標 dynamic_deps 的 dynamic_deps) 決定哪些 cc_libraries 不應連結至傳遞 deps，因為這些 cc_libraries 已由其他 cc_shared_library 提供。
hdrs_check

字串；預設為 ""

已淘汰，無操作。
includes

字串清單；預設為 []

要新增至編譯行中的包含目錄清單。適用於 "Make 變數" 替換。每個字串都會加上套件路徑，並傳遞至 C++ 工具鍊，以便透過「include_paths」CROSSTOOL 功能進行展開。在 POSIX 系統上執行的工具鍊，如果含有一般功能定義，就會產生 -isystem path_to_package/include_entry。這項功能僅適用於不符合 Google 寫法風格的第三方程式庫 #include 陳述式。與 COPTS 不同的是，這些標記會新增至此規則和所有依附此規則的規則。(注意：不是依附的規則！)請務必謹慎操作，因為這可能會造成廣泛的影響。如有疑問，請改為在 COPTS 中加入「-I」標記。

新增的 include 路徑會包含產生的檔案，以及來源樹狀結構中的檔案。

標籤；預設為 "@bazel_tools//tools/cpp:link_extra_lib"

控制額外程式庫的連結。

根據預設，C++ 二進位檔會連結至 //tools/cpp:link_extra_lib，而 //tools/cpp:link_extra_lib 預設會依附標籤標記 //tools/cpp:link_extra_libs。如果未設定標記，這個程式庫預設為空白。設定標籤標記可連結選用依附元件，例如弱式符號的覆寫值、共用程式庫函式的攔截器，或特殊執行階段程式庫 (針對 malloc 替換，請優先使用 malloc 或 --custom_malloc)。將此屬性設為 None 會停用此行為。
linkopts

字串清單；預設為 []

將這些標記新增至 C++ 連結器指令。適用於 「Make」變數替換、 Bourne 殼層符記化和標籤展開。這個屬性中的每個字串都會在連結二進位目標之前新增至 LINKOPTS。

這個清單中每個元素的開頭不是 $ 或 -，系統會假設為 deps 中目標的標籤。該目標產生的檔案清單會附加至連結器選項。如果標籤無效，或未在 deps 中宣告，系統會回報錯誤。
linkshared

布林值；預設值為 False

建立共用程式庫。如要啟用這項屬性，請在規則中加入 linkshared=True。這個選項預設為關閉。

這個標記的存在表示連結會將 -shared 標記連結至 gcc，而產生的共用程式庫則適合載入至 Java 程式等。不過，為了建構目的，它永遠不會連結至依附的二進位檔，因為系統會假設使用 cc_binary 規則建構的共用程式庫只能由其他程式手動載入，因此不應視為 cc_library 規則的替代方案。為了提升可擴充性，建議您完全避免採用這種做法，而改為讓 java_library 依附 cc_library 規則。

如果您同時指定 linkopts=['-static'] 和 linkshared=True，您將獲得一個完全獨立的單元。如果您同時指定 linkstatic=True 和 linkshared=True，您會得到一個幾乎自給自足的單一單位。
linkstatic

布林值；預設值為 True

針對 cc_binary 和 cc_test：在靜態模式中連結二進位檔。如為 cc_library.link_static：請參閱下文。

根據預設，這個選項會為 cc_binary 開啟，其餘選項則為關閉。

如果已啟用，且這是二進位檔或測試，這個選項會指示建構工具盡可能連結 .a 而非 .so 的使用者程式庫。系統程式庫 (例如 libc，但不是 C/C++ 執行階段程式庫，請參閱下文) 仍會動態連結，沒有靜態資料庫的程式庫也是如此。因此產生的可執行檔仍會以動態方式連結，因此只有「大部分」是靜態的。

實際上有三種不同的方式可以連結可執行檔：

  • STATIC 搭配 fully_static_link 功能，其中所有項目都會以靜態方式連結，例如「gcc -static foo.o libbar.a libbaz.a -lm」。
    如要啟用這個模式，請在 features 屬性中指定 fully_static_link。
  • STATIC，其中所有使用者程式庫會以靜態方式連結 (如果有靜態版本)，但系統程式庫 (不含 C/C++ 執行階段程式庫) 會以動態方式連結，例如「gcc foo.o libfoo.a libbaz.a -lm」。
    如要啟用此模式，請指定 linkstatic=True。
  • DYNAMIC，所有程式庫都會動態連結 (如果有動態版本)，例如「gcc foo.o libfoo.so libbaz.so -lm」。
    如要啟用這個模式，請指定 linkstatic=False。

如果 features 中的 linkstatic 屬性或 fully_static_link 用於 //third_party 外，請在規則旁邊加入註解，說明原因。

如果 linkstatic 屬性用於 cc_library() 規則，其意義就會有所不同。對於 C++ 程式庫，linkstatic=True 表示只允許靜態連結，因此不會產生 .so。linkstatic=False 不會阻止建立靜態資料庫。這個屬性用於控制動態程式庫的建立作業。

在正式環境中，使用 linkstatic=False 建構的程式碼應極少。如果是 linkstatic=False，則建構工具會在 *.runfiles 區域中建立指向所依附共用程式庫的符號連結。
local_defines

字串清單；預設為 []

要新增至編譯行中的定義清單。適用於 "Make" 變數替換和 Bourne shell 符記化。每個字串都必須包含單一 Bourne 殼層符記，並在開頭加上 -D，然後新增至此目標的編譯指令行，但不新增至其依附項目。
malloc

標籤；預設為 "@bazel_tools//tools/cpp:malloc"

覆寫對 malloc 的預設依附元件。

根據預設，C++ 二進位檔會連結至 //tools/cpp:malloc，這是空白程式庫，因此二進位檔會使用 libc malloc。這個標籤必須參照 cc_library。如果編譯作業是針對非 C++ 規則，則這個選項不會有任何作用。如果指定 linkshared=True，系統會忽略此屬性的值。
module_interfaces

標籤清單；預設為 []

檔案清單會視為 C++20 模組介面。

C++ 標準對模組介面檔案副檔名沒有限制

  • Clang 使用 cppm
  • GCC 可使用任何來源檔案副檔名
  • MSVC 使用 ixx

使用方式受到 --experimental_cpp_modules 旗標的保護。
nocopts

字串；預設為 ""

從 C++ 編譯指令中移除相符的選項。適用於 "Make" 變數替換。系統會將此屬性的值解讀為規則運算式。為了編譯此規則，系統會從 COPTS 中移除任何符合此規則運算式的先前 COPTS (包括規則 copts 屬性中明確指定的值)。這個屬性不應在 third_party 以外的情況下使用或需要。除了「Make」變數替換之外，系統不會以任何方式預先處理這些值。
reexport_deps

標籤清單；預設為 []
stamp

整數；預設值為 -1

是否將建構資訊編碼至二進位檔。可能的值：
  • stamp = 1：一律將建構資訊戳記到二進位檔案中，即使是在 --nostamp 版本中也是如此。請避免使用這項設定，因為這可能會導致二進位檔和任何依賴二進位檔的後續動作無法進行遠端快取。
  • stamp = 0：一律使用常數值取代建構資訊。這可提供良好的建構結果快取功能。
  • stamp = -1：版本資訊的嵌入方式由 --[no]stamp 標記控制。

除非依附元件變更，否則系統不會重新建構經過標記的二進位檔。
win_def_file

標籤；預設為 None

要傳遞至連結器的 Windows DEF 檔案。

只有在 Windows 是目標平台時，才應使用這個屬性。可在連結共用程式庫時 匯出符號。

cc_import

查看規則來源 
cc_import(name, deps, data, hdrs, alwayslink, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, includes, interface_library, linkopts, objects, pic_objects, pic_static_library, restricted_to, shared_library, static_library, system_provided, tags, target_compatible_with, testonly, toolchains, visibility)

cc_import 規則可讓使用者匯入預先編譯的 C/C++ 程式庫。

以下是常見用途：
1. 連結靜態資料庫


cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  static_library = "libmylib.a",
  # If alwayslink is turned on,
  # libmylib.a will be forcely linked into any binary that depends on it.
  # alwayslink = True,
)
2. 連結共用程式庫 (Unix)

cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  shared_library = "libmylib.so",
)
3. 將共用程式庫連結至介面程式庫

在 Unix 上：


cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  # libmylib.ifso is an interface library for libmylib.so which will be passed to linker
  interface_library = "libmylib.ifso",
  # libmylib.so will be available for runtime
  shared_library = "libmylib.so",
)

Windows：


cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  # mylib.lib is an import library for mylib.dll which will be passed to linker
  interface_library = "mylib.lib",
  # mylib.dll will be available for runtime
  shared_library = "mylib.dll",
)
4. 使用 system_provided=True 連結共用程式庫

在 Unix 上：


cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  interface_library = "libmylib.ifso", # Or we can also use libmylib.so as its own interface library
  # libmylib.so is provided by system environment, for example it can be found in LD_LIBRARY_PATH.
  # This indicates that Bazel is not responsible for making libmylib.so available.
  system_provided = True,
)

Windows：


cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  # mylib.lib is an import library for mylib.dll which will be passed to linker
  interface_library = "mylib.lib",
  # mylib.dll is provided by system environment, for example it can be found in PATH.
  # This indicates that Bazel is not responsible for making mylib.dll available.
  system_provided = True,
)
5. 連結至靜態或共用程式庫

在 Unix 上：


cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  static_library = "libmylib.a",
  shared_library = "libmylib.so",
)

Windows：


cc_import(
  name = "mylib",
  hdrs = ["mylib.h"],
  static_library = "libmylib.lib", # A normal static library
  interface_library = "mylib.lib", # An import library for mylib.dll
  shared_library = "mylib.dll",
)

其餘部分在 Unix 和 Windows 上都相同：


# first will link to libmylib.a (or libmylib.lib)
cc_binary(
  name = "first",
  srcs = ["first.cc"],
  deps = [":mylib"],
  linkstatic = True, # default value
)

# second will link to libmylib.so (or libmylib.lib)
cc_binary(
  name = "second",
  srcs = ["second.cc"],
  deps = [":mylib"],
  linkstatic = False,
)

cc_import 支援 include 屬性。例如：


cc_import(
  name = "curl_lib",
  hdrs = glob(["vendor/curl/include/curl/*.h"]),
  includes = ["vendor/curl/include"],
  shared_library = "vendor/curl/lib/.libs/libcurl.dylib",
)

引數

屬性
name

名稱；必填

這個目標的專屬名稱。
deps

標籤清單；預設為 []

目標依附的其他程式庫清單。如要查看 deps 的一般註解，請參閱「大多數建構規則定義的常見屬性」。
hdrs

標籤清單；預設為 []

這個預先編譯資料庫發布的標頭檔案清單，可由依附規則中的來源直接納入。

布林值；預設值為 False

如果為 1，則任何直接或間接依賴此 C++ 預先編譯程式庫的二進位檔，都會連結靜態資料庫中封存的所有物件檔案，即使其中有些檔案不含二進位檔參照的符號也一樣。如果二進位檔中的程式碼並未明確呼叫您的程式碼 (例如，如果您的程式碼註冊接收某些服務提供的回呼)，這項功能就很實用。

如果 alwayslink 無法在 Windows 上與 VS 2017 搭配運作，可能是因為已知問題，請將 VS 2017 升級至最新版本。
includes

字串清單；預設為 []

要新增至編譯行中的包含目錄清單。適用於 "Make 變數" 替換。每個字串都會加上套件路徑，並傳遞至 C++ 工具鍊，以便透過「include_paths」CROSSTOOL 功能進行展開。在 POSIX 系統上執行的工具鍊，如果含有一般功能定義，就會產生 -isystem path_to_package/include_entry。這項功能僅適用於不符合 Google 寫法風格的第三方程式庫 #include 陳述式。與 COPTS 不同的是，這些標記會新增至此規則和所有依附此規則的規則。(注意：不是依附的規則！)請務必謹慎操作，因為這可能會造成廣泛的影響。如有疑問，請改為在 COPTS 中加入「-I」標記。

預設 include 路徑不包含產生的檔案。如果您需要 #include 產生的標頭檔案，請在 srcs 中列出該檔案。
interface_library

標籤；預設為 None

用於連結共用程式庫的單一介面程式庫。

允許的檔案類型： .ifso、 .tbd、 .lib、 .so 或 .dylib

linkopts

字串清單；預設為 []

將這些標記新增至 C++ 連結器指令。適用於 「Make」變數替換、 Bourne 殼層符記化和標籤展開。這個屬性中的每個字串都會在連結二進位目標之前新增至 LINKOPTS。

清單中每個元素的開頭不是 $ 或 -，則會視為 deps 中目標的標籤。該目標產生的檔案清單會附加至連結器選項。如果標籤無效，或未在 deps 中宣告，系統會回報錯誤。
objects

標籤清單；預設為 []
pic_objects

標籤清單；預設為 []
pic_static_library

標籤；預設為 None
shared_library

標籤；預設為 None

單一預編譯共用程式庫。Bazel 會確保在執行階段，依附元件可供依附於該元件的二進位檔使用。

允許的檔案類型：.so、.dll 或 .dylib
static_library

標籤；預設為 None

單一預先編譯的靜態資料庫。

允許的檔案類型：.a、.pic.a 或 .lib
system_provided

布林值；預設值為 False

如果為 1，表示系統會提供執行階段所需的共用資料庫。在這種情況下，應指定 interface_library，而 shared_library 應留空。

cc_library

查看規則來源 
cc_library(name, deps, srcs, data, hdrs, additional_compiler_inputs, additional_linker_inputs, alwayslink, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, exec_compatible_with, exec_properties, features, hdrs_check, implementation_deps, include_prefix, includes, licenses, linkopts, linkstamp, linkstatic, local_defines, module_interfaces, restricted_to, strip_include_prefix, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, win_def_file)

請將 cc_library() 用於 C++ 編譯的程式庫。結果可能是 .so、.lo 或 .a，具體取決於需求。

如果您使用依附 cc_library 的靜態連結來建構項目，依附程式庫規則的輸出內容就是 .a 檔案。如果您指定 alwayslink=True，就會取得 .lo 檔案。

共用程式庫的實際輸出檔案名稱為 libfoo.so，其中 foo 是規則的名稱。其他類型的程式庫結尾分別為 .lo 和 .a。如果您需要特定的共用程式庫名稱 (例如，用於定義 Python 模組)，請使用 genrule 將程式庫複製至所需名稱。

標頭納入檢查

在建構作業中使用的所有標頭檔案，都必須在 cc_* 規則的 hdrs 或 srcs 中宣告。這項規定是強制執行的。

對於 cc_library 規則，hdrs 中的標頭包含程式庫的公開介面，可直接從 hdrs 和程式庫本身的 srcs 檔案，以及 cc_* 規則的 hdrs 和 srcs 檔案中，列出程式庫的 deps 中直接納入。srcs 中的標頭只能直接從資料庫本身的 hdrs 和 srcs 檔案中加入。決定是否要將標頭放入 hdrs 或 srcs 時，請先考慮是否要讓這個程式庫的使用者能夠直接納入標頭。這與程式語言中 public 和 private 可見性之間的決定大致相同。

cc_binary 和 cc_test 規則沒有匯出的介面，因此也沒有 hdrs 屬性。所有直接屬於二進位檔或測試的標頭都應列在 srcs 中。

以下範例說明這些規則。


cc_binary(
    name = "foo",
    srcs = [
        "foo.cc",
        "foo.h",
    ],
    deps = [":bar"],
)

cc_library(
    name = "bar",
    srcs = [
        "bar.cc",
        "bar-impl.h",
    ],
    hdrs = ["bar.h"],
    deps = [":baz"],
)

cc_library(
    name = "baz",
    srcs = [
        "baz.cc",
        "baz-impl.h",
    ],
    hdrs = ["baz.h"],
)

下表列出此範例中允許的直接包含項目。舉例來說，foo.cc 可直接包含 foo.h 和 bar.h，但不能包含 baz.h。

包含檔案允許納入的內容
foo.hbar.h
foo.ccfoo.h bar.h
bar.hbar-impl.h baz.h
bar-impl.hbar.h baz.h
bar.ccbar.h bar-impl.h baz.h
baz.hbaz-impl.h
baz-impl.hbaz.h
baz.ccbaz.h baz-impl.h

納入檢查規則僅適用於直接納入內容。在上述範例中，foo.cc 可包含 bar.h，而 bar.h 可包含 baz.h，baz.h 則可包含 baz-impl.h。從技術層面來說，編譯 .cc 檔案時，可能會透過 deps 閉包中的 cc_library 將 hdrs 或 srcs 中的任何標頭檔案納入。在這種情況下，編譯器在編譯 foo.cc 時可能會讀取 baz.h 和 baz-impl.h，但 foo.cc 不得包含 #include "baz.h"。為允許這項操作，baz 必須新增至 foo 的 deps。

Bazel 會依賴工具鍊支援功能來強制執行包含檢查規則。工具鍊必須支援 layering_check 功能，並明確要求此功能，例如透過 --features=layering_check 指令列旗標或 package 函式的 features 參數。Bazel 提供的工具鍊僅支援在 Unix 和 macOS 上使用 clang 執行這項功能。

範例


cc_library(
    name = "ast_inspector_lib",
    srcs = ["ast_inspector_lib.cc"],
    hdrs = ["ast_inspector_lib.h"],
    visibility = ["//visibility:public"],
    deps = ["//third_party/llvm/llvm/tools/clang:frontend"],
    # alwayslink as we want to be able to call things in this library at
    # debug time, even if they aren't used anywhere in the code.
    alwayslink = 1,
)

以下範例來自 third_party/python2_4_3/BUILD。部分程式碼會使用 dl 程式庫 (用於載入其他動態程式庫)，因此這項規則會指定 -ldl 連結選項，以連結 dl 程式庫。


cc_library(
    name = "python2_4_3",
    linkopts = [
        "-ldl",
        "-lutil",
    ],
    deps = ["//third_party/expat"],
)

以下範例來自 third_party/kde/BUILD。我們會在集管器中保留預先建構的 .so 檔案。標頭檔案位於名為 include 的子目錄中。


cc_library(
    name = "kde",
    srcs = [
        "lib/libDCOP.so",
        "lib/libkdesu.so",
        "lib/libkhtml.so",
        "lib/libkparts.so",
        ...more .so files...,
    ],
    includes = ["include"],
    deps = ["//third_party/X11"],
)

以下範例來自 third_party/gles/BUILD。第三方程式碼通常需要一些 defines 和 linkopts。


cc_library(
    name = "gles",
    srcs = [
        "GLES/egl.h",
        "GLES/gl.h",
        "ddx.c",
        "egl.c",
    ],
    defines = [
        "USE_FLOAT",
        "__GL_FLOAT",
        "__GL_COMMON",
    ],
    linkopts = ["-ldl"],  # uses dlopen(), dl library
    deps = [
        "es",
        "//third_party/X11",
    ],
)

引數

屬性
name

名稱；必填

這個目標的專屬名稱。
deps

標籤清單；預設為 []

程式庫目標依附的其他程式庫清單。

這些可以是 cc_library 或 objc_library 目標。

如要查看 deps 的一般註解，請參閱「大多數建構規則定義的常見屬性」。

這些應為 C++ 程式庫規則的名稱。建構連結此規則程式庫的二進位檔時，您也會連結 deps 中的程式庫。

儘管名稱為「deps」，但並非所有程式庫的用戶端都屬於此類別。執行階段資料依附元件應放在 data 中。其他規則產生的來源檔案則屬於 srcs。

如要連結預先編譯的第三方程式庫，請改為將其名稱新增至 srcs。

如要依附某個項目，但不將其連結至這個程式庫，請改為將其名稱新增至 data。
srcs

標籤清單；預設為 []

用來建立程式庫目標的 C 和 C++ 檔案清單。這些是 C/C++ 來源和標頭檔案，可能是未產生的 (一般來源程式碼) 或已產生的。

系統會編譯所有 .cc、.c 和 .cpp 檔案。這些檔案可能是產生的檔案：如果某個已命名的檔案位於其他規則的 outs 中，這個 cc_library 就會自動依附該規則。

純粹的彙整器檔案 (.s、.asm) 不會經過預先處理，通常會使用彙整器建構。經過預處理的彙整檔案 (.S) 會經過預處理，並通常使用 C/C++ 編譯器建構。

系統不會編譯 .h 檔案，但可供此規則中的來源加入。.cc 和 .h 檔案都能直接納入這些 srcs 或此規則的 hdrs 中列出的標頭，或是 deps 引數中列出的任何規則。

所有已 #include 檔案都必須在這個或參照的 cc_library 規則的 hdrs 屬性中提及，如果這些檔案是此程式庫的私人檔案，則應列在 srcs 中。詳情請參閱「"標頭包含檢查"。

.so、.lo 和 .a 檔案是預先編譯的檔案。如果程式庫使用我們沒有原始碼的第三方程式碼，則可能會以 srcs 的形式顯示。

如果 srcs 屬性包含其他規則的標籤，cc_library 會使用該規則的輸出檔案做為來源檔案進行編譯。這項功能可用於一次性產生原始碼 (如果要經常使用，建議實作 Starlark 規則類別並使用 cc_common API)

允許的 srcs 檔案類型：

  • C 和 C++ 來源檔案：.c、.cc、.cpp、.cxx、.c++、.C
  • C 和 C++ 標頭檔案：.h、.hh、.hpp、.hxx、.inc、.inl、.H
  • 使用 C 前置處理器的組譯器：.S
  • 封存：.a、.pic.a
  • 「一律連結」程式庫：.lo、.pic.lo
  • 共用資料庫 (已分版本或未分版本)：.so、.so.version
  • 物件檔案：.o、.pic.o

... 以及產生這些檔案的任何規則 (例如 cc_embed_data)。 根據 gcc 慣例，不同的副檔名代表不同的程式設計語言。
data

標籤清單；預設為 []

這個程式庫在執行階段所需的檔案清單。如要查看 data 的一般註解，請參閱「大多數建構規則定義的常見屬性」。

如果 data 是產生檔案的名稱，則這個 cc_library 規則會自動依附產生規則。

如果 data 是規則名稱，則這個 cc_library 規則會自動依賴該規則，而該規則的 outs 會自動加入這個 cc_library 的資料檔案。

C++ 程式碼可以存取這些資料檔案，如下所示：


  const std::string path = devtools_build::GetDataDependencyFilepath(
      "my/test/data/file");
hdrs

標籤清單；預設為 []

這個程式庫發布的標頭檔案清單，可由依附規則中的來源直接納入。

這是宣告描述程式庫介面的標頭檔案的首選位置。這些標頭會開放給這項規則或相關依附規則中的來源使用。即使標頭已由發布的標頭納入，如果該標頭並非此程式庫的用戶端應納入的標頭，也應列在 srcs 屬性中。詳情請參閱「"Header inclusion checking"。

允許的 headers 檔案類型： .h、 .hh、 .hpp、 .hxx。

additional_compiler_inputs

標籤清單；預設為 []

您可能想要傳遞至編譯器指令列的任何其他檔案，例如消毒劑忽略清單。您可以在 copts 中使用此處指定的檔案，並搭配 $(location) 函式。
additional_linker_inputs

標籤清單；預設為 []

將這些檔案傳遞至 C++ 連結器指令。

例如，您可以在此提供已編譯的 Windows .res 檔案，以便嵌入二進位目標。

布林值；預設值為 False

如果為 1，則任何直接或間接依附此 C++ 程式庫的二進位檔案，都會連結 srcs 中列出的所有物件檔案，即使其中有些檔案不含二進位檔案參照的符號也一樣。如果二進位檔中的程式碼並未明確呼叫您的程式碼 (例如，如果您的程式碼註冊接收某些服務提供的回呼)，這項功能就很實用。

如果 alwayslink 無法在 Windows 上與 VS 2017 搭配運作，可能是因為已知問題，請將 VS 2017 升級至最新版本。
conlyopts

字串清單；預設為 []

將這些選項加入 C 編譯指令。適用於 "Make variable" 替換和 Bourne shell 符記化。
copts

字串清單；預設為 []

將這些選項加入 C/C++ 編譯指令。適用於 "Make variable" 替換和 Bourne shell 符記化。

這個屬性中的每個字串都會依照指定順序新增至 COPTS，然後再編譯二進位目標。標記只會影響編譯這個目標，而非其依附元件，因此請留意其他地方是否包含標頭檔案。所有路徑都應以工作區為基準，而非目前套件。在 third_party 以外的情況下，不應需要此屬性。

如果套件宣告功能 no_copts_tokenization，Bourne shell 符記化只會套用至由單一「Make」變數組成的字串。
cxxopts

字串清單；預設為 []

將這些選項新增至 C++ 編譯指令。適用於 "Make variable" 替換和 Bourne shell 符記化。
defines

字串清單；預設為 []

要新增至編譯行中的定義清單。適用於 "Make" 變數替換和 Bourne shell 符記化。每個字串都必須包含單一 Bourne 殼層符記，並在開頭加上 -D，然後新增至這個目標的編譯指令行，以及依附於該目標的每個規則。請務必謹慎操作，因為這可能會造成廣泛的影響。如有疑問，請改為將定義值新增至 local_defines。
hdrs_check

字串；預設為 ""

已淘汰，無操作。
implementation_deps

標籤清單；預設為 []

程式庫目標依附的其他程式庫清單。與 deps 不同，這些程式庫的標頭和包含路徑 (以及所有傳遞依附元件) 只用於編譯這個程式庫，而非依附於此程式庫的程式庫。使用 implementation_deps 指定的程式庫仍會連結至依賴此程式庫的二進位目標。
include_prefix

字串；預設為 ""

要新增至此規則標頭路徑的前置字串。

設定後，您可以在該規則的 hdrs 屬性中存取標頭，該屬性值會附加至相對於存放區的路徑。

系統會先移除 strip_include_prefix 屬性中的前置字串，再新增這個前置字串。

這項屬性僅適用於 third_party。
includes

字串清單；預設為 []

要新增至編譯行中的包含目錄清單。適用於 "Make 變數" 替換。每個字串都會加上套件路徑，並傳遞至 C++ 工具鍊，以便透過「include_paths」CROSSTOOL 功能進行展開。在 POSIX 系統上執行的工具鍊，如果含有一般功能定義，就會產生 -isystem path_to_package/include_entry。這項功能僅適用於不符合 Google 寫法風格的第三方程式庫 #include 陳述式。與 COPTS 不同的是，這些標記會新增至此規則和所有依附此規則的規則。(注意：不是依附的規則！)請務必謹慎操作，因為這可能會造成廣泛的影響。如有疑問，請改為在 COPTS 中加入「-I」標記。

新增的 include 路徑會包含產生的檔案，以及來源樹狀結構中的檔案。
linkopts

字串清單；預設為 []

請參閱 cc_binary.linkopts。linkopts 屬性也會套用至任何目標，這些目標會透過 deps 屬性 (或透過其他類似處理方式的屬性：cc_binary 的 malloc 屬性)，直接或間接地依附於這個程式庫。相依性 linkopt 優先於相依 linkopt (也就是說，相依性 linkopt 會在命令列中稍後出現)。在 --linkopt 中指定的 Linkopt 優先於規則 Linkopt。

請注意，linkopts 屬性僅適用於建立 .so 檔案或可執行檔，而不適用於建立 .a 或 .lo 檔案。因此，如果已設定 linkstatic=True 屬性，linkopts 屬性就不會影響此程式庫的建立作業，只會影響依附此程式庫的其他目標。

此外，請注意，系統不支援「-Wl,-soname」或「-Xlinker -soname」選項，且不應在這個屬性中指定這些選項。

cc_library 規則產生的 .so 檔案並未連結至其依附的程式庫。如果您要建立共用程式庫，用於主要存放區以外的情況 (例如手動使用 dlopen() 或 LD_PRELOAD)，建議您使用 cc_binary 規則搭配 linkshared=True 屬性。請參閱 cc_binary.linkshared。
linkstamp

標籤；預設為 None

同時編譯並將指定的 C++ 來源檔案連結至最終二進位檔。您必須使用這種技巧，才能將時間戳記資訊加入二進位檔；如果我們以一般方式將來源檔案編譯為物件檔案，時間戳記就會不正確。連結標記編譯作業可能不包含任何特定的編譯器旗標組合，因此不應依賴任何特定的標頭、編譯器選項或其他建構變數。這個選項僅適用於 base 套件。
linkstatic

布林值；預設值為 False

針對 cc_binary 和 cc_test：在靜態模式中連結二進位檔。如為 cc_library.link_static：請參閱下文。

根據預設，這個選項會為 cc_binary 開啟，其餘選項則為關閉。

如果已啟用，且這是二進位檔或測試，這個選項會指示建構工具盡可能連結 .a 而非 .so 的使用者程式庫。系統程式庫 (例如 libc，但不是 C/C++ 執行階段程式庫，請參閱下文) 仍會動態連結，沒有靜態資料庫的程式庫也是如此。因此產生的可執行檔仍會以動態方式連結，因此只有「大部分」是靜態的。

實際上有三種不同的方式可以連結可執行檔：

  • STATIC 搭配 fully_static_link 功能，其中所有項目都會以靜態方式連結，例如「gcc -static foo.o libbar.a libbaz.a -lm」。
    如要啟用這個模式，請在 features 屬性中指定 fully_static_link。
  • STATIC，其中所有使用者程式庫會以靜態方式連結 (如果有靜態版本)，但系統程式庫 (不含 C/C++ 執行階段程式庫) 會以動態方式連結，例如「gcc foo.o libfoo.a libbaz.a -lm」。
    如要啟用此模式，請指定 linkstatic=True。
  • DYNAMIC，所有程式庫都會動態連結 (如果有動態版本)，例如「gcc foo.o libfoo.so libbaz.so -lm」。
    如要啟用這個模式，請指定 linkstatic=False。

如果 features 中的 linkstatic 屬性或 fully_static_link 用於 //third_party 外，請在規則旁邊加入註解，說明原因。

如果 linkstatic 屬性用於 cc_library() 規則，其意義就會有所不同。對於 C++ 程式庫，linkstatic=True 表示只允許靜態連結，因此不會產生 .so。linkstatic=False 不會阻止建立靜態資料庫。這個屬性用於控制動態程式庫的建立作業。

在正式環境中，使用 linkstatic=False 建構的程式碼應極少。如果是 linkstatic=False，則建構工具會在 *.runfiles 區域中建立指向所依附共用程式庫的符號連結。
local_defines

字串清單；預設為 []

要新增至編譯行中的定義清單。適用於 "Make" 變數替換和 Bourne shell 符記化。每個字串都必須包含單一 Bourne 殼層符記，並在開頭加上 -D，然後新增至此目標的編譯指令行，但不新增至其依附項目。
module_interfaces

標籤清單；預設為 []

檔案清單會視為 C++20 模組介面。

C++ 標準對模組介面檔案副檔名沒有限制

  • Clang 使用 cppm
  • GCC 可使用任何來源檔案副檔名
  • MSVC 使用 ixx

使用方式受到 --experimental_cpp_modules 旗標的保護。
strip_include_prefix

字串；預設為 ""

要從此規則標頭路徑中移除的前置字串。

設定後，您就可以在路徑中使用這個前置字串，存取這個規則的 hdrs 屬性中的標頭。

如果是相對路徑，則會視為與套件相關的路徑。如果是絕對路徑，系統會將其視為相對於存放區的路徑。

這個前置字元會在移除後，新增至 include_prefix 屬性。

這項屬性僅適用於 third_party。
textual_hdrs

標籤清單；預設為 []

這個程式庫發布的標頭檔案清單，可讓依附規則中的來源以文字形式納入。

這是宣告無法自行編譯的標頭檔案位置，也就是說，其他來源檔案必須以文字形式納入標頭檔案，才能建構有效的程式碼。
win_def_file

標籤；預設為 None

要傳遞至連結器的 Windows DEF 檔案。

只有在 Windows 是目標平台時，才應使用這個屬性。可在連結共用程式庫時 匯出符號。

cc_shared_library

查看規則來源 
cc_shared_library(name, deps, additional_linker_inputs, compatible_with, deprecation, distribs, dynamic_deps, exec_compatible_with, exec_properties, exports_filter, features, restricted_to, roots, shared_lib_name, static_deps, tags, target_compatible_with, testonly, toolchains, user_link_flags, visibility, win_def_file)

會產生共用程式庫。

範例

cc_shared_library(
    name = "foo_shared",
    deps = [
        ":foo",
    ],
    dynamic_deps = [
        ":bar_shared",
    ],
    additional_linker_inputs = [
        ":foo.lds",
    ],
    user_link_flags = [
        "-Wl,--version-script=$(location :foo.lds)",
    ],
)
cc_library(
    name = "foo",
    srcs = ["foo.cc"],
    hdrs = ["foo.h"],
    deps = [
        ":bar",
        ":baz",
    ],
)
cc_shared_library(
    name = "bar_shared",
    shared_lib_name = "bar.so",
    deps = [":bar"],
)
cc_library(
    name = "bar",
    srcs = ["bar.cc"],
    hdrs = ["bar.h"],
)
cc_library(
    name = "baz",
    srcs = ["baz.cc"],
    hdrs = ["baz.h"],
)

在這個範例中，foo_shared 會靜態連結 foo 和 baz，後者是傳遞式依附元件。系統已由 dynamic_dep bar_shared 動態提供 bar，因此不會連結 bar。

foo_shared 會使用連結器指令碼 *.lds 檔案，控管應匯出的符號。cc_shared_library 規則邏輯不會控制要匯出的符號，只會使用假設要匯出的符號，在分析階段提供錯誤訊息 (如果兩個共用程式庫匯出相同的目標)。

系統會假設 cc_shared_library 的每個直接依附元件都會匯出。因此，Bazel 在分析期間會假設 foo 是由 foo_shared 匯出。系統不會假設 baz 是由 foo_shared 匯出。系統也會假設 exports_filter 比對到的每個目標都會匯出。

範例中的每個 cc_library 最多只能出現在一個 cc_shared_library 中。如果我們想將 baz 連結至 bar_shared，就必須將 tags = ["LINKABLE_MORE_THAN_ONCE"] 新增至 baz。

由於 shared_lib_name 屬性，bar_shared 產生的檔案名稱會是 bar.so，而非 Linux 上的預設名稱 libbar.so。

錯誤

Two shared libraries in dependencies export the same symbols.

只要您建立的目標含有兩個匯出相同目標的不同 cc_shared_library 依附元件，就會發生這種情況。如要修正這個問題，您必須停止在其中一個 cc_shared_library 依附元件中匯出程式庫。

只要您建立新 cc_shared_library 時，其中包含兩個不同的 cc_shared_library 依附元件，且這些依附元件會靜態連結相同的目標，就會發生這種情況。與匯出錯誤類似。

修正這個問題的方法之一，是停止將程式庫連結至其中一個 cc_shared_library 依附元件。同時，仍連結該程式庫的應用程式需要匯出該程式庫，以便未連結該程式庫的應用程式可繼續查看該程式庫中的符號。另一種方法是提取匯出目標的第三方程式庫。第三種方法是使用 LINKABLE_MORE_THAN_ONCE 標記問題來源 cc_library，但這種修正方式應極少使用，您必須確保 cc_library 確實可安全地重複連結。

'//foo:foo' is already linked statically in '//bar:bar' but not exported`

這表示 deps 遞移閉合中的程式庫可供存取，且不必經過其中一個 cc_shared_library 依附元件，但已連結至 dynamic_deps 中的不同 cc_shared_library，且未匯出。

解決方法是從 cc_shared_library 依附元件匯出，或提取匯出該依附元件的第三方 cc_shared_library。

Do not place libraries which only contain a precompiled dynamic library in deps.

如果您有預先編譯的動態程式庫，則不需要且無法將其靜態連結至您目前正在建立的 cc_shared_library 目標。因此，它不屬於 cc_shared_library 的 deps。如果這個預先編譯的動態程式庫是 cc_libraries 其中一個的依附元件，則 cc_library 需要直接依附該程式庫。

Trying to export a library already exported by a different shared library

如果您在目前的規則中聲明要匯出目標，而該目標已由其中一個動態依附元件匯出，系統就會顯示這則錯誤訊息。

如要修正這個問題，請從 deps 中移除目標，並只從動態依附元件中依賴該目標，或是確認 exports_filter 不會擷取這個目標。

引數

屬性
name

名稱；必填

這個目標的專屬名稱。
deps

標籤清單；預設為 []

頂層程式庫，在經過整個封存作業後，會無條件地靜態連結至共用程式庫。

只要這些直接依附元件的任何間接程式庫依附元件尚未在 dynamic_deps 中連結至 cc_shared_library，就會連結至這個共用程式庫。

在分析期間，規則實作會將 deps 中列出的任何目標視為由共用程式庫匯出，以便在多個 cc_shared_libraries 匯出相同目標時顯示錯誤。規則實作不會通知連結器，共用物件應匯出哪些符號。使用者應透過連結器指令碼或原始碼中的可見度宣告來處理此問題。

當相同程式庫靜態連結至多個 cc_shared_library 時，實作也會觸發錯誤。如要避免這種情況，請將 "LINKABLE_MORE_THAN_ONCE" 新增至 cc_library.tags，或將 `cc_library` 列為其中一個共用程式庫的匯出項目，以便將其中一個程式庫設為另一個程式庫的 dynamic_dep。
additional_linker_inputs

標籤清單；預設為 []

您可能要傳遞給連結器的任何其他檔案，例如連結器指令碼。您必須另外傳遞連結器需要的任何連結器標記，才能讓連結器瞭解這個檔案。您可以透過 user_link_flags 屬性執行這項操作。
dynamic_deps

標籤清單；預設為 []

這些是目前目標依附的其他 cc_shared_library 依附元件。

cc_shared_library 實作會使用 dynamic_deps 清單 (以傳遞方式，也就是目前目標 dynamic_deps 的 dynamic_deps) 決定哪些 cc_libraries 不應連結至傳遞 deps，因為這些 cc_libraries 已由其他 cc_shared_library 提供。
exports_filter

字串清單；預設為 []

此屬性包含由目前共用程式庫宣稱要匯出的目標清單。

任何目標 deps 都已知會由共用程式庫匯出。這項屬性應用於列出共用程式庫匯出的任何目標，但這些目標是 deps 的間接依附元件。

請注意，這個屬性實際上並不會在這些目標中新增依附元件邊緣，而是應由 deps 建立依附元件邊緣。這個屬性中的項目只是字串。請注意，將目標放在這個屬性中，就表示共用程式庫會從該目標匯出符號。cc_shared_library 邏輯實際上不會處理告知連結器應匯出哪些符號的作業。

以下語法是允許的：

//foo:__pkg__ 可用於處理 foo/BUILD 中的任何目標

//foo:__subpackages__ 可用於處理 foo/BUILD 中的任何目標，或 foo/ 以下的任何其他套件，例如 foo/bar/BUILD
roots

標籤清單；預設為 []
shared_lib_name

字串；預設為 ""

根據預設，cc_shared_library 會根據目標名稱和平台，為共用程式庫輸出檔案使用名稱。包括擴充功能，有時也會包含前置字串。有時您可能不想要使用預設名稱，例如在為 Python 載入 C++ 共用程式庫時，通常不會使用預設的 lib* 前置字元，在這種情況下，您可以使用這個屬性選擇自訂名稱。
static_deps

字串清單；預設為 []

字串清單；預設為 []

您可能要傳遞給連結器的任何額外旗標。舉例來說，如要讓連結器瞭解透過 additional_linker_inputs 傳遞的連結器指令碼，您可以使用下列指令碼：

 cc_shared_library(
    name = "foo_shared",
    additional_linker_inputs = select({
      "//src/conditions:linux": [
        ":foo.lds",
        ":additional_script.txt",
      ],
      "//conditions:default": []}),
    user_link_flags = select({
      "//src/conditions:linux": [
        "-Wl,-rpath,kittens",
        "-Wl,--version-script=$(location :foo.lds)",
        "-Wl,--script=$(location :additional_script.txt)",
      ],
      "//conditions:default": []}),
      ...
 )
win_def_file

標籤；預設為 None

要傳遞至連結器的 Windows DEF 檔案。

只有在 Windows 是目標平台時，才應使用這個屬性。可在連結共用程式庫時 匯出符號。

cc_static_library

查看規則來源 
cc_static_library(name, deps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)
 此規則目前為實驗功能，只能與 --experimental_cc_static_library 旗標搭配使用。 根據目標清單及其間接依附元件，產生靜態資料庫。

產生的靜態資料庫包含 deps 中列出的目標物件檔案，以及其間接依附元件，並將偏好設定給 PIC 物件。

輸出群組

linkdeps

文字檔案，其中包含 deps 中列出的目標的傳遞依附元件標籤，這些目標並未為靜態資料庫提供任何物件檔案，但至少提供一個靜態、動態或介面資料庫。產生的靜態資料庫可能會要求這些程式庫在連結時可用。

linkopts

文字檔案，其中包含使用者提供的 linkopts，列出 deps 中列出的目標的所有傳遞依附元件。

重複符號

根據預設，cc_static_library 規則會檢查產生的靜態程式庫是否包含任何重複的符號。如果是這樣，建構作業就會失敗，並顯示列出重複符號和包含這些符號的物件檔案的錯誤訊息。

您可以設定 features = ["-symbol_check"]，或透過 --features=-symbol_check 全面停用每個目標或每個套件的這項檢查。

symbol_check 的工具鍊支援

搭配 Bazel 提供的自動設定 C++ 工具鍊，可在所有平台上支援 symbol_check 功能。自訂工具鍊可以透過下列兩種方式之一新增支援：

  • 實作 ACTION_NAMES.validate_static_library 動作，並透過 symbol_check 功能啟用該動作。在動作中設定的工具會透過兩個引數叫用：用於檢查重複符號的靜態資料庫，以及在檢查通過時必須建立的檔案路徑。
  • 讓 symbol_check 功能新增封存器旗標，導致建立靜態資料庫的動作在重複符號上失敗。

引數

屬性
name

名稱；必填

這個目標的專屬名稱。
deps

標籤清單；預設為 []

要合併至靜態程式庫的目標清單，包括所有遞移依附元件。

靜態程式庫不會納入未提供任何物件檔案的依附元件，但會在 linkdeps 輸出群組提供的檔案中收集這些依附元件的標籤。

cc_test

查看規則來源 
cc_test(name, deps, srcs, data, additional_linker_inputs, args, compatible_with, conlyopts, copts, cxxopts, defines, deprecation, distribs, dynamic_deps, env, env_inherit, exec_compatible_with, exec_properties, features, flaky, hdrs_check, includes, licenses, link_extra_lib, linkopts, linkshared, linkstatic, local, local_defines, malloc, module_interfaces, nocopts, reexport_deps, restricted_to, shard_count, size, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility, win_def_file)

cc_test() 規則會編譯測試。在本例中，測試是指包裝某些測試程式碼的二進位檔。

根據預設，C++ 測試會以動態連結方式連結。
如要將單元測試連結為靜態，請指定 linkstatic=True。建議您註解為何測試需要 linkstatic；這可能不是很明顯。

隱含輸出目標

  • name.stripped (僅在明確要求時建構)：經過精簡的二進位檔版本。strip -g 會在二進位檔上執行，以移除偵錯符號。您可以使用 --stripopt=-foo 在指令列上提供其他去除選項。
  • name.dwp (僅在明確要求時才建構)：如果已啟用 Fission：偵錯資訊套件檔案，適合用於偵錯遠端部署的二進位檔。否則：空白檔案。

請參閱 cc_binary() 引數，但測試的 stamp 引數預設為 0，且 cc_test 具有額外的 所有測試規則 (*_test) 通用的屬性。

引數

屬性
name

名稱；必填

這個目標的專屬名稱。
deps

標籤清單；預設為 []

要連結至二進位目標的其他程式庫清單。

這些可以是 cc_library 或 objc_library 目標。

您也可以將連結器指令碼 (.lds) 放入依附元件，並在 linkopts 中參照這些指令碼。
srcs

標籤清單；預設為 []

用來建立程式庫目標的 C 和 C++ 檔案清單。這些是 C/C++ 來源和標頭檔案，可能是未產生的 (一般來源程式碼) 或已產生的。

系統會編譯所有 .cc、.c 和 .cpp 檔案。這些檔案可能是產生的檔案：如果某個已命名的檔案位於其他規則的 outs 中，這個 cc_library 就會自動依附該規則。

純粹的彙整器檔案 (.s、.asm) 不會經過預先處理，通常會使用彙整器建構。經過預處理的彙整檔案 (.S) 會經過預處理，並通常使用 C/C++ 編譯器建構。

系統不會編譯 .h 檔案，但可供此規則中的來源加入。.cc 和 .h 檔案都能直接納入這些 srcs 或此規則的 hdrs 中列出的標頭，或是 deps 引數中列出的任何規則。

所有已 #include 檔案都必須在這個或參照的 cc_library 規則的 hdrs 屬性中提及，如果這些檔案是此程式庫的私人檔案，則應列在 srcs 中。詳情請參閱「"標頭包含檢查"。

.so、.lo 和 .a 檔案是預先編譯的檔案。如果程式庫使用我們沒有原始碼的第三方程式碼，則可能會以 srcs 的形式顯示。

如果 srcs 屬性包含其他規則的標籤，cc_library 會使用該規則的輸出檔案做為來源檔案進行編譯。這項功能可用於一次性產生原始碼 (如果要經常使用，建議實作 Starlark 規則類別並使用 cc_common API)

允許的 srcs 檔案類型：

  • C 和 C++ 來源檔案：.c、.cc、.cpp、.cxx、.c++、.C
  • C 和 C++ 標頭檔案：.h、.hh、.hpp、.hxx、.inc、.inl、.H
  • 使用 C 前置處理器的組譯器：.S
  • 封存：.a、.pic.a
  • 「一律連結」程式庫：.lo、.pic.lo
  • 共用資料庫 (已分版本或未分版本)：.so、.so.version
  • 物件檔案：.o、.pic.o

... 以及產生這些檔案的任何規則 (例如 cc_embed_data)。 根據 gcc 慣例，不同的副檔名代表不同的程式設計語言。
data

標籤清單；預設為 []

這個程式庫在執行階段所需的檔案清單。如要查看 data 的一般註解，請參閱「大多數建構規則定義的常見屬性」。

如果 data 是產生檔案的名稱，則這個 cc_library 規則會自動依附產生規則。

如果 data 是規則名稱，則這個 cc_library 規則會自動依賴該規則，而該規則的 outs 會自動加入這個 cc_library 的資料檔案。

C++ 程式碼可以存取這些資料檔案，如下所示：


  const std::string path = devtools_build::GetDataDependencyFilepath(
      "my/test/data/file");
additional_linker_inputs

標籤清單；預設為 []

將這些檔案傳遞至 C++ 連結器指令。

例如，您可以在此提供已編譯的 Windows .res 檔案，以便嵌入二進位目標。
conlyopts

字串清單；預設為 []

將這些選項加入 C 編譯指令。適用於 "Make variable" 替換和 Bourne shell 符記化。
copts

字串清單；預設為 []

將這些選項加入 C/C++ 編譯指令。適用於 "Make variable" 替換和 Bourne shell 符記化。

這個屬性中的每個字串都會依照指定順序新增至 COPTS，然後再編譯二進位目標。標記只會影響編譯這個目標，而非其依附元件，因此請留意其他地方是否包含標頭檔案。所有路徑都應以工作區為基準，而非目前套件。在 third_party 以外的情況下，不應需要此屬性。

如果套件宣告功能 no_copts_tokenization，Bourne shell 符記化只會套用至由單一「Make」變數組成的字串。
cxxopts

字串清單；預設為 []

將這些選項新增至 C++ 編譯指令。適用於 "Make variable" 替換和 Bourne shell 符記化。
defines

字串清單；預設為 []

要新增至編譯行中的定義清單。適用於 "Make" 變數替換和 Bourne shell 符記化。每個字串都必須包含單一 Bourne 殼層符記，並在開頭加上 -D，然後新增至這個目標的編譯指令行，以及依附於該目標的每個規則。請務必謹慎操作，因為這可能會造成廣泛的影響。如有疑問，請改為將定義值新增至 local_defines。
dynamic_deps

標籤清單；預設為 []

這些是目前目標依附的其他 cc_shared_library 依附元件。

cc_shared_library 實作會使用 dynamic_deps 清單 (以傳遞方式，也就是目前目標 dynamic_deps 的 dynamic_deps) 決定哪些 cc_libraries 不應連結至傳遞 deps，因為這些 cc_libraries 已由其他 cc_shared_library 提供。
hdrs_check

字串；預設為 ""

已淘汰，無操作。
includes

字串清單；預設為 []

要新增至編譯行中的包含目錄清單。適用於 "Make 變數" 替換。每個字串都會加上套件路徑，並傳遞至 C++ 工具鍊，以便透過「include_paths」CROSSTOOL 功能進行展開。在 POSIX 系統上執行的工具鍊，如果含有一般功能定義，就會產生 -isystem path_to_package/include_entry。這項功能僅適用於不符合 Google 寫法風格的第三方程式庫 #include 陳述式。與 COPTS 不同的是，這些標記會新增至此規則和所有依附此規則的規則。(注意：不是依附的規則！)請務必謹慎操作，因為這可能會造成廣泛的影響。如有疑問，請改為在 COPTS 中加入「-I」標記。

新增的 include 路徑會包含產生的檔案，以及來源樹狀結構中的檔案。

標籤；預設為 "@bazel_tools//tools/cpp:link_extra_lib"

控制額外程式庫的連結。

根據預設，C++ 二進位檔會連結至 //tools/cpp:link_extra_lib，而 //tools/cpp:link_extra_lib 預設會依附標籤標記 //tools/cpp:link_extra_libs。如果未設定標記，這個程式庫預設為空白。設定標籤標記可連結選用依附元件，例如弱式符號的覆寫值、共用程式庫函式的攔截器，或特殊執行階段程式庫 (針對 malloc 替換，請優先使用 malloc 或 --custom_malloc)。將此屬性設為 None 會停用此行為。
linkopts

字串清單；預設為 []

將這些標記新增至 C++ 連結器指令。適用於 「Make」變數替換、 Bourne 殼層符記化和標籤展開。這個屬性中的每個字串都會在連結二進位目標之前新增至 LINKOPTS。

這個清單中每個元素的開頭不是 $ 或 -，系統會假設為 deps 中目標的標籤。該目標產生的檔案清單會附加至連結器選項。如果標籤無效，或未在 deps 中宣告，系統會回報錯誤。
linkshared

布林值；預設值為 False

建立共用程式庫。如要啟用這項屬性，請在規則中加入 linkshared=True。這個選項預設為關閉。

這個標記的存在表示連結會將 -shared 標記連結至 gcc，而產生的共用程式庫則適合載入至 Java 程式等。不過，為了建構目的，它永遠不會連結至依附的二進位檔，因為系統會假設使用 cc_binary 規則建構的共用程式庫只能由其他程式手動載入，因此不應視為 cc_library 規則的替代方案。為了提升可擴充性，建議您完全避免採用這種做法，而改為讓 java_library 依附 cc_library 規則。

如果您同時指定 linkopts=['-static'] 和 linkshared=True，您將獲得一個完全獨立的單元。如果您同時指定 linkstatic=True 和 linkshared=True，您會得到一個幾乎自給自足的單一單位。
linkstatic

布林值；預設值為 False

針對 cc_binary 和 cc_test：在靜態模式中連結二進位檔。如為 cc_library.link_static：請參閱下文。

根據預設，這個選項會為 cc_binary 開啟，其餘選項則為關閉。

如果已啟用，且這是二進位檔或測試，這個選項會指示建構工具盡可能連結 .a 而非 .so 的使用者程式庫。系統程式庫 (例如 libc，但不是 C/C++ 執行階段程式庫，請參閱下文) 仍會動態連結，沒有靜態資料庫的程式庫也是如此。因此產生的可執行檔仍會以動態方式連結，因此只有「大部分」是靜態的。

實際上有三種不同的方式可以連結可執行檔：

  • STATIC 搭配 fully_static_link 功能，其中所有項目都會以靜態方式連結，例如「gcc -static foo.o libbar.a libbaz.a -lm」。
    如要啟用這個模式，請在 features 屬性中指定 fully_static_link。
  • STATIC，其中所有使用者程式庫會以靜態方式連結 (如果有靜態版本)，但系統程式庫 (不含 C/C++ 執行階段程式庫) 會以動態方式連結，例如「gcc foo.o libfoo.a libbaz.a -lm」。
    如要啟用此模式，請指定 linkstatic=True。
  • DYNAMIC，所有程式庫都會動態連結 (如果有動態版本)，例如「gcc foo.o libfoo.so libbaz.so -lm」。
    如要啟用這個模式，請指定 linkstatic=False。

如果 features 中的 linkstatic 屬性或 fully_static_link 用於 //third_party 外，請在規則旁邊加入註解，說明原因。

如果 linkstatic 屬性用於 cc_library() 規則，其意義就會有所不同。對於 C++ 程式庫，linkstatic=True 表示只允許靜態連結，因此不會產生 .so。linkstatic=False 不會阻止建立靜態資料庫。這個屬性用於控制動態程式庫的建立作業。

在正式環境中，使用 linkstatic=False 建構的程式碼應極少。如果是 linkstatic=False，則建構工具會在 *.runfiles 區域中建立指向所依附共用程式庫的符號連結。
local_defines

字串清單；預設為 []

要新增至編譯行中的定義清單。適用於 "Make" 變數替換和 Bourne shell 符記化。每個字串都必須包含單一 Bourne 殼層符記，並在開頭加上 -D，然後新增至此目標的編譯指令行，但不新增至其依附項目。
malloc

標籤；預設為 "@bazel_tools//tools/cpp:malloc"

覆寫對 malloc 的預設依附元件。

根據預設，C++ 二進位檔會連結至 //tools/cpp:malloc，這是空白程式庫，因此二進位檔會使用 libc malloc。這個標籤必須參照 cc_library。如果編譯作業是針對非 C++ 規則，則這個選項不會有任何作用。如果指定 linkshared=True，系統會忽略此屬性的值。
module_interfaces

標籤清單；預設為 []

檔案清單會視為 C++20 模組介面。

C++ 標準對模組介面檔案副檔名沒有限制

  • Clang 使用 cppm
  • GCC 可使用任何來源檔案副檔名
  • MSVC 使用 ixx

使用方式受到 --experimental_cpp_modules 旗標的保護。
nocopts

字串；預設為 ""

從 C++ 編譯指令中移除相符的選項。適用於 "Make" 變數替換。系統會將此屬性的值解讀為規則運算式。為了編譯此規則，系統會從 COPTS 中移除任何符合此規則運算式的先前 COPTS (包括規則 copts 屬性中明確指定的值)。這個屬性不應在 third_party 以外的情況下使用或需要。除了「Make」變數替換之外，系統不會以任何方式預先處理這些值。
reexport_deps

標籤清單；預設為 []
stamp

整數；預設值為 0

是否將建構資訊編碼至二進位檔。可能的值：
  • stamp = 1：一律將建構資訊戳記到二進位檔案中，即使是在 --nostamp 版本中也是如此。請避免使用這項設定，因為這可能會導致二進位檔和任何依賴二進位檔的後續動作無法進行遠端快取。
  • stamp = 0：一律使用常數值取代建構資訊。這可提供良好的建構結果快取功能。
  • stamp = -1：版本資訊的嵌入方式由 --[no]stamp 標記控制。

除非依附元件變更，否則系統不會重新建構經過標記的二進位檔。
win_def_file

標籤；預設為 None

要傳遞至連結器的 Windows DEF 檔案。

只有在 Windows 是目標平台時，才應使用這個屬性。可在連結共用程式庫時 匯出符號。

cc_toolchain

查看規則來源 
cc_toolchain(name, all_files, ar_files, as_files, compatible_with, compiler_files, compiler_files_without_includes, coverage_files, deprecation, distribs, dwp_files, dynamic_runtime_lib, exec_compatible_with, exec_properties, exec_transition_for_inputs, features, libc_top, licenses, linker_files, module_map, objcopy_files, output_licenses, restricted_to, static_runtime_lib, strip_files, supports_header_parsing, supports_param_files, tags, target_compatible_with, testonly, toolchain_config, toolchain_identifier, toolchains, visibility)

代表 C++ 工具鍊。

此規則負責：

  • 收集執行 C++ 動作所需的所有構件。這項操作會透過 all_files、compiler_files、linker_files 或其他以 _files 結尾的屬性完成。這些屬性通常是用來將所有必要檔案納入檔案群組。
  • 為 C++ 動作產生正確的命令列。這項操作是使用 CcToolchainConfigInfo 供應器完成的 (詳情請見下文)。

使用 toolchain_config 屬性設定 C++ 工具鍊。如要進一步瞭解 C++ 工具鍊設定和工具鍊選取說明文件，請參閱這個 頁面 。

使用 tags = ["manual"] 可避免在叫用 bazel build //... 時，不必要地建構及設定工具鍊

引數

屬性
name

名稱；必填

這個目標的專屬名稱。
all_files

標籤；必填

收集所有 cc_toolchain 構件。這些構件會新增為所有 rules_cc 相關動作的輸入內容 (使用屬性中更精確的構件集的動作除外)。Bazel 會假設 all_files 是所有其他提供構件屬性的超集 (例如，連結標記編譯作業需要編譯和連結檔案，因此會採用 all_files)。

這是 cc_toolchain.files 的內容，也是所有使用 C++ 工具鍊的 Starlark 規則所使用的內容。
ar_files

標籤；預設為 None

收集封存動作所需的所有 cc_toolchain 構件。
as_files

標籤；預設為 None

收集組合動作所需的所有 cc_toolchain 構件。
compiler_files

標籤；必填

收集編譯動作所需的所有 cc_toolchain 構件。
compiler_files_without_includes

標籤；預設為 None

在支援輸入探索功能 (目前僅限 Google) 的情況下，收集編譯動作所需的所有 cc_toolchain 構件。
coverage_files

標籤；預設為 None

收集涵蓋率動作所需的所有 cc_toolchain 構件。如果未指定，系統會使用 all_files。
dwp_files

標籤；必填

收集 dwp 動作所需的所有 cc_toolchain 構件。
dynamic_runtime_lib

標籤；預設為 None

C++ 執行階段程式庫的動態程式庫構件 (例如 libstdc++.so)。

當您啟用「static_link_cpp_runtimes」功能，並且要動態連結依附元件時，就會使用這個選項。
exec_transition_for_inputs

布林值；預設值為 False

已淘汰，無操作。
libc_top

標籤；預設為 None

一系列 libc 構件，會作為編譯/連結動作的輸入內容傳遞。
linker_files

標籤；必填

收集連結動作所需的所有 cc_toolchain 構件。
module_map

標籤；預設為 None

模組圖表構件，用於模組化建構。
objcopy_files

標籤；必填

收集 objcopy 動作所需的所有 cc_toolchain 構件。
output_licenses

字串清單；預設為 []
static_runtime_lib

標籤；預設為 None

C++ 執行階段程式庫的靜態資料庫構件 (例如 libstdc++.a)。

當您啟用「static_link_cpp_runtimes」功能，並且要以靜態方式連結依附元件時，系統就會使用這個值。
strip_files

標籤；必填

收集所有去除動作所需的 cc_toolchain 構件。
supports_header_parsing

布林值；預設值為 False

如果 cc_toolchain 支援標頭剖析動作，請將此值設為 True。
supports_param_files

布林值；預設值為 True

如果 cc_toolchain 支援使用 param 檔案連結動作，請將此值設為 True。
toolchain_config

標籤；必填

提供 cc_toolchain_config_info 的規則標籤。
toolchain_identifier

字串；預設為 ""

用於將這個 cc_toolchain 與對應的 crosstool_config.toolchain 比對的 ID。

在問題 #5380 修正前，這是建議將 cc_toolchain 與 CROSSTOOL.toolchain 建立關聯的方式。這項屬性將會替換為 toolchain_config (#5380)。

cc_toolchain_suite

查看規則來源 
cc_toolchain_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)

已淘汰：此規則不會執行任何操作，且將遭到移除。

引數

屬性
name

名稱；必填

這個目標的專屬名稱。

fdo_prefetch_hints

查看規則來源 
fdo_prefetch_hints(name, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)

代表工作區中 FDO 預先擷取提示設定檔。範例：


fdo_prefetch_hints(
    name = "hints",
    profile = "//path/to/hints:profile.afdo",
)

引數

屬性
name

名稱；必填

這個目標的專屬名稱。
profile

標籤；必填

提示設定檔的標籤。提示檔案的副檔名為 .afdo。標籤也可以指向 fdo_absolute_path_profile 規則。

fdo_profile

查看規則來源 
fdo_profile(name, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, memprof_profile, profile, proto_profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)

代表工作區中的 FDO 設定檔。範例：


fdo_profile(
    name = "fdo",
    profile = "//path/to/fdo:profile.zip",
)

引數

屬性
name

名稱；必填

這個目標的專屬名稱。
memprof_profile

標籤；預設為 None

MemProf 設定檔的標籤。設定檔應具有 .profdata 副檔名 (針對已編入索引/符號化的 memprof 設定檔)，或是 .zip 副檔名 (針對內含 memprof.profdata 檔案的 ZIP 檔案)。
profile

標籤；必填

FDO 設定檔或產生該設定檔的規則的標籤。FDO 檔案可以有下列其中一個副檔名：.profraw 用於未編入索引的 LLVM 設定檔、.profdata 用於已編入索引的 LLVM 設定檔、.zip 用於儲存 LLVM profraw 設定檔、.afdo 用於 AutoFDO 設定檔、.xfdo 用於 XBinary 設定檔。標籤也可以指向 fdo_absolute_path_profile 規則。
proto_profile

標籤；預設為 None

Protobuf 設定檔的標籤。

memprof_profile

查看規則來源 
memprof_profile(name, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)

代表工作區中的 MEMPROF 設定檔。範例：


memprof_profile(
    name = "memprof",
    profile = "//path/to/memprof:profile.afdo",
)

引數

屬性
name

名稱；必填

這個目標的專屬名稱。
profile

標籤；必填

MEMPROF 設定檔的標籤。設定檔應具有 .profdata 副檔名 (針對已編入索引/符號化的 memprof 設定檔)，或是 .zip 副檔名 (針對內含 memprof.profdata 檔案的 ZIP 檔案)。標籤也可以指向 fdo_absolute_path_profile 規則。

propeller_optimize

查看規則來源 
propeller_optimize(name, cc_profile, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, ld_profile, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)

代表工作區中的 Propeller 最佳化設定檔。範例：


propeller_optimize(
    name = "layout",
    cc_profile = "//path:cc_profile.txt",
    ld_profile = "//path:ld_profile.txt"
)

引數

屬性
name

名稱；必填

這個目標的專屬名稱。
cc_profile

標籤；必填

傳遞至各種編譯動作的設定檔標籤。這個檔案的副檔名為 .txt。
ld_profile

標籤；必填

傳遞至連結動作的設定檔標籤。這個檔案的副檔名為 .txt。