features.dart 9.11 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4 5 6 7 8 9
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'base/context.dart';

/// The current [FeatureFlags] implementation.
///
/// If not injected, a default implementation is provided.
10
FeatureFlags get featureFlags => context.get<FeatureFlags>()!;
11 12 13 14

/// The interface used to determine if a particular [Feature] is enabled.
///
/// The rest of the tools code should use this class instead of looking up
15
/// features directly. To facilitate rolls to google3 and other clients, all
16 17 18
/// flags should be provided with a default implementation here. Clients that
/// use this class should extent instead of implement, so that new flags are
/// picked up automatically.
19 20
abstract class FeatureFlags {
  /// const constructor so that subclasses can be const.
21 22 23
  const FeatureFlags();

  /// Whether flutter desktop for linux is enabled.
24
  bool get isLinuxEnabled => false;
25 26

  /// Whether flutter desktop for macOS is enabled.
27
  bool get isMacOSEnabled => false;
28 29

  /// Whether flutter web is enabled.
30
  bool get isWebEnabled => false;
31 32

  /// Whether flutter desktop for Windows is enabled.
33 34 35 36 37 38 39 40 41 42
  bool get isWindowsEnabled => false;

  /// Whether android is enabled.
  bool get isAndroidEnabled => true;

  /// Whether iOS is enabled.
  bool get isIOSEnabled => true;

  /// Whether fuchsia is enabled.
  bool get isFuchsiaEnabled => true;
43

44 45 46
  /// Whether custom devices are enabled.
  bool get areCustomDevicesEnabled => false;

47
  /// Whether fast single widget reloads are enabled.
48
  bool get isSingleWidgetReloadEnabled => false;
49

50 51 52
  /// Whether a particular feature is enabled for the current channel.
  ///
  /// Prefer using one of the specific getters above instead of this API.
53
  bool isEnabled(Feature feature);
54 55
}

56 57 58 59 60 61
/// All current Flutter feature flags.
const List<Feature> allFeatures = <Feature>[
  flutterWebFeature,
  flutterLinuxDesktopFeature,
  flutterMacOSDesktopFeature,
  flutterWindowsDesktopFeature,
62
  singleWidgetReload,
63 64 65
  flutterAndroidFeature,
  flutterIOSFeature,
  flutterFuchsiaFeature,
66
  flutterCustomDevicesFeature,
67 68 69 70
];

/// The [Feature] for flutter web.
const Feature flutterWebFeature = Feature(
71
  name: 'Flutter for web',
72 73 74 75
  configSetting: 'enable-web',
  environmentOverride: 'FLUTTER_WEB',
  master: FeatureChannelSetting(
    available: true,
76
    enabledByDefault: true,
77
  ),
78 79
  beta: FeatureChannelSetting(
    available: true,
80
    enabledByDefault: true,
81 82
  ),
  stable: FeatureChannelSetting(
83 84
    available: true,
    enabledByDefault: true,
85
  ),
86 87 88 89
);

/// The [Feature] for macOS desktop.
const Feature flutterMacOSDesktopFeature = Feature(
90
  name: 'support for desktop on macOS',
91
  configSetting: 'enable-macos-desktop',
92
  environmentOverride: 'FLUTTER_MACOS',
93 94
  master: FeatureChannelSetting(
    available: true,
95
    enabledByDefault: true,
96
  ),
97
  beta: FeatureChannelSetting(
98
    available: true,
99
    enabledByDefault: true,
100 101
  ),
  stable: FeatureChannelSetting(
102
    available: true,
103
    enabledByDefault: true,
104
  ),
105 106 107 108
);

/// The [Feature] for Linux desktop.
const Feature flutterLinuxDesktopFeature = Feature(
109
  name: 'support for desktop on Linux',
110
  configSetting: 'enable-linux-desktop',
111
  environmentOverride: 'FLUTTER_LINUX',
112 113
  master: FeatureChannelSetting(
    available: true,
114
    enabledByDefault: true,
115
  ),
116
  beta: FeatureChannelSetting(
117
    available: true,
118
    enabledByDefault: true,
119 120
  ),
  stable: FeatureChannelSetting(
121
    available: true,
122
    enabledByDefault: true,
123
  ),
124 125 126 127
);

/// The [Feature] for Windows desktop.
const Feature flutterWindowsDesktopFeature = Feature(
128
  name: 'support for desktop on Windows',
129
  configSetting: 'enable-windows-desktop',
130
  environmentOverride: 'FLUTTER_WINDOWS',
131 132
  master: FeatureChannelSetting(
    available: true,
133
    enabledByDefault: true,
134
  ),
135
  beta: FeatureChannelSetting(
136
    available: true,
137
    enabledByDefault: true,
138 139
  ),
  stable: FeatureChannelSetting(
140
    available: true,
141
    enabledByDefault: true,
142
  ),
143 144
);

145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
/// The [Feature] for Android devices.
const Feature flutterAndroidFeature = Feature(
  name: 'Flutter for Android',
  configSetting: 'enable-android',
  master: FeatureChannelSetting(
    available: true,
    enabledByDefault: true,
  ),
  beta: FeatureChannelSetting(
    available: true,
    enabledByDefault: true,
  ),
  stable: FeatureChannelSetting(
    available: true,
    enabledByDefault: true,
  ),
);


/// The [Feature] for iOS devices.
const Feature flutterIOSFeature = Feature(
  name: 'Flutter for iOS',
  configSetting: 'enable-ios',
  master: FeatureChannelSetting(
    available: true,
    enabledByDefault: true,
  ),
  beta: FeatureChannelSetting(
    available: true,
    enabledByDefault: true,
  ),
  stable: FeatureChannelSetting(
    available: true,
    enabledByDefault: true,
  ),
);

/// The [Feature] for Fuchsia support.
const Feature flutterFuchsiaFeature = Feature(
  name: 'Flutter for Fuchsia',
  configSetting: 'enable-fuchsia',
  environmentOverride: 'FLUTTER_FUCHSIA',
  master: FeatureChannelSetting(
    available: true,
  ),
);

192 193 194 195 196 197 198 199 200
const Feature flutterCustomDevicesFeature = Feature(
  name: 'Early support for custom device types',
  configSetting: 'enable-custom-devices',
  environmentOverride: 'FLUTTER_CUSTOM_DEVICES',
  master: FeatureChannelSetting(
    available: true,
  ),
);

201 202 203 204
/// The fast hot reload feature for https://github.com/flutter/flutter/issues/61407.
const Feature singleWidgetReload = Feature(
  name: 'Hot reload optimization for changes to class body of a single widget',
  configSetting: 'single-widget-reload-optimization',
205
  environmentOverride: 'FLUTTER_SINGLE_WIDGET_RELOAD',
206 207
  master: FeatureChannelSetting(
    available: true,
208
    enabledByDefault: true,
209 210 211 212 213 214
  ),
  beta: FeatureChannelSetting(
    available: true,
  ),
);

215 216 217 218 219 220
/// A [Feature] is a process for conditionally enabling tool features.
///
/// All settings are optional, and if not provided will generally default to
/// a "safe" value, such as being off.
///
/// The top level feature settings can be provided to apply to all channels.
221
/// Otherwise, more specific settings take precedence over higher level
222 223 224 225
/// settings.
class Feature {
  /// Creates a [Feature].
  const Feature({
226
    required this.name,
227 228
    this.environmentOverride,
    this.configSetting,
229
    this.extraHelpText,
230 231
    this.master = const FeatureChannelSetting(),
    this.beta = const FeatureChannelSetting(),
232
    this.stable = const FeatureChannelSetting()
233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253
  });

  /// The user visible name for this feature.
  final String name;

  /// The settings for the master branch and other unknown channels.
  final FeatureChannelSetting master;

  /// The settings for the beta branch.
  final FeatureChannelSetting beta;

  /// The settings for the stable branch.
  final FeatureChannelSetting stable;

  /// The name of an environment variable that can override the setting.
  ///
  /// The environment variable needs to be set to the value 'true'. This is
  /// only intended for usage by CI and not as an advertised method to enable
  /// a feature.
  ///
  /// If not provided, defaults to `null` meaning there is no override.
254
  final String? environmentOverride;
255 256 257 258

  /// The name of a setting that can be used to enable this feature.
  ///
  /// If not provided, defaults to `null` meaning there is no config setting.
259
  final String? configSetting;
260

261 262 263
  /// Additional text to add to the end of the help message.
  ///
  /// If not provided, defaults to `null` meaning there is no additional text.
264
  final String? extraHelpText;
265

266
  /// A help message for the `flutter config` command, or null if unsupported.
267
  String? generateHelpMessage() {
268 269 270
    if (configSetting == null) {
      return null;
    }
271 272
    final StringBuffer buffer = StringBuffer('Enable or disable $name. '
        'This setting will take effect on ');
273 274 275 276 277 278 279
    final List<String> channels = <String>[
      if (master.available) 'master',
      if (beta.available) 'beta',
      if (stable.available) 'stable',
    ];
    if (channels.length == 1) {
      buffer.write('the ${channels.single} channel.');
280 281
    } else if (channels.length == 2) {
      buffer.write('the ${channels.join(' and ')} channels.');
282
    } else {
283 284 285
      final String prefix = (channels.toList()
        ..removeLast()).join(', ');
      buffer.write('the $prefix, and ${channels.last} channels.');
286
    }
287 288 289
    if (extraHelpText != null) {
      buffer.write(' $extraHelpText');
    }
290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315
    return buffer.toString();
  }

  /// Retrieve the correct setting for the provided `channel`.
  FeatureChannelSetting getSettingForChannel(String channel) {
    switch (channel) {
      case 'stable':
        return stable;
      case 'beta':
        return beta;
      case 'master':
      default:
        return master;
    }
  }
}

/// A description of the conditions to enable a feature for a particular channel.
class FeatureChannelSetting {
  const FeatureChannelSetting({
    this.available = false,
    this.enabledByDefault = false,
  });

  /// Whether the feature is available on this channel.
  ///
316
  /// If not provided, defaults to `false`. This implies that the feature
317 318 319 320 321 322 323 324
  /// cannot be enabled even by the settings below.
  final bool available;

  /// Whether the feature is enabled by default.
  ///
  /// If not provided, defaults to `false`.
  final bool enabledByDefault;
}