Skip to content

Commit 4521d8d

Browse files
authored
refactor(flutter_tools): migrate AttachCommand to OptionDescriptor and OptionBundle (flutter#194359)
Migrates `flutter attach` to the shared option bundles and typed option descriptors introduced in flutter#194356, replacing imperative flag registration and untyped argument lookups. Part of flutter#194338 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing.
1 parent 0cca2ae commit 4521d8d

3 files changed

Lines changed: 154 additions & 85 deletions

File tree

‎packages/flutter_tools/lib/src/commands/attach.dart‎

Lines changed: 75 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,6 @@ import '../resident_runner.dart';
3434
import '../run_cold.dart';
3535
import '../run_hot.dart';
3636
import '../runner/flutter_command.dart';
37-
import '../runner/flutter_command_runner.dart';
3837
import '../vmservice.dart';
3938
import 'daemon.dart';
4039

@@ -70,72 +69,64 @@ class AttachCommand extends FlutterCommand {
7069
required ToolContext super.toolContext,
7170
required this._xcode,
7271
HotRunnerFactory? hotRunnerFactory,
73-
bool verboseHelp = false,
72+
super.verboseHelp = false,
7473
}) : _hotRunnerFactory = hotRunnerFactory ?? HotRunnerFactory(),
7574
_toolContext = toolContext {
76-
addBuildModeFlags(verboseHelp: verboseHelp, defaultToRelease: false, excludeRelease: true);
77-
usesTargetOption();
78-
usesPortOptions(verboseHelp: verboseHelp);
79-
usesIpv6Flag(verboseHelp: verboseHelp);
80-
usesFilesystemOptions(hide: !verboseHelp);
81-
usesFuchsiaOptions(hide: !verboseHelp);
82-
usesDartDefineOption();
83-
usesDeviceUserOption();
84-
addEnableExperimentation(hide: !verboseHelp);
85-
usesInitializeFromDillOption(hide: !verboseHelp);
86-
usesNativeAssetsOption(hide: !verboseHelp);
87-
argParser
88-
..addOption(
89-
'debug-port',
90-
hide: !verboseHelp,
91-
help:
92-
'(deprecated) Device port where the Dart VM Service is listening. Requires '
93-
'"--disable-service-auth-codes" to also be provided to the Flutter '
94-
'application at launch, otherwise this command will fail to connect to '
95-
'the application. In general, "--debug-url" should be used instead.',
96-
)
97-
..addOption(
98-
'debug-url',
99-
aliases: <String>['debug-uri'], // supported for historical reasons
100-
help: 'The URL at which the Dart VM Service is listening.',
101-
)
102-
..addOption(
103-
'app-id',
104-
help:
105-
'The package name (Android) or bundle identifier (iOS) for the app. '
106-
'This can be specified to avoid being prompted if multiple Dart VM Service ports '
107-
'are advertised.\n'
108-
'If you have multiple devices or emulators running, you should include the '
109-
'device hostname as well, e.g. "com.example.myApp@my-iphone".\n'
110-
'This parameter is case-insensitive.',
111-
)
112-
..addOption(
113-
'pid-file',
114-
help:
115-
'Specify a file to write the process ID to. '
116-
'You can send SIGUSR1 to trigger a hot reload '
117-
'and SIGUSR2 to trigger a hot restart. '
118-
'The file is created when the signal handlers '
119-
'are hooked and deleted when they are removed.',
120-
)
121-
..addFlag(
122-
'report-ready',
123-
help:
124-
'Print "ready" to the console after handling a keyboard command.\n'
125-
'This is primarily useful for tests and other automation, but consider '
126-
'using "--machine" instead.',
127-
hide: !verboseHelp,
128-
)
129-
..addOption('project-root', hide: !verboseHelp, help: 'Normally used only in run target.');
130-
addMachineOutputFlag(verboseHelp: verboseHelp);
131-
usesTrackWidgetCreation(verboseHelp: verboseHelp);
132-
addDdsOptions(verboseHelp: verboseHelp);
133-
addDevToolsOptions(verboseHelp: verboseHelp);
134-
usesDeviceTimeoutOption();
135-
usesDeviceConnectionOption();
136-
usesAdbLogFilteringOption(hide: !verboseHelp);
75+
enableUsesTargetOption();
76+
registerOptionBundles(const <OptionBundle>[
77+
BuildModeOptionsBundle(defaultToRelease: false, excludeRelease: true),
78+
VmServicePortOptionsBundle(),
79+
FilesystemOptionsBundle(),
80+
DeviceDiscoveryOptionsBundle(includeDeviceUser: true),
81+
ResidentCompilerOptionsBundle(),
82+
DdsAndDevToolsOptionsBundle(),
83+
]);
84+
argParser.addDescriptors(const <OptionDescriptor<Object?>>[
85+
CommonOptions.target,
86+
DebuggingOptionDescriptors.fuchsiaTargetModel,
87+
DebuggingOptionDescriptors.fuchsiaModule,
88+
CommonOptions.dartDefines,
89+
CommonOptions.dartDefineFromFile,
90+
CommonOptions.enableExperiment,
91+
_debugPort,
92+
_debugUrl,
93+
_appId,
94+
DebuggingOptionDescriptors.pidFile,
95+
DebuggingOptionDescriptors.reportReady,
96+
DebuggingOptionDescriptors.projectRoot,
97+
CommonOptions.machine,
98+
BuildInfoOptions.trackWidgetCreation,
99+
DebuggingOptionDescriptors.adbLogFiltering,
100+
], verboseHelp: verboseHelp);
137101
}
138102

103+
static const _debugPort = StringOptionDescriptor(
104+
name: 'debug-port',
105+
verboseOnly: true,
106+
help:
107+
'(deprecated) Device port where the Dart VM Service is listening. Requires '
108+
'"--disable-service-auth-codes" to also be provided to the Flutter '
109+
'application at launch, otherwise this command will fail to connect to '
110+
'the application. In general, "--debug-url" should be used instead.',
111+
);
112+
113+
static const _debugUrl = StringOptionDescriptor(
114+
name: 'debug-url',
115+
aliases: <String>['debug-uri'], // supported for historical reasons
116+
help: 'The URL at which the Dart VM Service is listening.',
117+
);
118+
119+
static const _appId = StringOptionDescriptor(
120+
name: 'app-id',
121+
help:
122+
'The package name (Android) or bundle identifier (iOS) for the app. '
123+
'This can be specified to avoid being prompted if multiple Dart VM Service ports '
124+
'are advertised.\n'
125+
'If you have multiple devices or emulators running, you should include the '
126+
'device hostname as well, e.g. "com.example.myApp@my-iphone".\n'
127+
'This parameter is case-insensitive.',
128+
);
129+
139130
final HotRunnerFactory _hotRunnerFactory;
140131
final ToolContext _toolContext;
141132
final BuildSystem _buildSystem;
@@ -172,18 +163,19 @@ known, it can be explicitly provided to attach via the command-line, e.g.
172163
bool get refreshWirelessDevices => true;
173164

174165
int? get debugPort {
175-
if (argResults!['debug-port'] == null) {
166+
final String? port = getValue(_debugPort);
167+
if (port == null) {
176168
return null;
177169
}
178170
try {
179-
return int.parse(stringArg('debug-port')!);
171+
return int.parse(port);
180172
} on Exception catch (error) {
181173
throwToolExit('Invalid port for `--debug-port`: $error');
182174
}
183175
}
184176

185177
Uri? get debugUri {
186-
final String? debugUrl = stringArg('debug-url');
178+
final String? debugUrl = getValue(_debugUrl);
187179
if (debugUrl == null) {
188180
return null;
189181
}
@@ -197,11 +189,9 @@ known, it can be explicitly provided to attach via the command-line, e.g.
197189
return uri;
198190
}
199191

200-
String? get appId {
201-
return stringArg('app-id');
202-
}
192+
String? get appId => getValue(_appId);
203193

204-
String? get userIdentifier => stringArg(FlutterOptions.kDeviceUser);
194+
String? get userIdentifier => getValue(CommonOptions.deviceUser);
205195

206196
@override
207197
Future<void> validateCommand() async {
@@ -221,15 +211,15 @@ known, it can be explicitly provided to attach via the command-line, e.g.
221211
if (!_isIOSDevice(targetDevice) &&
222212
debugPort == null &&
223213
debugUri == null &&
224-
argResults!.wasParsed(FlutterCommand.ipv6Flag)) {
214+
wasParsed(DebuggingOptionDescriptors.ipv6)) {
225215
throwToolExit(
226216
'When the --debug-port or --debug-url is unknown, this command determines '
227217
'the value of --ipv6 on its own.',
228218
);
229219
}
230220
if (debugPort == null &&
231221
debugUri == null &&
232-
argResults!.wasParsed(FlutterCommand.vmServicePortOption)) {
222+
wasParsed(DebuggingOptionDescriptors.vmServicePort)) {
233223
throwToolExit(
234224
'When the --debug-port or --debug-url is unknown, this command does not use '
235225
'the value of --vm-service-port.',
@@ -242,7 +232,7 @@ known, it can be explicitly provided to attach via the command-line, e.g.
242232
if (userIdentifier != null) {
243233
final Device? device = await findTargetDevice();
244234
if (device is! AndroidDevice) {
245-
throwToolExit('--${FlutterOptions.kDeviceUser} is only supported for Android');
235+
throwToolExit('--${CommonOptions.deviceUser.name} is only supported for Android');
246236
}
247237
}
248238
}
@@ -255,7 +245,7 @@ known, it can be explicitly provided to attach via the command-line, e.g.
255245
throwToolExit('Did not find any valid target devices.');
256246
}
257247

258-
final bool machineMode = boolArg(FlutterGlobalOptions.kMachineFlag);
248+
final bool machineMode = getValue(CommonOptions.machine);
259249

260250
try {
261251
await (machineMode ? _attachDaemon(device: device) : _attach(device: device));
@@ -297,8 +287,8 @@ known, it can be explicitly provided to attach via the command-line, e.g.
297287
terminal: terminal,
298288
signals: signals,
299289
processInfo: processInfo,
300-
reportReady: boolArg('report-ready'),
301-
pidFile: stringArg('pid-file'),
290+
reportReady: getValue(DebuggingOptionDescriptors.reportReady),
291+
pidFile: getValue(DebuggingOptionDescriptors.pidFile),
302292
)
303293
..registerSignalHandlers()
304294
..setupTerminal();
@@ -368,7 +358,7 @@ known, it can be explicitly provided to attach via the command-line, e.g.
368358
toolContext: toolContext,
369359
buildInfo: buildInfo,
370360
target: targetFile,
371-
targetModelOverride: TargetModel(stringArg('target-model')!),
361+
targetModelOverride: TargetModel(getValue(DebuggingOptionDescriptors.fuchsiaTargetModel)),
372362
userIdentifier: userIdentifier,
373363
);
374364
flutterDevice.vmServiceUri = vmServiceUri;
@@ -380,21 +370,22 @@ known, it can be explicitly provided to attach via the command-line, e.g.
380370
devToolsServerAddress: devToolsServerAddress,
381371
usingCISystem: usingCISystem,
382372
debugLogsDirectoryPath: debugLogsDirectoryPath,
383-
enableDevTools: boolArg(FlutterCommand.kEnableDevTools),
373+
enableDevTools: getValue(DebuggingOptionDescriptors.enableDevTools),
384374
ipv6: ipv6!,
385-
printDtd: boolArg(FlutterGlobalOptions.kPrintDtd, global: true),
375+
printDtd: getValue(CommonOptions.printDtd),
386376
adbLogFiltering:
387-
argParser.options.containsKey('adb-log-filtering') && boolArg('adb-log-filtering'),
377+
hasOption(DebuggingOptionDescriptors.adbLogFiltering) &&
378+
getValue(DebuggingOptionDescriptors.adbLogFiltering),
388379
);
389380

390381
return buildInfo.isDebug
391382
? _hotRunnerFactory.build(
392383
flutterDevices,
393384
target: targetFile,
394385
debuggingOptions: debuggingOptions,
395-
projectRootPath: stringArg('project-root'),
396-
dillOutputPath: stringArg('output-dill'),
397-
nativeAssetsYamlFile: stringArg(FlutterOptions.kNativeAssetsYamlFile),
386+
projectRootPath: getValue(DebuggingOptionDescriptors.projectRoot),
387+
dillOutputPath: getValue(BuildInfoOptions.outputDill),
388+
nativeAssetsYamlFile: getValue(BuildInfoOptions.nativeAssetsYamlFile),
398389
analytics: analytics,
399390
buildSystem: _buildSystem,
400391
buildTargets: _buildTargets,
@@ -437,7 +428,7 @@ known, it can be explicitly provided to attach via the command-line, e.g.
437428

438429
final VMServiceDiscoveryForAttach vmServiceDiscovery = device.getVMServiceDiscoveryForAttach(
439430
appId: appId,
440-
fuchsiaModule: stringArg('module'),
431+
fuchsiaModule: getValue(DebuggingOptionDescriptors.fuchsiaModule),
441432
filterDevicePort: devicePort,
442433
expectedHostPort: hostVmservicePort,
443434
ipv6: usesIpv6,

‎packages/flutter_tools/lib/src/runner/options/common_options.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -237,7 +237,6 @@ abstract final class BuildInfoOptions {
237237
static const trackWidgetCreation = FlagOptionDescriptor(
238238
name: 'track-widget-creation',
239239
defaultsTo: true,
240-
verboseOnly: true,
241240
help:
242241
'Track widget creation locations. This enables features such as the widget inspector. '
243242
'This parameter is only functional in debug mode (i.e. when compiling JIT, not AOT).',
@@ -875,6 +874,7 @@ abstract final class DebuggingOptionDescriptors {
875874
static const adbLogFiltering = FlagOptionDescriptor(
876875
name: 'adb-log-filtering',
877876
defaultsTo: true,
877+
verboseOnly: true,
878878
help:
879879
'Filter adb logs so that logs not emitted by the current flutter application are not '
880880
'displayed.',

‎packages/flutter_tools/test/commands.shard/hermetic/attach_test.dart‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1517,6 +1517,84 @@ void main() {
15171517
},
15181518
);
15191519
});
1520+
1521+
testUsingContext('preserves expected hidden and visible options across verboseHelp modes', () {
1522+
final defaultCommand = AttachCommand(
1523+
buildSystem: buildSystem,
1524+
buildTargets: const BuildTargetsImpl(),
1525+
xcode: null,
1526+
toolContext: createToolContext(),
1527+
);
1528+
1529+
final visibleByDefault = <String>{
1530+
for (final entry in defaultCommand.argParser.options.entries)
1531+
if (!entry.value.hide) entry.key,
1532+
};
1533+
final hiddenByDefault = <String>{
1534+
for (final entry in defaultCommand.argParser.options.entries)
1535+
if (entry.value.hide) entry.key,
1536+
};
1537+
1538+
expect(
1539+
visibleByDefault,
1540+
unorderedEquals(<String>[
1541+
'help',
1542+
'debug',
1543+
'profile',
1544+
'target',
1545+
'device-vmservice-port',
1546+
'host-vmservice-port',
1547+
'dart-define',
1548+
'dart-define-from-file',
1549+
'device-user',
1550+
'device-timeout',
1551+
'device-connection',
1552+
'dds',
1553+
'dds-port',
1554+
'debug-url',
1555+
'app-id',
1556+
'pid-file',
1557+
'track-widget-creation',
1558+
]),
1559+
);
1560+
expect(
1561+
hiddenByDefault,
1562+
unorderedEquals(<String>[
1563+
'vm-service-port',
1564+
'ipv6',
1565+
'output-dill',
1566+
'filesystem-root',
1567+
'filesystem-scheme',
1568+
'initialize-from-dill',
1569+
'assume-initialize-from-dill-up-to-date',
1570+
'native-assets-yaml-file',
1571+
'disable-dds',
1572+
'devtools',
1573+
'devtools-server-address',
1574+
'target-model',
1575+
'module',
1576+
'enable-experiment',
1577+
'debug-port',
1578+
'report-ready',
1579+
'project-root',
1580+
'machine',
1581+
'adb-log-filtering',
1582+
]),
1583+
);
1584+
1585+
final verboseCommand = AttachCommand(
1586+
buildSystem: buildSystem,
1587+
buildTargets: const BuildTargetsImpl(),
1588+
xcode: null,
1589+
toolContext: createToolContext(),
1590+
verboseHelp: true,
1591+
);
1592+
final hiddenInVerboseMode = <String>{
1593+
for (final entry in verboseCommand.argParser.options.entries)
1594+
if (entry.value.hide) entry.key,
1595+
};
1596+
expect(hiddenInVerboseMode, isEmpty);
1597+
});
15201598
});
15211599
}
15221600

0 commit comments

Comments
 (0)