可視性

問題を報告するopen_in_new ソースを表示open_in_new

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

2 種類の可視性は、他のデベロッパーがライブラリの公開 API とその実装の詳細を区別するのに役立ちます。また、ワークスペースの拡大に伴って構造がわかりやすくなります。公開 API のサポートを終了して現在のユーザーを許可し、新しいユーザーを拒否することもできます。

ターゲットの公開設定

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

ターゲット B は、同じパッケージ内にある場合、または A が B のパッケージへの可視性を付与する場合に、ターゲット A に表示されます。パッケージは、アクセスを許可するかどうかを決定するための粒度単位です。B が A に依存しているが A が B に表示されない場合、分析中に B をビルドしようとしても失敗します。

パッケージの公開設定だけでは、サブパッケージの公開設定は付与されません。パッケージとサブパッケージの詳細については、コンセプトと用語をご覧ください。

プロトタイピングでは、--check_visibility=false フラグを設定することで、ターゲットの公開設定の適用を無効にできます。送信されたコードの本番環境での使用は行わないでください。

可視性を制御する主な方法は、ルール ターゲットの visibility 属性を使用することです。このセクションでは、この属性の形式と、ターゲットの公開設定を決定する方法について説明します。

公開設定の仕様

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

• "//visibility:public": すべてのパッケージへのアクセスを許可します。（他の仕様と組み合わせることはできません）。

• "//visibility:private": 追加のアクセス権を付与しません。このパッケージのターゲットのみがこのターゲットを使用できます。（他の仕様と組み合わせることはできません）。

• "//foo/bar:__pkg__": //foo/bar へのアクセス権を付与します（サブパッケージはアクセスできません）。

• "//foo/bar:__subpackages__": //foo/bar とそのすべての直接および間接のサブパッケージへのアクセス権を付与します。

• "//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 で定義されたターゲットでは使用できません。

ベスト プラクティス: 同じパッケージの複数のセットに複数のターゲットを表示するには、各ターゲットの visibility 属性でリストを繰り返す代わりに、package_group を使用します。これにより、読みやすさが向上し、リストが同期しなくなるのを防ぐことができます。

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

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

1. 設定されている場合、visibility 属性の値。それ以外の場合は

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

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 は select() のキーで参照されている config_setting ターゲットの可視性を適用していません。このレガシー動作を削除するには、次の 2 つのフラグがあります。

• --incompatible_enforce_config_setting_visibility を使用すると、こうしたターゲットの可視性チェックが有効になります。また、移行を容易にするため、visibility を指定していない config_setting は（パッケージ レベルの default_visibility に関係なく）一般公開とみなされます。

• --incompatible_config_setting_private_default_visibility により、visibility を指定していない config_setting が、他のルール ターゲットと同様に、パッケージの default_visibility を尊重し、非公開の公開設定でフォールバックします。--incompatible_enforce_config_setting_visibility が設定されていない場合、処理は行われません。

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

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

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

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

一部のルールには暗黙的な依存関係があります。依存関係は、BUILD ファイル内ではスペル定義されないものの、そのルールのすべてのインスタンスに固有のものです。たとえば、cc_library ルールは、各ルール ターゲットから C++ コンパイラを表す実行可能ターゲットへの暗黙的な依存関係を作成します。

現在、可視性の観点から、これらの暗黙的な依存関係は他の依存関係と同様に扱われます。つまり、依存しているターゲット（C++ コンパイラなど）は、ルールのすべてのインスタンスに表示される必要があります。実際には、通常はターゲットを一般公開する必要があります。

この動作は、--incompatible_visibility_private_attributes_at_definition を設定することで変更できます。有効にすると、対象のターゲットは、暗黙的な依存関係を宣言するルールからのみ参照できます。つまり、ルールが定義されている .bzl ファイルを含むパッケージから参照できる必要があります。この例では、cc_library ルールの定義と同じパッケージに存在する限り、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() の引数は、package_group の packages 属性と同様に、パッケージ仕様のリストです。ただし、visibility() では負のパッケージ指定は指定できません。

visibility() の呼び出しは、ファイル内で 1 回だけ（関数内ではなく）トップレベルで、できれば load() ステートメントの直後に行う必要があります。

ターゲットの可視性とは異なり、デフォルトの読み込みの可視性は常に公開されています。visibility() を呼び出さないファイルは、常にワークスペースの任意の場所から読み込むことができます。パッケージの外部での使用を特に意図していない新しい .bzl ファイルの先頭に visibility("private") を追加することをおすすめします。

例

# //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 が includes 属性を介して他の package_group を組み込むことに似ています。

広く使用されるマクロを廃止するとします。既存のユーザーと、所属するチームが所有するパッケージに対してのみ表示可能にする。次のように記述します。

# //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

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