このページでは、Bazel の 2 つの公開設定システム（ ターゲットの公開設定と読み込みの公開設定）について説明します。
どちらのタイプの公開設定も、他のデベロッパーがライブラリの公開 API と実装の詳細を区別するのに役立ち、ワークスペースの拡大に伴って構造を適用するのに役立ちます。また、公開 API を非推奨にする際に、公開設定を使用して、現在のユーザーは許可し、新しいユーザーは拒否することもできます。
ターゲットの公開設定
ターゲットの公開設定 は、ターゲットに依存できるユーザー（つまり、
ターゲットのラベルを deps などの属性内で使用できるユーザー）を制御します。
ターゲット A は、ターゲット B と同じパッケージ内にある場合、または
A が B's パッケージに公開設定を付与する場合、ターゲット B から参照できます。したがって、アクセスを許可するかどうかを決定する
粒度はパッケージ単位になります。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 を使用します。これにより、可読性が向上し、
リストの同期が取れなくなるのを防ぐことができます。
ルール ターゲットの公開設定
ルール ターゲットの公開設定は次のとおりです。
設定されている場合は、
visibility属性の値。それ以外の場合はターゲットの
BUILDファイルのpackageステートメントのdefault_visibility引数の値（そのような宣言が存在する場合）。それ以外の場合は//visibility:private。
ベスト プラクティス: default_visibility を public に設定しないでください。プロトタイピングや小規模なコードベースでは
便利ですが、コードベースが大きくなるにつれて、誤って
公開ターゲットを作成するリスクが高まります。パッケージの公開インターフェースの一部であるターゲットを
明示的に指定することをおすすめします。
例
ファイル //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 に渡されない場合、公開設定は public になります。
exports_files を使用して、生成されたファイルの公開設定をオーバーライドすることはできません。
exports_files の呼び出しに表示されないソースファイル ターゲットの場合、
公開設定は
--incompatible_no_implicit_file_export フラグの値によって異なります。
フラグが設定されている場合、公開設定は private になります。
それ以外の場合は、以前の動作が適用されます。公開設定は
BUILDファイルのdefault_visibilityと同じになります。デフォルトの公開設定が指定されていない場合は private になります。
以前の動作に依存することは避けてください。ソースファイル ターゲットに private 以外の公開設定が必要な場合は、常に exports_files
宣言を記述してください。
ベスト プラクティス: 可能であれば、
ソース ファイルではなくルール ターゲットを公開することをおすすめします。たとえば、exports_files ファイルで .java を呼び出すのではなく、非公開の 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は、これらのターゲットの公開設定チェックを有効にします。移行を支援するため、config_settingを指定しないvisibilityは、パッケージ レベルのdefault_visibilityに関係なく、 public とみなされます。--incompatible_config_setting_private_default_visibilityを指定しないconfig_settingは、他のルール ターゲットと同様に、 パッケージのdefault_visibilityを尊重し、private の公開設定にフォールバックします。visibility--incompatible_enforce_config_setting_visibilityが設定されていない場合は、何も行いません。
以前の動作に依存することは避けてください。現在のパッケージ外で使用する config_setting は、パッケージで適切な default_visibility が指定されていない場合は、明示的な visibility を設定する必要があります。
パッケージ グループ ターゲットの公開設定
package_group ターゲットには visibility 属性がありません。常に
公開されます。
暗黙的な依存関係の公開設定
一部のルールには暗黙的な依存関係があります。これは、
BUILD ファイルに記述されていませんが、
そのルールのすべてのインスタンスに固有の依存関係です。たとえば、cc_library ルールは、各ルール ターゲットから C++ コンパイラを表す実行可能ターゲットへの
暗黙的な依存関係を作成する場合があります。
このような暗黙的な依存関係の公開設定は、ルール（またはアスペクト）が定義されている .bzl ファイルを含む
パッケージに関してチェックされます。この例では、C++ コンパイラは、定義と同じ
パッケージ内にある限り、private にできます。cc_libraryフォールバックとして、
暗黙的な依存関係が定義から参照できない場合は、
cc_library ターゲットに関してチェックされます。
この動作を変更するには、
--incompatible_visibility_private_attributes_at_definition を無効にします。
無効にすると、暗黙的な依存関係は他の依存関係と同様に扱われます。
つまり、依存しているターゲット（C++ コンパイラなど）は、ルールのすべてのインスタンスから
参照できる必要があります。実際には、通常、ターゲット
の公開設定は public にする必要があります。
ルールの使用を特定のパッケージに制限する場合は、代わりに 読み込みの公開設定を使用します。
読み込みの公開設定
読み込みの公開設定 は、現在のパッケージ外の他の
BUILD ファイルまたは .bzl ファイルから .bzl ファイルを読み込めるかどうかを制御します。
ターゲットの公開設定がターゲットでカプセル化されたソースコードを保護するのと同じように、読み込みの公開設定は .bzl
ファイルでカプセル化されたビルドロジックを保護します。たとえば、BUILD ファイルの作成者は、繰り返し使用される
ターゲット定義を .bzl ファイルのマクロにファクタリングしたいと考えるかもしれません。読み込みの
公開設定で保護されていない場合、同じワークスペース内の他の共同編集者がマクロを再利用し、マクロを変更すると他のチームのビルドが中断される可能性があります。
.bzl ファイルに、対応するソースファイル ターゲットがある場合とない場合があります。
ある場合でも、読み込みの公開設定とターゲット
の公開設定が一致するとは限りません。つまり、同じ BUILD ファイルで
.bzl ファイルを読み込むことはできますが、srcs の filegroup にリストすることはできません。
その逆も同様です。これにより、ドキュメントの生成やテストなど、
.bzl ファイルをソースコードとして使用するルールで問題が発生することがあります。
プロトタイピングでは、読み込みの公開設定の適用を無効にできます。
--check_bzl_visibility=false--check_visibility=false と同様に、送信されたコードではこれを行わないでください。
読み込みの公開設定は Bazel 6.0 以降で使用できます。
読み込みの公開設定を宣言する
.bzl ファイルの読み込みの公開設定を設定するには、ファイル内で
visibility() 関数を呼び出します。
visibility() の引数は、
packages の
package_group 属性と同様に、パッケージ仕様のリストです。ただし、visibility() は負のパッケージ
仕様を受け入れません。
visibility() の呼び出しは、ファイルごとに 1 回だけ、最上位レベル（
関数内ではない）で行う必要があります。理想的には、load() ステートメントの直後に行います。
ターゲットの公開設定とは異なり、デフォルトの読み込みの公開設定は常に public です。`visibility()` を呼び出さないファイルは、ワークスペース内のどこからでも読み込むことができます。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 が他の 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 シンボルは、
別のファイルから読み込むことはできません。これにより、private シンボルを簡単に作成できますが、これらのシンボルを信頼できるファイルの限定されたセットと共有することはできません。一方、読み込みの公開設定を使用すると、他のパッケージが
参照できるかどうかを制御できますが、アンダースコア以外のシンボルが
読み込まれないようにすることはできません。.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 リンター
ユーザーのファイルがそのディレクトリの親の下にない場合、ユーザーが internal または private という名前のディレクトリからファイルを読み込むと、警告が表示される Buildifier リンターがあります。このリンターは読み込みの公開設定機能よりも前に存在し、
ファイルが公開設定を宣言するワークスペースでは不要です。.bzl