長寬比

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

本頁面將說明使用切面的基礎知識和好處,並提供簡單和進階範例。

您可以使用面向,透過額外資訊和動作擴充建構依附元件圖表。以下是一些可使用面向的常見情境:

  • 整合 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 會針對上述範例中的每個目標,為相應的規則 (在本例中為「java_library」) 呼叫實作函式,藉此分析這個相依關係圖。規則實作函式會產生動作,這些動作會建構 .jar 檔案等構件,並將位置和這些構件的名稱等資訊傳遞至 供應器中這些目標的反向依附元件。

層面與規則類似,因為它們都有實作函式,可產生動作並傳回提供者。不過,這些功能的強大之處在於依附元件圖表的建構方式。一個面向會具有實作項目,以及一份列出其沿途會傳播的所有屬性清單。假設有一個面向 A,會沿著名為「deps」的屬性傳播。這個面向可套用至目標 X,產生面向應用節點 A(X)。在應用期間,A 會遞迴套用至 X 在其「deps」屬性 (A 傳播清單中的所有屬性) 中參照的所有目標。

因此,將 A 層面套用至目標 X 的單一動作,會產生目標原始依附圖表的「陰影圖表」,如下圖所示:

使用 Aspect 建構圖表

圖 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 []

面向實作函式與規則實作函式類似。其會傳回「提供者」、產生動作,並採用兩個引數:

  • target:要套用特徵的目標
  • ctx:可用於存取屬性及產生輸出內容和動作的 ctx 物件。

實作函式可以透過 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 定義切面的一組屬性。公開切面屬性為 string 類型,稱為參數。參數必須指定 values 屬性。這個範例包含名為 extension 的參數,可使用 '*'、'h' 或 'cc' 做為值。

切面的參數值取自要求切面規則的相同名稱字串屬性 (請參閱 file_count_rule 的定義)。由於沒有可定義參數的語法,因此無法透過指令列使用含有參數的部分。

層面也允許使用 labellabel_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 遞迴存取的所有目標。