blob: 19b7f2c6b8409c622563cb348d4463a389a57dcb [file] [log] [blame]
// Copyright (c) 2020, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
import 'configuration.dart';
/// A step that is run on a builder to build and test certain configurations of
/// the Dart SDK.
/// Each step on a builder runs a script the with provided arguments. If the
/// script is 'tools/' (which is the default if no script is given in
/// the test matrix), or `testRunner == true`, the step is called a 'test
/// step'. Test steps must include the '--named_configuration' (for short
/// '-n') option to select the named [Configuration] to test.
/// Test steps are expected to produce test results that are collected during
/// the run of the builder and checked against the expected results to determine
/// the success or failure of the build.
class Step {
final String name;
final String script;
final List<String> arguments;
final Map<String, String> environment;
final String fileSet;
final int shards;
final bool isTestRunner;
final Configuration testedConfiguration;
Step(, String script, this.arguments, this.environment, this.fileSet,
this.shards, this.isTestRunner, this.testedConfiguration)
: script = script ?? testScriptName;
static const testScriptName = "tools/";
bool get isTestStep => script == testScriptName || isTestRunner;
/// Create a [Step] from the 'step template' [map], values for supported
/// variables [configuration], and the list of supported named configurations.
static Step parse(Map map, Map<String, String> configuration,
List<Configuration> configurations) {
var arguments = (map["arguments"] as List ?? [])
.map((argument) => _expandVariables(argument as String, configuration))
var testedConfigurations = <Configuration>[];
var script = map["script"] as String ?? testScriptName;
var isTestRunner = map["testRunner"] as bool ?? false;
if (script == testScriptName || isTestRunner) {
// TODO(karlklose): replace with argument parser that can handle all
// arguments to
for (var argument in arguments) {
var names = <String>[];
if (argument.startsWith("--named_configuration")) {
.map((s) => s.trim()));
} else if (argument.startsWith("-n")) {
argument.substring("-n".length).split(",").map((s) => s.trim()));
} else {
for (var name in names) {
var matchingConfigurations =
configurations.where((c) => == name);
if (matchingConfigurations.isEmpty) {
throw FormatException("Undefined configuration: $name");
if (testedConfigurations.length > 1) {
throw FormatException("Step tests multiple configurations: $arguments");
return Step(
map["name"] as String,
<String, String>{...?map["environment"]},
map["fileset"] as String,
map["shards"] as int,
testedConfigurations.isEmpty ? null : testedConfigurations.single);
/// A builder runs a list of [Step]s to build and test certain configurations of
/// the Dart SDK.
/// Groups of builders are defined in the 'builder_configurations' section of
/// the test matrix.
class Builder {
final String name;
final String description;
final List<Step> steps;
final System system;
final Mode mode;
final Architecture arch;
final Sanitizer sanitizer;
final Runtime runtime;
final Set<Configuration> testedConfigurations;
Builder(, this.description, this.steps, this.system, this.mode,
this.arch, this.sanitizer, this.runtime, this.testedConfigurations);
/// Create a [Builder] from its name, a list of 'step templates', the
/// supported named configurations and a description.
/// The 'step templates' can contain the variables `${system}`, `${mode}`,
/// `${arch}`, and `${runtime}. The values for these variables are inferred
/// from the builder's name.
static Builder parse(String builderName, List<Map> steps,
List<Configuration> configurations, String description) {
var builderParts = builderName.split("-");
var systemName = _findPart(builderParts, System.names);
var modeName = _findPart(builderParts, Mode.names);
var archName = _findPart(builderParts, Architecture.names);
var sanitizerName = _findPart(builderParts, Sanitizer.names);
var runtimeName = _findPart(builderParts, Runtime.names);
var parsedSteps = steps
.map((step) => Step.parse(
"system": systemName,
"mode": modeName,
"arch": archName,
"sanitizer": sanitizerName,
"runtime": runtimeName,
var testedConfigurations = _getTestedConfigurations(parsedSteps);
return Builder(
_findIfNotNull(System.find, systemName),
_findIfNotNull(Mode.find, modeName),
_findIfNotNull(Architecture.find, archName),
_findIfNotNull(Sanitizer.find, sanitizerName),
_findIfNotNull(Runtime.find, runtimeName),
/// Tries to replace a variable named [variableName] with [value] and throws
/// and exception if the variable is used but `value == null`.
String _tryReplace(String string, String variableName, String value) {
var variable = "\${$variableName}";
if (string.contains(variable)) {
if (value == null) {
throw FormatException("Undefined value for '$variableName' in '$string'");
return string.replaceAll(variable, value);
} else {
return string;
/// Replace the use of supported variable names with the their value given
/// in [values] and throws an exception if an unsupported variable name is used.
String _expandVariables(String string, Map<String, String> values) {
for (var variable in ["system", "mode", "arch", "sanitizer", "runtime"]) {
string = _tryReplace(string, variable, values[variable]);
return string;
Set<Configuration> _getTestedConfigurations(List<Step> steps) {
return steps
.where((step) => step.isTestStep)
.map((step) => step.testedConfiguration)
T _findIfNotNull<T>(T Function(String) find, String name) {
return name != null ? find(name) : null;
String _findPart(List<String> builderParts, List<String> parts) {
return builderParts.firstWhere((part) => parts.contains(part),
orElse: () => null);
List<Builder> parseBuilders(
List<Map> builderConfigurations, List<Configuration> configurations) {
var builders = <Builder>[];
var names = <String>{};
for (var builderConfiguration in builderConfigurations) {
var meta = builderConfiguration["meta"] as Map ?? <String, String>{};
var builderNames = <String>[...?builderConfiguration["builders"]];
var steps = <Map>[...?builderConfiguration["steps"]];
for (var builderName in builderNames) {
if (!names.add(builderName)) {
throw FormatException('Duplicate builder name: "$builderName"');
builderName, steps, configurations, meta["description"] as String));
return builders;