規則
- cc_binary
- cc_import
- cc_library
- cc_proto_library
- fdo_prefetch_hints
- fdo_profile
- propeller_optimize
- cc_test
- cc_toolchain
- cc_toolchain_suite
cc_binary
cc_binary(name, deps, srcs, data, additional_linker_inputs, args, compatible_with, copts, defines, deprecation, distribs, env, exec_compatible_with, exec_properties, features, includes, licenses, linkopts, linkshared, linkstatic, local_defines, malloc, nocopts, output_licenses, restricted_to, stamp, tags, target_compatible_with, testonly, toolchains, visibility, win_def_file)
隱式輸出目標
name.stripped
(僅在明確要求時建構):精簡的二進位檔版本。strip -g
會在二進位檔上執行,以移除偵錯符號。您可以使用--stripopt=-foo
在指令列中提供其他移除選項。只有在明確要求時,才會建構此輸出內容。name.dwp
(僅在明確要求時建構):如果已啟用 Fission:適用於遠端部署二進位檔的偵錯資訊套件檔案。其他:空白檔案。
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
deps
|
目標可以是 |
srcs
|
系統會編譯所有 系統不會編譯 所有 如果規則的名稱位於
允許的
...以及產生這些檔案的任何規則。 不同的擴充功能會根據 gcc 慣例表示不同的程式設計語言。 |
additional_linker_inputs
|
舉例來說,您可以在這裡提供經過編譯的 Windows .res 檔案,以嵌入二進位檔目標中。 |
copts
|
此屬性中的每個字串都會按照指定順序新增至
如果套件宣告了功能
|
defines
|
-D ,並新增至這個目標的編譯指令列,以及依附於該目標的所有規則。但請小心謹慎,以免影響深遠。如有疑慮,請改為將定義值新增至 local_defines 。 |
includes
|
需要使用「Make 變數」替代。每個字串前面都會加上 標頭必須新增至 srcs 或 hdrs,否則在採用沙箱機制編譯時,相依規則將無法提供給相依規則 (預設值)。 |
linkopts
|
LINKOPTS ,然後再連結二進位目標。
系統會假設這個清單中每個不是以 |
linkshared
|
linkshared=True 。這個選項預設為關閉。
出現這個標記時,代表連結是透過
如果同時指定 |
linkstatic
|
cc_binary 和 cc_test :在靜態模式下連結二進位檔。如為 cc_library.linkstatic :請參閱下文。
根據預設,系統會針對
如果啟用,且這是二進位檔或測試,這個選項會盡可能指示建構工具針對使用者程式庫連結 連結執行檔的方法有很多種:
如果用於
如果為 |
local_defines
|
-D ,並新增至這個目標的編譯指令列,而非其相依項。 |
malloc
|
根據預設,C++ 二進位檔會與 |
nocopts
|
COPTS (包括規則的 copts 屬性明確指定的值),系統都會從 COPTS 中移除,以便編譯這項規則。
這項屬性很少需要用到。 |
stamp
|
除非二進位檔的依附元件變更,否則系統「不會」重新建立經過加載的二進位檔。 |
win_def_file
|
只有在 Windows 為目標平台時,才能使用這個屬性。您可以在連結共用程式庫時,使用此項目來 匯出符號。 |
cc_import
cc_import(name, data, hdrs, alwayslink, compatible_with, deprecation, distribs, features, interface_library, licenses, restricted_to, shared_library, static_library, system_provided, tags, target_compatible_with, testonly, 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 = 1, )2. 連結共用資料庫 (Unix)
cc_import( name = "mylib", hdrs = ["mylib.h"], shared_library = "libmylib.so", )3. 連結共用程式庫與介面程式庫 (Windows)
cc_import( name = "mylib", hdrs = ["mylib.h"], # mylib.lib is a 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
(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 = 1, )5. 連結至靜態或共用資料庫
在 Unix 上:
cc_import( name = "mylib", hdrs = ["mylib.h"], static_library = "libmylib.a", shared_library = "libmylib.so", ) # first will link to libmylib.a cc_binary( name = "first", srcs = ["first.cc"], deps = [":mylib"], linkstatic = 1, # default value ) # second will link to libmylib.so cc_binary( name = "second", srcs = ["second.cc"], deps = [":mylib"], linkstatic = 0, )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", ) # first will link to libmylib.lib cc_binary( name = "first", srcs = ["first.cc"], deps = [":mylib"], linkstatic = 1, # default value ) # second will link to mylib.dll through mylib.lib cc_binary( name = "second", srcs = ["second.cc"], deps = [":mylib"], linkstatic = 0, )
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
hdrs
|
|
alwayslink
|
如果因為已知問題導致一律連結無法在 Windows 上使用 VS 2017,請將 VS 2017 升級至最新版本。 |
interface_library
|
允許的檔案類型: |
shared_library
|
允許的檔案類型: |
static_library
|
允許的檔案類型: |
system_provided
|
interface_library ,而 shared_library 應為空白。 |
cc_library
cc_library(name, deps, srcs, data, hdrs, additional_compiler_inputs, additional_linker_inputs, alwayslink, compatible_with, copts, defines, deprecation, distribs, exec_compatible_with, exec_properties, features, implementation_deps, include_prefix, includes, licenses, linkopts, linkstamp, linkstatic, local_defines, nocopts, restricted_to, strip_include_prefix, tags, target_compatible_with, testonly, textual_hdrs, toolchains, visibility, win_def_file)
標頭納入檢查
建構中使用的所有標頭檔案都必須在 cc_*
規則的 hdrs
或 srcs
中宣告。這是強制執行的。
針對 cc_library
規則,hdrs
中的標頭構成程式庫的公開介面,可從程式庫本身的 hdrs
和 srcs
檔案,以及在 deps
中列出程式庫的 cc_*
規則和 cc_*
規則中的檔案直接加入。hdrs
srcs
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.h | bar.h |
foo.cc | foo.h bar.h |
bar.h | bar-impl.h baz.h |
Bar-impl.h | bar.h baz.h |
bar.cc | bar.h bar-impl.h baz.h |
baz.h | baz-impl.h |
baz-impl.h | baz.h |
baz.cc | baz.h baz-impl.h |
納入檢查規則僅適用於直接納入項目。在上述範例中,foo.cc
可以加入 bar.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 目前無法區分直接和遞移納入項目,因此無法偵測檔案中非法直接納入標頭的錯誤情況。舉例來說,如果上述範例中的 foo.cc
直接包含 baz.h
,Bazel 不會抱怨。這可能違法,因為 foo
不會直接依賴 baz
。目前不會產生錯誤,但日後可能會新增這類錯誤檢查功能。
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
deps
|
目標可以是 |
srcs
|
系統會編譯所有 系統不會編譯 所有 如果規則的名稱位於
允許的
...以及產生這些檔案的任何規則。 不同的擴充功能會根據 gcc 慣例表示不同的程式設計語言。 |
hdrs
|
如要宣告用於描述程式庫介面的標頭檔案,強烈建議您使用此位置。凡是在這項規則或獨立規則中的來源,都能加入這些標頭。
如果標頭不應由這個程式庫的用戶端加入,則即使標頭已包含在已發布的標頭中,仍應改為列於 |
additional_compiler_inputs
|
|
additional_linker_inputs
|
舉例來說,您可以在這裡提供經過編譯的 Windows .res 檔案,以嵌入二進位檔目標中。 |
alwayslink
|
srcs 所列檔案的所有項目檔案中連結,即使部分不包含二進位檔參照的符號也一樣。如果二進位檔中的程式碼未明確呼叫程式碼 (例如程式碼會註冊以接收某些服務提供的部分回呼),這項功能就非常實用。如果因為已知問題導致一律連結無法在 Windows 上使用 VS 2017,請將 VS 2017 升級至最新版本。 |
copts
|
此屬性中的每個字串都會按照指定順序新增至
如果套件宣告了功能
|
defines
|
-D ,並新增至這個目標的編譯指令列,以及依附於該目標的所有規則。但請小心謹慎,以免影響深遠。如有疑慮,請改為將定義值新增至 local_defines 。 |
implementation_deps
|
deps 不同,這些程式庫的標頭和包含的路徑 (及其所有遞移依附元件) 只會用於編譯這個程式庫,而不會用於依賴這個程式庫的程式庫。以 implementation_deps 指定的程式庫仍會在依附這個程式庫的二進位目標中保持連結狀態。目前只能使用 cc_Library,且受到 |
include_prefix
|
設定完成後,即可透過此屬性值前面的存放區相關路徑存取這項規則 系統會先移除 |
includes
|
需要使用「Make 變數」替代。每個字串前面都會加上 標頭必須新增至 srcs 或 hdrs,否則在採用沙箱機制編譯時,相依規則將無法提供給相依規則 (預設值)。 |
linkopts
|
LINKOPTS ,然後再連結二進位目標。
系統會假設這個清單中每個不是以 |
linkstamp
|
base 套件才需要使用這個選項。 |
linkstatic
|
cc_binary 和 cc_test :在靜態模式下連結二進位檔。如為 cc_library.linkstatic :請參閱下文。
根據預設,系統會針對
如果啟用,且這是二進位檔或測試,這個選項會盡可能指示建構工具針對使用者程式庫連結 連結執行檔的方法有很多種:
如果用於
如果為 |
local_defines
|
-D ,並新增至這個目標的編譯指令列,而非其相依項。 |
nocopts
|
COPTS (包括規則的 copts 屬性明確指定的值),系統都會從 COPTS 中移除,以便編譯這項規則。
這項屬性很少需要用到。 |
strip_include_prefix
|
設定後,使用者可在路徑中存取這項規則的 如果是相對路徑,則會以套件相關路徑的形式提供。如果是絕對路徑,系統會視為存放區相關路徑。 移除這個前置字串後,系統就會新增 |
textual_hdrs
|
這是宣告無法自行編譯的標頭檔案的位置。也就是說,這些必須一律以文字方式納入其他來源檔案,才能建構有效的程式碼。 |
win_def_file
|
只有在 Windows 為目標平台時,才能使用這個屬性。您可以在連結共用程式庫時,使用此項目來 匯出符號。 |
cc_proto_library
cc_proto_library(name, deps, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, restricted_to, tags, target_compatible_with, testonly, visibility)
cc_proto_library
會從 .proto
檔案產生 C++ 程式碼。
deps
必須指向 proto_library
規則。
範例:
cc_library( name = "lib", deps = [":foo_cc_proto"], ) cc_proto_library( name = "foo_cc_proto", deps = [":foo_proto"], ) proto_library( name = "foo_proto", )
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
deps
|
proto_library 規則清單。
|
fdo_prefetch_hints
fdo_prefetch_hints(name, compatible_with, deprecation, distribs, features, licenses, profile, restricted_to, tags, target_compatible_with, testonly, visibility)
代表位於工作區或指定絕對路徑的 FDO 預先擷取提示設定檔。示例:
fdo_prefetch_hints( name = "hints", profile = "//path/to/hints:profile.afdo", ) fdo_profile( name = "hints_abs", absolute_path_profile = "/absolute/path/profile.afdo", )
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
profile
|
|
fdo_profile
fdo_profile(name, absolute_path_profile, compatible_with, deprecation, distribs, features, licenses, profile, proto_profile, restricted_to, tags, target_compatible_with, testonly, visibility)
代表在工作區或指定絕對路徑中的 FDO 設定檔。示例:
fdo_profile( name = "fdo", profile = "//path/to/fdo:profile.zip", ) fdo_profile( name = "fdo_abs", absolute_path_profile = "/absolute/path/profile.zip", )
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
absolute_path_profile
|
|
profile
|
|
proto_profile
|
|
propeller_optimize
propeller_optimize(name, compatible_with, deprecation, distribs, features, ld_profile, licenses, restricted_to, tags, target_compatible_with, testonly, visibility)
代表工作區中的 Propeller 最佳化設定檔。示例:
propeller_optimize( name = "layout", cc_profile = "//path:cc_profile.txt", ld_profile = "//path:ld_profile.txt" ) propeller_optimize( name = "layout_absolute", absolute_cc_profile = "/absolute/cc_profile.txt", absolute_ld_profile = "/absolute/ld_profile.txt" )
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
ld_profile
|
|
cc_test
cc_test(name, deps, srcs, data, additional_linker_inputs, args, compatible_with, copts, defines, deprecation, distribs, env, env_inherit, exec_compatible_with, exec_properties, features, flaky, includes, licenses, linkopts, linkstatic, local, local_defines, malloc, nocopts, restricted_to, shard_count, size, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility, win_def_file)
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
deps
|
目標可以是 |
srcs
|
系統會編譯所有 系統不會編譯 所有 如果規則的名稱位於
允許的
...以及產生這些檔案的任何規則。 不同的擴充功能會根據 gcc 慣例表示不同的程式設計語言。 |
additional_linker_inputs
|
舉例來說,您可以在這裡提供經過編譯的 Windows .res 檔案,以嵌入二進位檔目標中。 |
copts
|
此屬性中的每個字串都會按照指定順序新增至
如果套件宣告了功能
|
defines
|
-D ,並新增至這個目標的編譯指令列,以及依附於該目標的所有規則。但請小心謹慎,以免影響深遠。如有疑慮,請改為將定義值新增至 local_defines 。 |
includes
|
需要使用「Make 變數」替代。每個字串前面都會加上 標頭必須新增至 srcs 或 hdrs,否則在採用沙箱機制編譯時,相依規則將無法提供給相依規則 (預設值)。 |
linkopts
|
LINKOPTS ,然後再連結二進位目標。
系統會假設這個清單中每個不是以 |
linkstatic
|
cc_binary 和 cc_test :在靜態模式下連結二進位檔。如為 cc_library.linkstatic :請參閱下文。
根據預設,系統會針對
如果啟用,且這是二進位檔或測試,這個選項會盡可能指示建構工具針對使用者程式庫連結 連結執行檔的方法有很多種:
如果用於
如果為 |
local_defines
|
-D ,並新增至這個目標的編譯指令列,而非其相依項。 |
malloc
|
根據預設,C++ 二進位檔會與 |
nocopts
|
COPTS (包括規則的 copts 屬性明確指定的值),系統都會從 COPTS 中移除,以便編譯這項規則。
這項屬性很少需要用到。 |
stamp
|
除非二進位檔的依附元件變更,否則系統「不會」重新建立經過加載的二進位檔。 |
win_def_file
|
只有在 Windows 為目標平台時,才能使用這個屬性。您可以在連結共用程式庫時,使用此項目來 匯出符號。 |
cc_toolchain
cc_toolchain(name, all_files, ar_files, as_files, compatible_with, compiler, compiler_files, compiler_files_without_includes, coverage_files, cpu, deprecation, distribs, dwp_files, dynamic_runtime_lib, exec_transition_for_inputs, features, libc_top, licenses, linker_files, module_map, objcopy_files, restricted_to, static_runtime_lib, strip_files, supports_header_parsing, supports_param_files, tags, target_compatible_with, testonly, toolchain_config, toolchain_identifier, visibility)
代表 C++ 工具鍊。
這項規則是指:
-
收集執行 C++ 動作所需的所有構件。方法是使用
all_files
、compiler_files
、linker_files
等屬性,或是結尾為_files
的其他屬性。這些是最常見的檔案群組,用來雜亂所有必要檔案。 -
為 C++ 動作產生正確的指令列。方法是透過
CcToolchainConfigInfo
供應商完成 (詳情如下)。
使用 toolchain_config
屬性設定 C++ 工具鍊。如需完整的 C++ 工具鍊設定和工具鍊選取說明文件,也請參閱這個
頁面
。
使用 tags = ["manual"]
,避免在叫用 bazel build //...
時不必要的工具鍊建構及設定
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
all_files
|
all_files 是所有其他提供構件屬性的超集 (例如 linktamp 編譯需要編譯和連結檔案,因此會採用 all_files )。
這是 |
ar_files
|
這個集合列出了封存動作所需的所有 cc_toolchain 成果。 |
as_files
|
收藏組裝動作所需的所有 cc_toolchain 構件。 |
compiler
|
toolchain_identifier 屬性。
從 CROSSTOOL 遷移至 Starlark
之後,這項指令會取消作業,並於 #7075前移除。
設定後,系統就會使用這個指令執行 crosstool_config.toolchain 選取。這項設定的優先順序高於 --cpu Bazel 選項。 |
compiler_files
|
|
compiler_files_without_includes
|
|
coverage_files
|
|
cpu
|
設定後,系統就會使用這個指令執行 crosstool_config.toolchain 選取。這項設定的優先順序高於 --cpu Bazel 選項。 |
dwp_files
|
|
dynamic_runtime_lib
|
如果已啟用「static_link_cpp_runtimes」功能,並動態連結依附元件,系統就會使用此這個參數。 |
exec_transition_for_inputs
|
|
libc_top
|
|
linker_files
|
|
module_map
|
|
objcopy_files
|
|
static_runtime_lib
|
如果已啟用「static_link_cpp_runtimes」功能,且我們要以靜態方式連結依附元件,系統就會使用這個值。 |
strip_files
|
|
supports_header_parsing
|
|
supports_param_files
|
|
toolchain_config
|
cc_toolchain_config_info 的規則標籤。 |
toolchain_identifier
|
在問題 #5380 修正之前,建議您使用這個方法將 |
cc_toolchain_suite
cc_toolchain_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, toolchains, visibility)
代表一組 C++ 工具鍊。
這項規則是指:
- 收集所有相關的 C++ 工具鍊。
-
根據傳遞至 Bazel 的
--cpu
和--compiler
選項,選取一個工具鍊。
如需完整的 C++ 工具鍊設定和工具鍊選取說明文件,也請參閱這個 頁面 。
引數
屬性 | |
---|---|
name |
此目標的專屬名稱。 |
toolchains
|
cc_toolchain 標籤的對應。只有 --cpu 傳遞至 Bazel 時,系統就會使用「<cpu>」,如果 --cpu 和 --compiler 皆傳遞至 Bazel,系統就會使用「<cpu>|<compiler>」。範例:
cc_toolchain_suite( name = "toolchain", toolchains = { "piii|gcc": ":my_cc_toolchain_for_piii_using_gcc", "piii": ":my_cc_toolchain_for_piii_using_default_compiler", }, ) |