本頁面將說明使用面向的基本概念和優點,並提供簡單和進階範例。
切面可擴增建構依附元件圖表,提供額外資訊和動作。切面適用的幾個常見情況:
- 整合 Bazel 的 IDE 可使用面向收集專案相關資訊。
- 程式碼產生工具可利用各個層面,以不區分目標的方式執行輸入內容。舉例來說,
BUILD
檔案可以指定 protobuf 程式庫定義階層,而特定語言的規則可以根據特定條件,附加針對特定語言產生 protobuf 支援程式碼的動作。
顯示比例基本概念
BUILD
檔案會提供專案原始碼的說明:專案包含哪些來源檔案、應從這些檔案建構哪些構件 (目標)、這些檔案之間的相依性為何等等。Bazel 會使用這些資訊執行建構作業,也就是找出產生構件的必要動作集合 (例如執行編譯器或連結器),並執行這些動作。Bazel 會在目標之間建構相依關係圖,並查看這張圖表來收集這些動作。
請參考下列 BUILD
檔案:
java_library(name = 'W', ...)
java_library(name = 'Y', deps = [':W'], ...)
java_library(name = 'Z', deps = [':W'], ...)
java_library(name = 'Q', ...)
java_library(name = 'T', deps = [':Q'], ...)
java_library(name = 'X', deps = [':Y',':Z'], runtime_deps = [':T'], ...)
這個 BUILD
檔案定義了依附元件圖表,如下圖所示:
圖 1. BUILD
檔案依附元件圖。
Bazel 會針對上述範例中的每個目標呼叫對應的 rule (在這個範例中為「java_library」) 的實作函式,藉此分析這個依附元件圖。規則實作函式會產生動作,這些動作會建構 .jar
檔案等構件,並將位置和這些構件的名稱等資訊傳遞至 供應器中這些目標的反向依附元件。
層面與規則類似,因為它們都有實作函式,可產生動作並傳回提供者。不過,這些功能的強大之處在於依附元件圖表的建構方式。一個面向會具有實作項目,以及一份列出其沿途會傳播的所有屬性清單。請考慮沿著名為「deps」的屬性傳播的 A 層面。這個面向可套用至目標 X,產生面向應用節點 A(X)。在應用期間,A 會遞迴套用至 X 在其「deps」屬性 (A 傳播清單中的所有屬性) 中參照的所有目標。
因此,將 A 層面套用至目標 X 的單一動作,會產生目標原始依附圖表的「陰影圖表」,如下圖所示:
圖 2. 使用面向建立圖表。
只有沿著傳播集合內屬性邊緣的邊緣會遭到遮蔽,因此 runtime_deps
邊緣不會在這個例子中遭到遮蔽。接著,系統會在陰影圖表的所有節點上叫用面向實作函式,這與在原始圖表的節點上叫用規則實作方式相似。
簡單範例
以下範例說明如何以遞迴方式顯示規則的來源檔案及其所有具有 deps
屬性的依附元件。這份文件會說明面向性實作、面向性定義,以及如何從 Bazel 指令列叫用面向性。
def _print_aspect_impl(target, ctx):
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the files that make up the sources and
# print their paths.
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
print(f.path)
return []
print_aspect = aspect(
implementation = _print_aspect_impl,
attr_aspects = ['deps'],
)
我們將這個範例分成幾個部分,並逐一檢查。
切面定義
print_aspect = aspect(
implementation = _print_aspect_impl,
attr_aspects = ['deps'],
)
面向定義與規則定義類似,且使用 aspect
函式定義。
就像規則一樣,面向也有實作函式,在本例中為 _print_aspect_impl
。
attr_aspects
是規則屬性清單,可沿著該屬性傳播。在這種情況下,系統會沿著所套用規則的 deps
屬性傳播子集。
attr_aspects
的另一個常見引數是 ['*']
,這個引數會將規格套用到規則的所有屬性。
實作方面
def _print_aspect_impl(target, ctx):
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the files that make up the sources and
# print their paths.
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
print(f.path)
return []
面向實作函式與規則實作函式類似。這些方法會傳回提供者、可產生動作,並採用兩個引數:
實作函式可透過 ctx.rule.attr
存取目標規則的屬性。可透過 target
引數,檢查套用目標的目標提供的提供者。
您必須有切面才能傳回提供者清單。在這個範例中,此面向不會提供任何內容,因此會傳回空白清單。
使用指令列叫用切面
套用面向最簡單的方法,就是在指令列中使用 --aspects
引數。假設上述顯示比例是在名為 print.bzl
的檔案中定義:
bazel build //MyExample:example --aspects print.bzl%print_aspect
會將 print_aspect
套用至目標 example
,以及可透過 deps
屬性遞迴存取的所有目標規則。
--aspects
旗標會採用一個引數,也就是以 <extension file label>%<aspect top-level name>
格式指定的顯示比例。
進階範例
以下範例說明如何使用目標規則的面向,計算目標中的檔案,並可能依據副檔名篩選檔案。本節說明如何使用提供者傳回值、如何使用參數將引數傳遞至面向實作項目,以及如何從規則叫用面向。
file_count.bzl
檔案:
FileCountInfo = provider(
fields = {
'count' : 'number of files'
}
)
def _file_count_aspect_impl(target, ctx):
count = 0
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the sources counting files
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
if ctx.attr.extension == '*' or ctx.attr.extension == f.extension:
count = count + 1
# Get the counts from our dependencies.
for dep in ctx.rule.attr.deps:
count = count + dep[FileCountInfo].count
return [FileCountInfo(count = count)]
file_count_aspect = aspect(
implementation = _file_count_aspect_impl,
attr_aspects = ['deps'],
attrs = {
'extension' : attr.string(values = ['*', 'h', 'cc']),
}
)
def _file_count_rule_impl(ctx):
for dep in ctx.attr.deps:
print(dep[FileCountInfo].count)
file_count_rule = rule(
implementation = _file_count_rule_impl,
attrs = {
'deps' : attr.label_list(aspects = [file_count_aspect]),
'extension' : attr.string(default = '*'),
},
)
BUILD.bazel
檔案:
load('//:file_count.bzl', 'file_count_rule')
cc_library(
name = 'lib',
srcs = [
'lib.h',
'lib.cc',
],
)
cc_binary(
name = 'app',
srcs = [
'app.h',
'app.cc',
'main.cc',
],
deps = ['lib'],
)
file_count_rule(
name = 'file_count',
deps = ['app'],
extension = 'h',
)
切面定義
file_count_aspect = aspect(
implementation = _file_count_aspect_impl,
attr_aspects = ['deps'],
attrs = {
'extension' : attr.string(values = ['*', 'h', 'cc']),
}
)
這個範例說明如何透過 deps
屬性傳播相片。
attrs
會定義某個面向的一組屬性。公開的子集屬性會定義參數,且只能是 bool
、int
或 string
類型。針對規則套用方式的層面,int
和 string
參數必須指定 values
。這個範例包含名為 extension
的參數,可使用 '*
'、'h
' 或 'cc
' 做為值。
對於規則傳播的層面,參數值會從要求該層面的規則中取得,並使用規則的屬性 (具有相同名稱和類型)。(請參閱 file_count_rule
的定義)。
針對指令列方面,您可以使用 --aspects_parameters
旗標傳遞參數值。int
和 string
參數的 values
限制可能會省略。
層面也允許使用 label
或 label_list
類型的私人屬性。私有標籤屬性可用於針對切面產生的動作所需,指定工具或程式庫的依附元件。這個範例中並未定義私人屬性,但下列程式碼片段示範如何將工具傳入至某個面向:
...
attrs = {
'_protoc' : attr.label(
default = Label('//tools:protoc'),
executable = True,
cfg = "exec"
)
}
...
實作方面
FileCountInfo = provider(
fields = {
'count' : 'number of files'
}
)
def _file_count_aspect_impl(target, ctx):
count = 0
# Make sure the rule has a srcs attribute.
if hasattr(ctx.rule.attr, 'srcs'):
# Iterate through the sources counting files
for src in ctx.rule.attr.srcs:
for f in src.files.to_list():
if ctx.attr.extension == '*' or ctx.attr.extension == f.extension:
count = count + 1
# Get the counts from our dependencies.
for dep in ctx.rule.attr.deps:
count = count + dep[FileCountInfo].count
return [FileCountInfo(count = count)]
就像規則實作函式一樣,面向切面的實作函式會傳回可供依附元件存取的提供者結構體。
在這個範例中,FileCountInfo
定義為含有一個 count
欄位的提供者。最佳做法是使用 fields
屬性明確定義提供者的欄位。
若要為某個面向應用程式 A(X) 提供一組供應器,您必須將針對目標 X 的規則實作和面向 A 的實作,兩者供應器的集合合併起來。規則導入程序會在套用面向之前建立並凍結提供者,因此無法從面向修改。如果目標和套用至目標的層面各自為提供者提供相同類型的資料,則會發生錯誤,但 OutputGroupInfo
(只要規則和層面指定不同的輸出群組,就會合併) 和 InstrumentedFilesInfo
(取自層面) 除外。也就是說,切面實作項目可能不會傳回 DefaultInfo
。
參數和私人屬性會在 ctx
的屬性中傳遞。這個範例會參照 extension
參數,並決定要計算哪些檔案。
對於傳回的供應商,沿著傳播層面 (來自 attr_aspects
清單) 的屬性值會替換為將層面套用至這些屬性的結果。舉例來說,如果目標 X 的依附元件包含 Y 和 Z,則 A(X) 的 ctx.rule.attr.deps
會是 [A(Y), A(Z)]。在本例中,ctx.rule.attr.deps
是 Target 物件,是將層面套用至已套用層面的原始目標的「deps」所產生的結果。
在這個範例中,此面向項目會從目標的依附元件存取 FileCountInfo
供應器,累積檔案的傳遞總數。
從規則叫用切面
def _file_count_rule_impl(ctx):
for dep in ctx.attr.deps:
print(dep[FileCountInfo].count)
file_count_rule = rule(
implementation = _file_count_rule_impl,
attrs = {
'deps' : attr.label_list(aspects = [file_count_aspect]),
'extension' : attr.string(default = '*'),
},
)
規則實作項目示範如何透過 ctx.attr.deps
存取 FileCountInfo
。
規則定義會示範如何定義參數 (extension
) 並為其提供預設值 (*
)。請注意,由於在切面定義中的參數設有限制,如果預設值不是「cc
」、「h
」或「*
」,就會發生錯誤。
透過目標規則叫用切面
load('//:file_count.bzl', 'file_count_rule')
cc_binary(
name = 'app',
...
)
file_count_rule(
name = 'file_count',
deps = ['app'],
extension = 'h',
)
這裡示範如何透過規則將 extension
參數傳遞至面向。由於 extension
參數在規則實作中具有預設值,因此系統會將 extension
視為選用參數。
建構 file_count
目標時,系統會評估自身的層面,以及可透過 deps
遞迴存取的所有目標。