builtinsInternals) {
this.starlarkGlobals = starlarkGlobals;
this.ruleFunctions = ruleFunctions;
this.registeredBzlToplevels = registeredBzlToplevels;
this.workspaceBzlNativeBindings = workspaceBzlNativeBindings;
this.bzlToplevelsWithoutNative =
createBzlToplevelsWithoutNative(starlarkGlobals, registeredBzlToplevels);
this.uninjectedBuildBzlNativeBindings =
createUninjectedBuildBzlNativeBindings(
starlarkGlobals, ruleFunctions, registeredBuildFileToplevels);
this.uninjectedBuildBzlEnv =
createUninjectedBuildBzlEnv(bzlToplevelsWithoutNative, uninjectedBuildBzlNativeBindings);
this.uninjectedWorkspaceBzlEnv =
createWorkspaceBzlEnv(bzlToplevelsWithoutNative, workspaceBzlNativeBindings);
this.builtinsBzlEnv =
createBuiltinsBzlEnv(
starlarkGlobals,
builtinsInternals,
uninjectedBuildBzlNativeBindings,
uninjectedBuildBzlEnv);
this.uninjectedBuildEnv =
createUninjectedBuildEnv(starlarkGlobals, ruleFunctions, registeredBuildFileToplevels);
}
/**
* Returns a {@link StarlarkGlobals} instance.
*
* In practice, {@link StarlarkGlobals} is a singleton, so this accessor is really about
* retrieving {@link StarlarkGlobalsImpl#INSTANCE} without requiring a dependency on the
* lib/analysis/ package.
*/
public StarlarkGlobals getStarlarkGlobals() {
return starlarkGlobals;
}
/**
* Returns the contents of the "native" object for BUILD-loaded bzls, not accounting for builtins
* injection.
*/
public ImmutableMap getUninjectedBuildBzlNativeBindings() {
return uninjectedBuildBzlNativeBindings;
}
/** Returns the contents of the "native" object for WORKSPACE-loaded bzls. */
public ImmutableMap getWorkspaceBzlNativeBindings() {
return workspaceBzlNativeBindings;
}
/**
* Returns the original environment for BUILD-loaded bzl files, not accounting for builtins
* injection. Excludes symbols in {@link Starlark#UNIVERSE}.
*
* The post-injection environment may differ from this one by what symbols a name is bound to,
* but the set of symbols remains the same.
*/
public ImmutableMap getUninjectedBuildBzlEnv() {
return uninjectedBuildBzlEnv;
}
/**
* Returns the original environment for BUILD files, not accounting for builtins injection or
* application of the prelude. Excludes symbols in {@link Starlark#UNIVERSE}.
*
* Applying builtins injection may update name bindings, but not add or remove them. I.e. some
* names may refer to different symbols but the static set of names remains the same. Applying the
* prelude file may update and add name bindings but not remove them.
*/
public ImmutableMap getUninjectedBuildEnv() {
return uninjectedBuildEnv;
}
/**
* Returns the environment for WORKSPACE-loaded bzl files before builtins injection. Excludes
* symbols in {@link Starlark#UNIVERSE}.
*/
public ImmutableMap getUninjectedWorkspaceBzlEnv() {
return uninjectedWorkspaceBzlEnv;
}
/**
* Returns the environment for bzl files in the {@code @_builtins} pseudo-repository. Excludes
* symbols in {@link Starlark#UNIVERSE}.
*/
public ImmutableMap getBuiltinsBzlEnv() {
return builtinsBzlEnv;
}
private static ImmutableMap createBzlToplevelsWithoutNative(
StarlarkGlobals starlarkGlobals, Map registeredBzlToplevels) {
ImmutableMap.Builder env = new ImmutableMap.Builder<>();
env.putAll(starlarkGlobals.getFixedBzlToplevels());
env.putAll(registeredBzlToplevels);
return env.buildOrThrow();
}
/**
* Produces everything that would be in the {@code native} object for BUILD-loaded bzl files if
* builtins injection didn't happen.
*/
private static ImmutableMap createUninjectedBuildBzlNativeBindings(
StarlarkGlobals starlarkGlobals,
Map ruleFunctions,
Map registeredBuildFileToplevels) {
ImmutableMap.Builder env = new ImmutableMap.Builder<>();
env.putAll(starlarkGlobals.getFixedBuildFileToplevelsSharedWithNative());
env.putAll(ruleFunctions);
env.putAll(registeredBuildFileToplevels);
return env.buildOrThrow();
}
/** Constructs a "native" module object with the given contents. */
private static Object createNativeModule(Map bindings) {
return StructProvider.STRUCT.create(bindings, "no native function or rule '%s'");
}
private static ImmutableMap createUninjectedBuildBzlEnv(
Map bzlToplevelsWithoutNative,
Map uninjectedBuildBzlNativeBindings) {
ImmutableMap.Builder env = new ImmutableMap.Builder<>();
env.putAll(bzlToplevelsWithoutNative);
// Determine the "native" module.
// TODO(#11954): Use the same "native" object for both BUILD- and WORKSPACE-loaded .bzls, and
// just have it be a dynamic error to call the wrong thing at the wrong time. This is a breaking
// change.
env.put("native", createNativeModule(uninjectedBuildBzlNativeBindings));
return env.buildOrThrow();
}
private static ImmutableMap createUninjectedBuildEnv(
StarlarkGlobals starlarkGlobals,
Map ruleFunctions,
Map registeredBuildFileToplevels) {
ImmutableMap.Builder env = ImmutableMap.builder();
env.putAll(starlarkGlobals.getFixedBuildFileToplevelsSharedWithNative());
env.putAll(starlarkGlobals.getFixedBuildFileToplevelsNotInNative());
env.putAll(ruleFunctions);
env.putAll(registeredBuildFileToplevels);
return env.buildOrThrow();
}
private static ImmutableMap createWorkspaceBzlEnv(
Map bzlToplevelsWithoutNative,
Map workspaceBzlNativeBindings) {
ImmutableMap.Builder env = new ImmutableMap.Builder<>();
env.putAll(bzlToplevelsWithoutNative);
// See above comments for native in BUILD bzls.
env.put("native", createNativeModule(workspaceBzlNativeBindings));
return env.buildOrThrow();
}
private static ImmutableMap createBuiltinsBzlEnv(
StarlarkGlobals starlarkGlobals,
Map builtinsInternals,
Map uninjectedBuildBzlNativeBindings,
Map uninjectedBuildBzlEnv) {
Map env = new HashMap<>(starlarkGlobals.getFixedBzlToplevels());
// For _builtins.toplevel, replace all GuardedValues with the underlying value;
// StarlarkSemantics flags do not affect @_builtins.
//
// We do this because otherwise we'd need to differentiate the _builtins.toplevel object (and
// therefore the @_builtins environment) based on StarlarkSemantics. That seems unnecessary.
// Instead we trust @_builtins to not misuse flag-guarded features, same as native code.
//
// If foo is flag-guarded (either experimental or incompatible), it is unconditionally visible
// as _builtins.toplevel.foo. It is legal to list it in exported_toplevels unconditionally, but
// the flag still controls whether the symbol is actually visible to user code.
Map unwrappedBuildBzlSymbols = new HashMap<>();
for (Map.Entry entry : uninjectedBuildBzlEnv.entrySet()) {
Object symbol = entry.getValue();
if (symbol instanceof GuardedValue) {
symbol = ((GuardedValue) symbol).getObject();
}
unwrappedBuildBzlSymbols.put(entry.getKey(), symbol);
}
Object builtinsModule =
new BuiltinsInternalModule(
createNativeModule(uninjectedBuildBzlNativeBindings),
// createNativeModule() is good enough for the "toplevel" and "internal" objects too.
createNativeModule(unwrappedBuildBzlSymbols),
createNativeModule(builtinsInternals));
Object conflictingValue = env.put("_builtins", builtinsModule);
Preconditions.checkState(
conflictingValue == null, "'_builtins' name is reserved for builtins injection");
return ImmutableMap.copyOf(env);
}
/**
* Throws {@link InjectionException} with an appropriate error message if the given {@code symbol}
* is not in both {@code existingSymbols} and {@code injectableSymbols}. {@code kind} is a string
* describing the domain of {@code symbol}.
*/
private static void validateSymbolIsInjectable(
String symbol, Set existingSymbols, Set injectableSymbols, String kind)
throws InjectionException {
if (!existingSymbols.contains(symbol)) {
throw new InjectionException(
String.format(
"Injected %s '%s' must override an existing one by that name", kind, symbol));
} else if (!injectableSymbols.contains(symbol)) {
throw new InjectionException(
String.format("Cannot override '%s' with an injected %s", symbol, kind));
}
}
/** Given a string prefixed with + or -, returns that prefix character, or null otherwise. */
@Nullable
private static Character getKeyPrefix(String key) {
if (key.isEmpty()) {
return null;
}
char prefix = key.charAt(0);
if (!(prefix == '+' || prefix == '-')) {
return null;
}
return prefix;
}
/**
* Given a string prefixed with + or -, returns the remainder of the string, or the whole string
* otherwise.
*/
private static String getKeySuffix(String key) {
return getKeyPrefix(key) == null ? key : key.substring(1);
}
/**
* Given a list of strings representing the +/- prefixed items in {@code
* --experimental_builtins_injection_override}, returns a map from each item to a Boolean
* indicating whether it last appeared with the + suffix (True) or - suffix (False).
*
* @throws InjectionException if an item is not prefixed with either "+" or "-"
*/
private static Map parseInjectionOverridesList(List overrides)
throws InjectionException {
HashMap result = new HashMap<>();
for (String prefixedItem : overrides) {
Character prefix = getKeyPrefix(prefixedItem);
if (prefix == null) {
throw new InjectionException(
String.format("Invalid injection override item: '%s'", prefixedItem));
}
result.put(prefixedItem.substring(1), prefix == '+');
}
return result;
}
/**
* Given an exports dict key, and an override map, return whether injection should be applied for
* that key.
*/
private static boolean injectionApplies(String key, Map overrides) {
Character prefix = getKeyPrefix(key);
if (prefix == null) {
// Unprefixed; overrides don't get a say in the matter.
return true;
}
Boolean override = overrides.get(key.substring(1));
if (override == null) {
return prefix == '+';
} else {
return override;
}
}
/**
* Constructs an environment for a BUILD-loaded bzl file based on the default environment, the
* maps corresponding to the {@code exported_toplevels} and {@code exported_rules} dicts, and the
* value of {@code --experimental_builtins_injection_override}.
*
* Injected symbols must override an existing symbol of that name. Furthermore, the overridden
* symbol must be one that was registered on the rule class provider (e.g., {@code CcInfo} or
* {@code cc_library}), not a fixed symbol that's always available (e.g., {@code provider} or
* {@code glob}). Throws InjectionException if these conditions are not met.
*
*
Whether or not injection actually occurs for a given map key depends on its prefix (if any)
* and the prefix of its appearance (if it appears at all) in the override list; see the
* documentation for {@code --experimental_builtins_injection_override}. Non-injected symbols must
* still obey the above constraints.
*
* @see com.google.devtools.build.lib.skyframe.StarlarkBuiltinsFunction
*/
public ImmutableMap createBuildBzlEnvUsingInjection(
Map exportedToplevels,
Map exportedRules,
List overridesList)
throws InjectionException {
return createBzlEnvUsingInjection(
exportedToplevels, exportedRules, overridesList, uninjectedBuildBzlNativeBindings);
}
/**
* Constructs an environment for a WORKSPACE-loaded bzl file based on the default environment, the
* maps corresponding to the {@code exported_toplevels} and {@code exported_rules} dicts, and the
* value of {@code --experimental_builtins_injection_override}.
*
* @see com.google.devtools.build.lib.skyframe.StarlarkBuiltinsFunction
*/
public ImmutableMap createWorkspaceBzlEnvUsingInjection(
Map exportedToplevels,
Map exportedRules,
List overridesList)
throws InjectionException {
return createBzlEnvUsingInjection(
exportedToplevels, exportedRules, overridesList, workspaceBzlNativeBindings);
}
private ImmutableMap createBzlEnvUsingInjection(
Map exportedToplevels,
Map exportedRules,
List overridesList,
Map nativeBase)
throws InjectionException {
Map overridesMap = parseInjectionOverridesList(overridesList);
Map env = new HashMap<>(bzlToplevelsWithoutNative);
// Determine "native" bindings.
// TODO(#11954): See above comment in createUninjectedBuildBzlEnv.
Map nativeBindings = new HashMap<>(nativeBase);
for (Map.Entry entry : exportedRules.entrySet()) {
String key = entry.getKey();
String name = getKeySuffix(key);
validateSymbolIsInjectable(name, nativeBindings.keySet(), ruleFunctions.keySet(), "rule");
if (injectionApplies(key, overridesMap)) {
nativeBindings.put(name, entry.getValue());
}
}
env.put("native", createNativeModule(nativeBindings));
// Determine top-level symbols.
for (Map.Entry entry : exportedToplevels.entrySet()) {
String key = entry.getKey();
String name = getKeySuffix(key);
validateSymbolIsInjectable(
name,
Sets.union(env.keySet(), Starlark.UNIVERSE.keySet()),
registeredBzlToplevels.keySet(),
"top-level symbol");
if (injectionApplies(key, overridesMap)) {
env.put(name, entry.getValue());
}
}
return ImmutableMap.copyOf(env);
}
/**
* Constructs an environment for a BUILD file based on the default environment, the map
* corresponding to the {@code exported_rules} dict, and the value of {@code
* --experimental_builtins_injection_override}.
*
* Injected rule symbols must override an existing native rule of that name. Only rules may be
* overridden in this manner, not generic built-ins such as {@code package} or {@code glob}.
* Throws InjectionException if these conditions are not met.
*
*
Whether or not injection actually occurs for a given map key depends on its prefix (if any)
* and the prefix of its appearance (if it appears at all) in the override list; see the
* documentation for {@code --experimental_builtins_injection_override}. Non-injected symbols must
* still obey the above constraints.
*/
public ImmutableMap createBuildEnvUsingInjection(
Map exportedRules, List overridesList) throws InjectionException {
Map overridesMap = parseInjectionOverridesList(overridesList);
HashMap env = new HashMap<>(uninjectedBuildEnv);
for (Map.Entry entry : exportedRules.entrySet()) {
String key = entry.getKey();
String name = getKeySuffix(key);
validateSymbolIsInjectable(
name,
Sets.union(env.keySet(), Starlark.UNIVERSE.keySet()),
ruleFunctions.keySet(),
"rule");
if (injectionApplies(key, overridesMap)) {
env.put(name, entry.getValue());
}
}
return ImmutableMap.copyOf(env);
}
/** Indicates a problem performing builtins injection. */
public static final class InjectionException extends Exception {
InjectionException(String message) {
super(message);
}
}
}