可視性

<ph type="x-smartling-placeholder"></ph> 問題を報告する ソースを表示 夜間 · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

このページでは、Bazel の 2 つの可視化システムについて説明します。 ターゲットの公開設定と負荷の可視性。

どちらのタイプの公開設定も、他のデベロッパーが ライブラリの公開 API とその実装の詳細が表示され、構造を適用するのに役立ちます。 おすすめしますまた、一般公開を非推奨にするときに公開設定を使用することもできます。 現在のユーザーを許可し、新規ユーザーは拒否する API。

ターゲットの可視性

ターゲットの公開設定では、ターゲットに依存するユーザー、つまり、 deps などの属性内でターゲットのラベルを使用する。

ターゲット A は、同じパッケージ内にある場合、または次の場合に、ターゲット B に表示されます。 A は B のパッケージに対する可視性を付与します。したがって、パッケージは 許可するかどうかを細かく制御できます。B が A に依存している場合 ただし、A は B からは見えません。その場合、B をビルドしようとしても失敗します。 分析。

パッケージに可視性を付与しても、パッケージに可視性が付与されるわけではないことに注意してください。 サブパッケージに追加します。パッケージとサブパッケージの詳細については、以下をご覧ください。 コンセプトと用語

プロトタイピングでは、ターゲットの公開設定の適用を フラグ --check_visibility=false。これは、Google Cloud の本番環境での使用には 表示されます。

公開設定を制御する主な方法は、 visibility 属性がオン 指定します。このセクションでは、この属性の形式と、 ターゲットの可視性を決定します。

公開設定の仕様

すべてのルール ターゲットには、ラベルのリストを受け取る visibility 属性があります。各 次のいずれかの形式になります。最後のフォームを除いて 実際のターゲットに対応しない構文上のプレースホルダです。

  • "//visibility:public": すべてのパッケージへのアクセスを許可します。（組み合わせることはできない） 使用しないでください）。

  • "//visibility:private": 追加のアクセス権を付与しません。ターゲットのみ このターゲットを使用できます。（他のソリューションや specification.)

  • "//foo/bar:__pkg__": //foo/bar へのアクセスを許可します（ただし、 使用しないでください。

  • "//foo/bar:__subpackages__": //foo/bar とそのすべてにアクセス権を付与します。 直接サブパッケージと間接サブパッケージの 2 つがあります

  • "//some_pkg:my_package_group": すべてのパッケージへのアクセスを許可します。 指定された package_group の一部である。

    • パッケージ グループでは 異なる構文 パッケージを指定するだけです。パッケージグループ内では "//foo/bar:__pkg__" と "//foo/bar:__subpackages__" はそれぞれ "//foo/bar" と "//foo/bar/..." に置き換えられました。同様に "//visibility:public" と "//visibility:private" はわずか "public" です および "private"。

たとえば、//some/package:mytarget の visibility が [":__subpackages__", "//tests:__pkg__"] の場合は、どのターゲットでも使用できます。 （//some/package/... ソースツリーの一部）と、定義されたターゲット //tests/BUILD には格納されますが、//tests/integration/BUILD で定義されたターゲットによるものではありません。

おすすめの方法: 複数のターゲットを同じセットに表示する パッケージごとにリストを繰り返すのではなく、package_group を使用します。 ターゲットの visibility 属性。これにより 可読性が向上し リストが同期されなくなるのを防げます

ルール ターゲットの公開設定

ルール ターゲットの公開設定は次のとおりです。

  1. visibility 属性の値（設定されている場合）。その他

  2. 「 default_visibility 引数に、package ステートメントの ターゲットの BUILD ファイル（そのような宣言が存在する場合）。その他

  3. //visibility:private。

ベスト プラクティス: default_visibility を公開に設定しないでください。たぶん プロトタイピングや小規模なコードベースでは便利ですが、誤って パブリック ターゲットの作成は、コードベースが大きくなるにつれて増加します。自分の役割を パッケージの公開インターフェースに含まれるターゲットを明示します。

例

ファイル //frobber/bin/BUILD:

# This target is visible to everyone
cc_binary(
    name = "executable",
    visibility = ["//visibility:public"],
    deps = [":library"],
)

# This target is visible only to targets declared in the same package
cc_library(
    name = "library",
    # No visibility -- defaults to private since no
    # package(default_visibility = ...) was used.
)

# This target is visible to targets in package //object and //noun
cc_library(
    name = "subject",
    visibility = [
        "//noun:__pkg__",
        "//object:__pkg__",
    ],
)

# See package group "//frobber:friends" (below) for who can
# access this target.
cc_library(
    name = "thingy",
    visibility = ["//frobber:friends"],
)

ファイル //frobber/BUILD:

# This is the package group declaration to which target
# //frobber/bin:thingy refers.
#
# Our friends are packages //frobber, //fribber and any
# subpackage of //fribber.
package_group(
    name = "friends",
    packages = [
        "//fribber/...",
        "//frobber",
    ],
)

生成されたファイル ターゲットの公開設定

生成されたファイル ターゲットは、そのファイル ターゲットと同じ公開設定になります。 生成します。

ソースファイル ターゲットの公開設定

ソースファイル ターゲットの公開設定を明示的に設定するには、 exports_files。visibility がない場合 exports_files に渡されると、公開設定が公開されるようになります。 exports_files を使用して、生成されたファイルの公開設定をオーバーライドすることはできません。

exports_files の呼び出しにないソースファイル ターゲットの場合、 可視性はフラグの値によって --incompatible_no_implicit_file_export:

  • このフラグが設定されている場合、公開設定は非公開です。

  • それ以外の場合は、従来の動作が適用されます。公開設定は BUILD ファイルの default_visibility。デフォルトの公開設定が次の場合は非公開です。 指定されていません。

従来の動作に依存しないでください。常に exports_files を記述する 宣言します。

ベスト プラクティス: 可能であれば、特定のルールではなく、ルールのターゲットを 渡します。たとえば、.java ファイルに対して exports_files を呼び出す代わりに、 非公開ではない java_library ターゲットでファイルをラップします。一般的に、ルールのターゲットは 直接参照するのは、同じパッケージ内にあるソースファイルのみです。

例

ファイル //frobber/data/BUILD:

exports_files(["readme.txt"])

ファイル //frobber/bin/BUILD:

cc_binary(
  name = "my-program",
  data = ["//frobber/data:readme.txt"],
)

構成設定の公開設定

これまで、Bazel は以下に対する可視性を必須としていませんでした。 次の config_setting 個のターゲット: select() のキーで参照されます。そこで、 は、この従来の動作を削除する 2 つのフラグです。

  • --incompatible_enforce_config_setting_visibility これらのターゲットの可視性チェックを有効にします。移行を支援するために また、visibility を指定していない config_setting も 公開と見なされます（パッケージ レベルの default_visibility は関係ありません）。

  • --incompatible_config_setting_private_default_visibility visibility を指定していない config_setting は、 パッケージの default_visibility を使用し、非公開の公開設定にフォールバックできます。 他のルール ターゲットと同じように使用できます。次の場合は NoOps である --incompatible_enforce_config_setting_visibility は設定されていません。

従来の動作に依存しないでください。以下を対象とした config_setting 現在のパッケージの外部で使用する場合は、明示的な visibility を指定する必要があります。 パッケージで適切な default_visibility がまだ指定されていない。

パッケージ グループ ターゲットの公開設定

package_group ターゲットには visibility 属性がありません。常に 一般公開されます。

暗黙的な依存関係の可視性

一部のルールには暗黙的な依存関係があります。 BUILD ファイルに記述されていないものの本質的に依存関係があり、 表示されます。たとえば、cc_library ルールにより、 各ルール ターゲットから実行可能なターゲットへの暗黙的な依存関係 C++ コンパイラを表します。

このような暗黙的な依存関係の可視性は、Terraform 構成の ルール（またはアスペクト）が定義されている .bzl ファイルを含むパッケージ。イン この例では、C++ コンパイラは、同じ環境にある限り非公開にできます。 cc_library ルールの定義として使用します。代わりに 暗黙的な依存関係は定義からは見えません。暗黙的な依存関係は cc_library ターゲットを基準として考慮されます。

この動作を変更するには、 --incompatible_visibility_private_attributes_at_definition。 無効にすると、暗黙的な依存関係は他の依存関係と同様に扱われます。 つまり、依存するターゲット（C++ コンパイラなど）は、 すべてのインスタンスに表示されます。実際には、これは通常 公開設定が必要です。

ルールの使用を特定のパッケージに制限する場合は、次のコマンドを使用します。 読み込み可視性を使用してください。

負荷の可視性

読み込みの可視性は、.bzl ファイルを他の場所から読み込めるかどうかを制御します。 BUILD または .bzl ファイル。

ターゲットの可視性が、カプセル化されたソースコードを保護するのと同様に、 ターゲットごとの負荷の可視性により、.bzl によってカプセル化されたビルドロジックが保護される できます。たとえば、BUILD ファイルの作成者は、 .bzl ファイル内のマクロに変換します。負荷の保護なし 他の共同編集者によってマクロが再利用され、 その場合、マクロを変更すると他のチームのデータが破損し、説明します。

.bzl ファイルには、対応するソースファイルのターゲットが存在する場合と存在しない場合があります。 含まれている場合、負荷の可視性とターゲットが 表示されます。つまり、同じ BUILD ファイルで .bzl ファイルですが、filegroup の srcs にリストされていない場合、 といったことができますそのため、カスタム アルゴリズムを消費するルールで ドキュメントの生成やテストに使用するソースコードとしての .bzl ファイル。

プロトタイピングでは、負荷の可視性の適用を無効にするために、 --check_bzl_visibility=false。--check_visibility=false と同様に、この処理は 提出されたコードの処理は行われません。

負荷の可視性は、Bazel 6.0 以降で利用できます。

負荷の可視性の宣言

.bzl ファイルの読み込み可視性を設定するには、 visibility() 関数をファイル内から呼び出します。 visibility() の引数は、次のようなパッケージ仕様のリストです。 次の packages 属性: package_group。ただし、visibility() ではネガティブな荷物は受け付けておりません 仕様。

visibility() の呼び出しは、ファイルごとに 1 回だけトップレベルで行う必要があります。 load() ステートメントの直後に置くのが理想的です。

ターゲットの公開設定とは異なり、デフォルトの負荷の公開設定は常に公開です。ファイル visibility() を呼び出さないオブジェクトは、常に できます。visibility("private") を名前の先頭に追加すると、 新しい .bzl ファイルが含まれていることを確認します。

例

# //mylib/internal_defs.bzl

# Available to subpackages and to mylib's tests.
visibility(["//mylib/...", "//tests/mylib/..."])

def helper(...):
    ...

# //mylib/rules.bzl

load(":internal_defs.bzl", "helper")
# Set visibility explicitly, even though public is the default.
# Note the [] can be omitted when there's only one entry.
visibility("public")

myrule = rule(
    ...
)

# //someclient/BUILD

load("//mylib:rules.bzl", "myrule")          # ok
load("//mylib:internal_defs.bzl", "helper")  # error

...

負荷の可視性の実践

このセクションでは、負荷の可視性の宣言を管理するためのヒントについて説明します。

可視性の因数分解

複数の .bzl ファイルの公開設定を同じにする必要がある場合は、次のようにすることをおすすめします。 パッケージ仕様を共通のリストに因数分解します。例:

# //mylib/internal_defs.bzl

visibility("private")

clients = [
    "//foo",
    "//bar/baz/...",
    ...
]

# //mylib/feature_A.bzl

load(":internal_defs.bzl", "clients")
visibility(clients)

...

# //mylib/feature_B.bzl

load(":internal_defs.bzl", "clients")
visibility(clients)

...

これにより、さまざまな .bzl ファイル間の意図しない歪みを防ぐことができます。 示します。また、clients リストが大きい場合にも読みやすくなります。

作成時の公開設定

場合によっては、許可リストに登録された許可リストに .bzl ファイルを 複数の小さな許可リストで構成されますこれも package_group は、次を介して他の package_group を組み込むことができます。 includes 属性。

広く使用されているマクロを廃止するとします。表示のみ可能にしたい 自分のチームが所有するパッケージに公開されます。たとえば、次のように記述します。

# //mylib/macros.bzl

load(":internal_defs.bzl", "our_packages")
load("//some_big_client:defs.bzl", "their_remaining_uses)

# List concatenation. Duplicates are fine.
visibility(our_packages + their_remaining_uses)

パッケージ グループによる重複排除

ターゲットの可視性とは異なり、負荷の可視性を package_group。両方のターゲットに同じ許可リストを再利用したい場合 公開設定を行うには、パッケージのリストを 仕様を .bzl ファイルに変換していますが、どちらの種類の宣言でも、 できます。可視性の因数分解の例からの構築 上記のように、次のように記述します。

# //mylib/BUILD

load(":internal_defs", "clients")

package_group(
    name = "my_pkg_grp",
    packages = clients,
)

これは、リストに除外パッケージが含まれていない場合にのみ機能します。 仕様。

個々のシンボルを保護する

名前がアンダースコアで始まる Starlark シンボルは、 作成します。これにより、非公開シンボルを簡単に作成できますが、 これらのシンボルを、信頼できる一部のファイルと共有できます。反対側 負荷の可視性により、他のパッケージが何を認識するかを .bzl file。ただし、アンダースコア以外の記号を 表示されます。

これら 2 つの機能を組み合わせることで、きめ細かい管理が可能です。

# //mylib/internal_defs.bzl

# Can't be public, because internal_helper shouldn't be exposed to the world.
visibility("private")

# Can't be underscore-prefixed, because this is
# needed by other .bzl files in mylib.
def internal_helper(...):
    ...

def public_util(...):
    ...

# //mylib/defs.bzl

load(":internal_defs", "internal_helper", _public_util="public_util")
visibility("public")

# internal_helper, as a loaded symbol, is available for use in this file but
# can't be imported by clients who load this file.
...

# Re-export public_util from this file by assigning it to a global variable.
# We needed to import it under a different name ("_public_util") in order for
# this assignment to be legal.
public_util = _public_util

bzl-visibility Buildifier lint

Buildifier lint が存在します。 ユーザーが internal という名前のディレクトリからファイルを読み込むと警告を表示する または private（ユーザーのファイル自体がその親の下位にない場合） されます。この lint は読み込みの可視性機能より前から存在するため、 .bzl ファイルで公開設定を宣言するワークスペース