The process of "builtins injection" refers to evaluating this Skyfunction and applying its * result to {@link BzlLoadFunction}'s computation. See also the design * doc: * *
This function has a trivial key, so there can only be one value in the build at a time. It has * a single dependency, on the result of evaluating the exports.bzl file to a {@link BzlLoadValue}. */ public class StarlarkBuiltinsFunction implements SkyFunction { /** * The label where {@code @_builtins} symbols are exported from. (Note that this is never * conflated with an actual repository named "{@code @_builtins}" because 1) it is only ever * accessed through a special SkyKey, and 2) we disallow the user from defining a repo named * {@code @_builtins} to avoid confusion.) */ static final Label EXPORTS_ENTRYPOINT = Label.parseCanonicalUnchecked("@_builtins//:exports.bzl"); // unused /** * Key for loading exports.bzl. Note that {@code keyForBuiltins} (as opposed to {@code * keyForBuild}) ensures we can resolve {@code @_builtins}, which is otherwise inaccessible. It * also prevents us from cyclically requesting StarlarkBuiltinsFunction again to evaluate * exports.bzl. */ static final BzlLoadValue.Key EXPORTS_ENTRYPOINT_KEY = BzlLoadValue.keyForBuiltins(EXPORTS_ENTRYPOINT); // Used to obtain the injected environment. private final BazelStarlarkEnvironment bazelStarlarkEnvironment; public StarlarkBuiltinsFunction(BazelStarlarkEnvironment bazelStarlarkEnvironment) { this.bazelStarlarkEnvironment = bazelStarlarkEnvironment; } @Override @Nullable public SkyValue compute(SkyKey skyKey, Environment env) throws StarlarkBuiltinsFunctionException, InterruptedException { // skyKey is a singleton, unused. try { return computeInternal( env, bazelStarlarkEnvironment, /* inliningState= */ null, /* bzlLoadFunction= */ null); } catch (BuiltinsFailedException e) { throw new StarlarkBuiltinsFunctionException(e); } } /** * Computes this Skyfunction under inlining of {@link BzlLoadFunction}, forwarding the given * inlining state. * *
The given Skyframe environment must be a {@link RecordingSkyFunctionEnvironment}. It is * unwrapped before calling {@link BzlLoadFunction}'s inlining code path. * *
Returns null on Skyframe restart or error.
*/
@Nullable
public static StarlarkBuiltinsValue computeInline(
StarlarkBuiltinsValue.Key key, // singleton value, unused
BzlLoadFunction.InliningState inliningState,
BazelStarlarkEnvironment bazelStarlarkEnvironment,
BzlLoadFunction bzlLoadFunction)
throws BuiltinsFailedException, InterruptedException {
// See BzlLoadFunction#computeInline and BzlLoadFunction.InliningState for an explanation of the
// inlining mechanism and its invariants. For our purposes, the Skyframe environment to use
// comes from inliningState.
return computeInternal(
inliningState.getEnvironment(), bazelStarlarkEnvironment, inliningState, bzlLoadFunction);
}
// bzlLoadFunction and inliningState are non-null iff using inlining code path.
@Nullable
private static StarlarkBuiltinsValue computeInternal(
Environment env,
BazelStarlarkEnvironment bazelStarlarkEnvironment,
@Nullable BzlLoadFunction.InliningState inliningState,
@Nullable BzlLoadFunction bzlLoadFunction)
throws BuiltinsFailedException, InterruptedException {
StarlarkSemantics starlarkSemantics = PrecomputedValue.STARLARK_SEMANTICS.get(env);
if (starlarkSemantics == null) {
return null;
}
// Return the empty value if builtins injection is disabled.
if (starlarkSemantics.get(BuildLanguageOptions.EXPERIMENTAL_BUILTINS_BZL_PATH).isEmpty()) {
return StarlarkBuiltinsValue.createEmpty(starlarkSemantics);
}
// Load exports.bzl. If we were requested using inlining, make sure to inline the call back into
// BzlLoadFunction.
BzlLoadValue exportsValue;
try {
if (inliningState == null) {
exportsValue =
(BzlLoadValue)
env.getValueOrThrow(EXPORTS_ENTRYPOINT_KEY, BzlLoadFailedException.class);
} else {
exportsValue = bzlLoadFunction.computeInline(EXPORTS_ENTRYPOINT_KEY, inliningState);
}
} catch (BzlLoadFailedException ex) {
throw BuiltinsFailedException.errorEvaluatingBuiltinsBzls(ex);
}
if (exportsValue == null) {
return null;
}
// Apply declarations of exports.bzl to the native predeclared symbols.
byte[] transitiveDigest = exportsValue.getTransitiveDigest();
Module module = exportsValue.getModule();
try {
ImmutableMap This exception type typically wraps a {@link BzlLoadFailedException} and is wrapped by a
* {@link BzlLoadFailedException} in turn.
*/
static final class BuiltinsFailedException extends Exception {
private final Transience transience;
private BuiltinsFailedException(String errorMessage, Exception cause, Transience transience) {
super(errorMessage, cause);
this.transience = transience;
}
Transience getTransience() {
return transience;
}
static BuiltinsFailedException errorEvaluatingBuiltinsBzls(BzlLoadFailedException cause) {
return errorEvaluatingBuiltinsBzls(cause, cause.getTransience());
}
static BuiltinsFailedException errorEvaluatingBuiltinsBzls(
Exception cause, Transience transience) {
return new BuiltinsFailedException(
String.format("Failed to load builtins sources: %s", cause.getMessage()),
cause,
transience);
}
static BuiltinsFailedException errorApplyingExports(Exception cause) {
return new BuiltinsFailedException(
String.format("Failed to apply declared builtins: %s", cause.getMessage()),
cause,
Transience.PERSISTENT);
}
}
/** The exception type thrown by {@link StarlarkBuiltinsFunction}. */
static final class StarlarkBuiltinsFunctionException extends SkyFunctionException {
private StarlarkBuiltinsFunctionException(BuiltinsFailedException cause) {
super(cause, cause.transience);
}
}
}