features.dart 9.48 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 the windows UWP embedding is enabled.
  bool get isWindowsUwpEnabled => false;

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

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

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

/// The [Feature] for macOS desktop.
const Feature flutterMacOSDesktopFeature = Feature(
94
  name: 'beta-quality support for desktop on macOS',
95
  configSetting: 'enable-macos-desktop',
96
  environmentOverride: 'FLUTTER_MACOS',
97
  extraHelpText: 'Newer beta versions are available on the beta channel.',
98 99 100
  master: FeatureChannelSetting(
    available: true,
  ),
101
  beta: FeatureChannelSetting(
102
    available: true,
103 104
  ),
  stable: FeatureChannelSetting(
105
    available: true,
106
  ),
107 108 109 110
);

/// The [Feature] for Linux desktop.
const Feature flutterLinuxDesktopFeature = Feature(
111
  name: 'beta-quality support for desktop on Linux',
112
  configSetting: 'enable-linux-desktop',
113
  environmentOverride: 'FLUTTER_LINUX',
114
  extraHelpText: 'Newer beta versions are available on the beta channel.',
115 116 117
  master: FeatureChannelSetting(
    available: true,
  ),
118
  beta: FeatureChannelSetting(
119
    available: true,
120 121
  ),
  stable: FeatureChannelSetting(
122
    available: 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
/// The feature for enabling the Windows UWP embedding.
216 217 218 219 220 221 222 223
const Feature windowsUwpEmbedding = Feature(
  name: 'Flutter for Windows UWP',
  configSetting: 'enable-windows-uwp-desktop',
  master: FeatureChannelSetting(
    available: true,
  ),
);

224 225 226 227 228 229
/// 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.
230
/// Otherwise, more specific settings take precedence over higher level
231 232 233 234
/// settings.
class Feature {
  /// Creates a [Feature].
  const Feature({
235
    required this.name,
236 237
    this.environmentOverride,
    this.configSetting,
238
    this.extraHelpText,
239 240
    this.master = const FeatureChannelSetting(),
    this.beta = const FeatureChannelSetting(),
241
    this.stable = const FeatureChannelSetting()
242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262
  });

  /// 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.
263
  final String? environmentOverride;
264 265 266 267

  /// 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.
268
  final String? configSetting;
269

270 271 272
  /// Additional text to add to the end of the help message.
  ///
  /// If not provided, defaults to `null` meaning there is no additional text.
273
  final String? extraHelpText;
274

275
  /// A help message for the `flutter config` command, or null if unsupported.
276
  String? generateHelpMessage() {
277 278 279
    if (configSetting == null) {
      return null;
    }
280 281
    final StringBuffer buffer = StringBuffer('Enable or disable $name. '
        'This setting will take effect on ');
282 283 284 285 286 287 288
    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.');
289 290
    } else if (channels.length == 2) {
      buffer.write('the ${channels.join(' and ')} channels.');
291
    } else {
292 293 294
      final String prefix = (channels.toList()
        ..removeLast()).join(', ');
      buffer.write('the $prefix, and ${channels.last} channels.');
295
    }
296 297 298
    if (extraHelpText != null) {
      buffer.write(' $extraHelpText');
    }
299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324
    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.
  ///
325
  /// If not provided, defaults to `false`. This implies that the feature
326 327 328 329 330 331 332 333
  /// 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;
}