Note: Historically, all modules had the .bzl suffix, but this is no longer true now that Bazel * supports the .scl dialect. In identifiers, code comments, and documentation, you should generally * assume any "bzl" term could mean a .scl file as well. * *
The key consists of an absolute {@link Label} and the context in which the load occurs. The * Label should not reference the special {@code external} package. * *
This value is also used to represent the special prelude file that may be implicitly loaded
* and sourced by BUILD files. The prelude file need not end in ".bzl".
*/
public class BzlLoadValue implements SkyValue {
private final Module module; // .bzl module (and indirectly, the entire load DAG)
// TODO(brandjon): Is this field redundant with BazelModuleContext#bzlTransitiveDigest, accessible
// from the Module as client data?
private final byte[] transitiveDigest; // of .bzl file and load dependencies
private final BzlVisibility bzlVisibility;
@VisibleForTesting
public BzlLoadValue(Module module, byte[] transitiveDigest, BzlVisibility bzlVisibility) {
this.module = checkNotNull(module);
this.transitiveDigest = checkNotNull(transitiveDigest);
this.bzlVisibility = checkNotNull(bzlVisibility);
}
/** Returns the .bzl module. */
public Module getModule() {
return module;
}
/** Returns the digest of the .bzl module and its transitive load dependencies. */
public byte[] getTransitiveDigest() {
return transitiveDigest;
}
/** Returns the visibility of this module for the purpose of {@code load()} statements. */
public BzlVisibility getBzlVisibility() {
return bzlVisibility;
}
private static final SkyKeyInterner For {@link KeyForBuiltins}, it must begin with {@code @_builtins//:}. (It is legal for
* other keys to use {@code @_builtins}, but since no real repo by that name may be defined,
* they won't evaluate to a successful result.)
*/
abstract Label getLabel();
/** Returns true if this is a request for the special BUILD prelude file. */
boolean isBuildPrelude() {
return false;
}
/** Returns true if this is a request for a builtins bzl file. */
boolean isBuiltins() {
return false;
}
/** Returns true if the requested file follows the .scl dialect. */
// Note: Just as with .bzl, the same .scl file can be referred to from multiple key types, for
// instance if a BUILD file and a module rule both load foo.scl. Conceptually, .scl files
// shouldn't depend on what kind of top-level file caused them to load, but in practice, this
// implementation quirk means that the .scl file will be loaded twice as separate copies.
//
// This shouldn't matter except in rare edge cases, such as if a Starlark function is loaded
// from both copies and compared for equality. Performance wise, it also means that all
// transitive .scl files will be double-loaded, but we don't expect that to be significant.
//
// The alternative is to use a separate key type just for .scl, but that complicates repo logic;
// see BzlLoadFunction#getRepositoryMapping.
final boolean isSclDialect() {
return getLabel().getName().endsWith(".scl");
}
/**
* Constructs a new key suitable for evaluating a {@code load()} dependency of this key's .bzl
* file.
*
* The new key uses the given label but the same contextual information -- whether the
* top-level requesting value is a BUILD or WORKSPACE file, and if it's a WORKSPACE, its
* chunking info.
*/
abstract Key getKeyForLoad(Label loadLabel);
/**
* Constructs a BzlCompileValue key suitable for retrieving the Starlark code for this .bzl,
* given the Root in which to find its file.
*/
abstract BzlCompileValue.Key getCompileKey(Root root);
@Override
public SkyFunctionName functionName() {
return SkyFunctions.BZL_LOAD;
}
@Override
public final boolean valueIsShareable() {
// We don't guarantee that all constructs implement equality, meaning we can't correctly
// compare deserialized instances. This is currently the case for attribute descriptors.
return false;
}
@SuppressWarnings("EqualsGetClass") // All subclasses are known.
@Override
public boolean equals(Object obj) {
if (this == obj) {
return true;
}
if (obj == null) {
return false;
}
if (!this.getClass().equals(obj.getClass())) {
return false;
}
Key that = (Key) obj;
return this.getLabel().equals(that.getLabel())
&& (this.isBuildPrelude() == that.isBuildPrelude())
&& (this.isBuiltins() == that.isBuiltins());
}
@Override
public int hashCode() {
return Objects.hash(getClass(), getLabel(), isBuildPrelude(), isBuiltins());
}
protected final MoreObjects.ToStringHelper toStringHelper() {
return MoreObjects.toStringHelper(this)
.add("label", getLabel())
.add("isBuildPrelude", isBuildPrelude());
}
@Override
public String toString() {
return toStringHelper().toString();
}
@Override
public SkyKeyInterner This needs to track "chunking" information, i.e. a sequence number indicating which segment
* of the WORKSPACE file we are in the process of evaluating. This helps determine the appropriate
* repository remapping value to use.
*/
// TODO(brandjon): Question: It looks like the chunk number doesn't play any role in deciding
// whether or not a repo is available for load()ing. Are we tracking incremental dependencies
// correctly? For instance, if a repository declaration moves from one workspace chunk to another,
// are we reevaluating whether its loads are still valid? AI: fix if broken, improve this comment
// if not broken.
@Immutable
@AutoCodec.VisibleForSerialization
static final class KeyForWorkspace extends Key {
private final Label label;
private final int workspaceChunk;
private final RootedPath workspacePath;
private KeyForWorkspace(Label label, int workspaceChunk, RootedPath workspacePath) {
this.label = checkNotNull(label);
this.workspaceChunk = workspaceChunk;
this.workspacePath = checkNotNull(workspacePath);
}
@Override
Label getLabel() {
return label;
}
int getWorkspaceChunk() {
return workspaceChunk;
}
RootedPath getWorkspacePath() {
return workspacePath;
}
@Override
Key getKeyForLoad(Label loadLabel) {
return keyForWorkspace(loadLabel, workspaceChunk, workspacePath);
}
@Override
BzlCompileValue.Key getCompileKey(Root root) {
return BzlCompileValue.key(root, label);
}
@Override
public boolean equals(Object obj) {
if (!super.equals(obj)) {
return false;
}
KeyForWorkspace other = (KeyForWorkspace) obj;
return workspaceChunk == other.workspaceChunk && workspacePath.equals(other.workspacePath);
}
@Override
public int hashCode() {
return Objects.hash(super.hashCode(), workspaceChunk, workspacePath);
}
}
/**
* A key for loading a .bzl during {@code @_builtins} evaluation.
*
* This kind of key is only requested by {@link StarlarkBuiltinsFunction} and its transitively
* loaded {@link BzlLoadFunction} calls.
*
* The label must have {@link StarlarkBuiltinsValue#BUILTINS_REPO} as its repository component.
* (It is valid for other key types to use that repo name, but since it is not a real repository
* and cannot be fetched, any attempt to resolve such a key would fail.)
*/
// TODO(#11437): Prevent users from trying to declare a repo named "@_builtins".
@Immutable
@AutoCodec.VisibleForSerialization
static final class KeyForBuiltins extends Key {
private final Label label;
private KeyForBuiltins(Label label) {
this.label = checkNotNull(label);
if (!StarlarkBuiltinsValue.isBuiltinsRepo(label.getRepository())) {
throw new IllegalArgumentException("repository name for builtins key must be '@_builtins'");
}
}
@Override
Label getLabel() {
return label;
}
@Override
boolean isBuiltins() {
return true;
}
@Override
Key getKeyForLoad(Label label) {
return keyForBuiltins(label);
}
@Override
BzlCompileValue.Key getCompileKey(Root root) {
return BzlCompileValue.keyForBuiltins(root, label);
}
}
/** A key for loading a .bzl to get the repo rule required by Bzlmod generated repositories. */
@Immutable
@AutoCodec.VisibleForSerialization
static final class KeyForBzlmod extends Key {
private final Label label;
private KeyForBzlmod(Label label) {
this.label = checkNotNull(label);
}
@Override
Label getLabel() {
return label;
}
@Override
Key getKeyForLoad(Label loadLabel) {
return keyForBzlmod(loadLabel);
}
@Override
BzlCompileValue.Key getCompileKey(Root root) {
return BzlCompileValue.key(root, label);
}
}
/** Constructs a key for loading a regular (non-workspace) .bzl file, from the .bzl's label. */
public static Key keyForBuild(Label label) {
return keyInterner.intern(new KeyForBuild(label, /*isBuildPrelude=*/ false));
}
/**
* Constructs a key for loading a .bzl file from the context of evaluating the WORKSPACE file.
*
* @param label the label of the bzl file being loaded
* @param workspaceChunk the workspace chunk that the load statement originated from. If the bzl
* file is loaded more than once, this is the chunk that it was first loaded from
* @param workspacePath the path of the workspace file for the project
*/
static Key keyForWorkspace(Label label, int workspaceChunk, RootedPath workspacePath) {
return keyInterner.intern(new KeyForWorkspace(label, workspaceChunk, workspacePath));
}
/** Constructs a key for loading a .bzl file within the {@code @_builtins} pseudo-repository. */
static Key keyForBuiltins(Label label) {
return keyInterner.intern(new KeyForBuiltins(label));
}
/** Constructs a key for loading the special prelude .bzl. */
static Key keyForBuildPrelude(Label label) {
return keyInterner.intern(new KeyForBuild(label, /*isBuildPrelude=*/ true));
}
/** Constructs a key for loading a .bzl for Bzlmod repos */
public static Key keyForBzlmod(Label label) {
return keyInterner.intern(new KeyForBzlmod(label));
}
}