blob: 5fc9b2855400023e5e7c5ccde2c1e0a921013957 [file] [log] [blame]
// Copyright 2018 The Bazel Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package com.google.devtools.build.lib.skylarkbuildapi.config;
import com.google.devtools.build.lib.skylarkinterface.Param;
import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
import com.google.devtools.build.lib.skylarkinterface.SkylarkConstructor;
import com.google.devtools.build.lib.skylarkinterface.SkylarkGlobalLibrary;
import com.google.devtools.build.lib.syntax.BaseFunction;
import com.google.devtools.build.lib.syntax.Dict;
import com.google.devtools.build.lib.syntax.EvalException;
import com.google.devtools.build.lib.syntax.Sequence;
import com.google.devtools.build.lib.syntax.StarlarkThread;
/**
* A collection of top-level Starlark functions pertaining to configuration.
*/
@SkylarkGlobalLibrary
public interface ConfigGlobalLibraryApi {
@SkylarkCallable(
name = "transition",
doc =
"A transition that reads a set of input build settings and writes a set of output build "
+ "settings."
+ "<p>Example:</p>"
+ "<p><pre class=\"language-python\">\n"
+ "def _transition_impl(settings, attr):\n"
+ " # This transition just reads the current CPU value as a demonstration.\n"
+ " # A real transition could incorporate this into its followup logic.\n"
+ " current_cpu = settings[\"//command_line_option:cpu\"]\n"
+ " return {\"//command_line_option:compilation_mode\": \"dbg\"}\n"
+ "\n"
+ "build_in_debug_mode = transition(\n"
+ " implementation = _transition_impl,\n"
+ " inputs = [\"//command_line_option:cpu\"],\n"
+ " outputs = [\"//command_line_option:compilation_mode\"],\n"
+ ")"
+ "</pre></p>"
+ "<p>For more details see <a href=\"../config.html#user-defined-transitions\">"
+ "here</a>.</p>",
parameters = {
@Param(
name = "implementation",
type = BaseFunction.class,
positional = false,
named = true,
// TODO(cparsons): The settings dict should take actual Label objects as keys and not
// strings. Update the documentation.
doc =
"The function implementing this transition. This function always has two "
+ "parammeters: <code>settings</code> and <code>attr</code>. The "
+ "<code>settings</code> param is a dictionary whose set of keys is defined "
+ "by the inputs parameter. So, for each build setting "
+ "<code>--//foo=bar</code>, if <code>inputs</code> contains "
+ "<code>//foo</code>, <code>settings</code> will "
+ "have an entry <code>settings['//foo']='bar'</code>.<p>"
+ "The <code>attr</code> param is a reference to <code>ctx.attr</code>. This "
+ "gives the implementation function access to the rule's attributes to make "
+ "attribute-parameterized transitions possible.<p>"
+ "This function must return a <code>dict</code> from build setting identifier "
+ "to build setting value; this represents the configuration transition: for "
+ "each entry in the returned <code>dict</code>, the transition updates that "
+ "setting to the new value. All other settings are unchanged. This function "
+ "can also return a <code>list</code> of <code>dict</code>s or a "
+ "<code>dict</code> of <code>dict</code>s in the case of a "
+ "split transition."),
@Param(
name = "inputs",
type = Sequence.class,
generic1 = String.class,
positional = false,
named = true,
doc =
"List of build settings that can be read by this transition. This becomes the "
+ "key set of the settings parameter of the implementation function "
+ "parameter."),
@Param(
name = "outputs",
type = Sequence.class,
generic1 = String.class,
positional = false,
named = true,
doc =
"List of build settings that can be written by this transition. This must be "
+ "a superset of the key set of the dictionary returned by this transition."),
},
useStarlarkThread = true)
@SkylarkConstructor(objectType = ConfigurationTransitionApi.class)
ConfigurationTransitionApi transition(
BaseFunction implementation,
Sequence<?> inputs, // <String> expected
Sequence<?> outputs, // <String> expected
StarlarkThread thread)
throws EvalException;
@SkylarkCallable(
name = "analysis_test_transition",
doc =
"<p> Creates a configuration transition to be applied on "
+ "an analysis-test rule's dependencies. This transition may only be applied "
+ "on attributes of rules with <code>analysis_test = True</code>. Such rules are "
+ "restricted in capabilities (for example, the size of their dependency tree is "
+ "limited), so transitions created using this function are limited in potential "
+ "scope as compared to transitions created using "
+ "<a href=\"#transition\">transition</a>.",
parameters = {
@Param(
name = "settings",
type = Dict.class,
positional = false,
named = true,
doc =
"A dictionary containing information about configuration settings which "
+ "should be set by this configuration transition. Keys are build setting "
+ "labels and values are their new post-transition values. All other settings "
+ "are unchanged. Use this to declare specific configuration settings that "
+ "an analysis test requires to be set in order to pass."),
},
useStarlarkThread = true)
ConfigurationTransitionApi analysisTestTransition(
Dict<?, ?> changedSettings, // <String, String> expected
StarlarkThread thread)
throws EvalException;
}