안정적인 출시 문서를 보려면 '버전이 지정된 문서' 드롭다운을 사용하세요. 기본 보기에는 HEAD의 최신 버전이 반영됩니다.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

공개 상태

이 페이지에서는 Bazel의 두 가지 공개 상태 시스템인 대상 가시성과 부하 가시성을 다룹니다.

두 유형의 공개 상태 모두 다른 개발자가 라이브러리의 공개 API와 구현 세부정보를 구분하는 데 도움이 되며, 작업공간이 커짐에 따라 구조를 적용할 수 있습니다. 또한 공개 API를 지원 중단할 때 현재 사용자는 허용하고 새로운 사용자는 거부하도록 공개 API를 사용할 수 있습니다.

타겟 노출 상태

타겟 공개 상태는 타겟을 기반으로 할 수 있는 사용자, 즉 deps와 같은 속성 내에서 타겟의 라벨을 사용할 수 있는 사용자를 제어합니다.

타겟 A는 타겟 B가 동일한 패키지에 있거나 A가 B의 패키지에 공개 상태를 부여하는 경우 타겟 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를 사용하세요. 이렇게 하면 가독성이 높아지고 목록이 동기화되지 않는 것을 방지할 수 있습니다.

권장사항: 다른 팀의 프로젝트에 가시성을 부여할 때 프로젝트가 발전하고 새로운 하위 패키지가 추가될 때 불필요한 가시성 이탈을 방지하려면 __pkg__보다 __subpackages__를 사용하는 것이 좋습니다.

규칙 대상 공개 상태

규칙 대상의 공개 상태는 다음과 같습니다.

visibility 속성의 값입니다(설정된 경우).
타겟의 BUILD 파일에 있는 package 문의 default_visibility 인수의 값(이러한 선언이 있는 경우)
//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 대상에 대한 공개 상태를 적용하지 않았습니다. 이 기존 동작을 삭제하는 플래그 두 개가 있습니다.

--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가 설정되어 있지 않으면 작동하지 않습니다.

레거시 동작에 의존하지 마세요. 현재 패키지 외부에서 사용할 모든 config_setting에는 명시적 visibility가 있어야 합니다(패키지가 적절한 default_visibility를 아직 지정하지 않은 경우).

패키지 그룹 대상 공개 상태

package_group 타겟에 visibility 속성이 없습니다. 항상 공개적으로 표시됩니다.

암시적 종속 항목의 공개 상태

일부 규칙에는 암시적 종속 항목이 있습니다. 암시적 종속 항목은 BUILD 파일에 명시되어 있지 않지만 해당 규칙의 모든 인스턴스에 내재된 종속 항목입니다. 예를 들어 cc_library 규칙은 각 규칙 대상에서 C++ 컴파일러를 나타내는 실행 가능한 대상에 대한 암시적 종속 항목을 만들 수 있습니다.

이러한 암시적 종속 항목의 공개 상태는 규칙 (또는 관점)이 정의된 .bzl 파일이 포함된 패키지와 관련하여 확인됩니다. 이 예에서 C++ 컴파일러는 cc_library 규칙의 정의와 동일한 패키지에 있는 한 비공개일 수 있습니다. 암시적 종속 항목이 정의에 표시되지 않으면 cc_library 타겟과 관련하여 확인됩니다.

규칙 사용을 특정 패키지로 제한하려면 로드 공개 상태를 대신 사용하세요.

로드 공개 상태

로드 가시성은 .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() 호출은 함수 내부가 아닌 최상위 수준에서 파일당 한 번만 발생해야 하며 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가 표시될 수 있는 다른 패키지를 제어할 수 있지만 밑줄이 없는 기호가 로드되는 것을 막을 수는 없습니다.

다행히 이 두 기능을 결합하여 세밀하게 제어할 수 있습니다.

# //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 빌드 도구 린트

사용자의 파일이 디렉터리의 상위 요소 아래에 있지 않을 때 사용자가 internal 또는 private 디렉터리에서 파일을 로드하는 경우 경고를 제공하는 빌드 도구 린트가 있습니다. 이 린트는 로드 공개 상태 기능 이전에 발생하며 .bzl 파일이 공개 상태를 선언하는 작업공간에서는 필요하지 않습니다.