forked from flutter/flutter
-
Notifications
You must be signed in to change notification settings - Fork 0
/
flutter_command.dart
1853 lines (1657 loc) · 71.9 KB
/
flutter_command.dart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
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
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
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
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// Copyright 2014 The Flutter Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
import 'package:args/args.dart';
import 'package:args/command_runner.dart';
import 'package:file/file.dart';
import 'package:meta/meta.dart';
import 'package:package_config/package_config_types.dart';
import '../application_package.dart';
import '../base/common.dart';
import '../base/context.dart';
import '../base/io.dart' as io;
import '../base/os.dart';
import '../base/user_messages.dart';
import '../base/utils.dart';
import '../build_info.dart';
import '../build_system/build_system.dart';
import '../bundle.dart' as bundle;
import '../cache.dart';
import '../convert.dart';
import '../dart/generate_synthetic_packages.dart';
import '../dart/package_map.dart';
import '../dart/pub.dart';
import '../device.dart';
import '../features.dart';
import '../globals.dart' as globals;
import '../project.dart';
import '../reporting/reporting.dart';
import '../web/compile.dart';
import 'flutter_command_runner.dart';
import 'target_devices.dart';
export '../cache.dart' show DevelopmentArtifact;
abstract class DotEnvRegex {
// Dot env multi-line block value regex
static final RegExp multiLineBlock = RegExp(r'^\s*([a-zA-Z_]+[a-zA-Z0-9_]*)\s*=\s*"""\s*(.*)$');
// Dot env full line value regex (eg FOO=bar)
// Entire line will be matched including key and value
static final RegExp keyValue = RegExp(r'^\s*([a-zA-Z_]+[a-zA-Z0-9_]*)\s*=\s*(.*)?$');
// Dot env value wrapped in double quotes regex (eg FOO="bar")
// Value between double quotes will be matched (eg only bar in "bar")
static final RegExp doubleQuotedValue = RegExp(r'^"(.*)"\s*(\#\s*.*)?$');
// Dot env value wrapped in single quotes regex (eg FOO='bar')
// Value between single quotes will be matched (eg only bar in 'bar')
static final RegExp singleQuotedValue = RegExp(r"^'(.*)'\s*(\#\s*.*)?$");
// Dot env value wrapped in back quotes regex (eg FOO=`bar`)
// Value between back quotes will be matched (eg only bar in `bar`)
static final RegExp backQuotedValue = RegExp(r'^`(.*)`\s*(\#\s*.*)?$');
// Dot env value without quotes regex (eg FOO=bar)
// Value without quotes will be matched (eg full value after the equals sign)
static final RegExp unquotedValue = RegExp(r'^([^#\n\s]*)\s*(?:\s*#\s*(.*))?$');
}
enum ExitStatus {
success,
warning,
fail,
killed,
}
/// [FlutterCommand]s' subclasses' [FlutterCommand.runCommand] can optionally
/// provide a [FlutterCommandResult] to furnish additional information for
/// analytics.
class FlutterCommandResult {
const FlutterCommandResult(
this.exitStatus, {
this.timingLabelParts,
this.endTimeOverride,
});
/// A command that succeeded. It is used to log the result of a command invocation.
factory FlutterCommandResult.success() {
return const FlutterCommandResult(ExitStatus.success);
}
/// A command that exited with a warning. It is used to log the result of a command invocation.
factory FlutterCommandResult.warning() {
return const FlutterCommandResult(ExitStatus.warning);
}
/// A command that failed. It is used to log the result of a command invocation.
factory FlutterCommandResult.fail() {
return const FlutterCommandResult(ExitStatus.fail);
}
final ExitStatus exitStatus;
/// Optional data that can be appended to the timing event.
/// https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#timingLabel
/// Do not add PII.
final List<String?>? timingLabelParts;
/// Optional epoch time when the command's non-interactive wait time is
/// complete during the command's execution. Use to measure user perceivable
/// latency without measuring user interaction time.
///
/// [FlutterCommand] will automatically measure and report the command's
/// complete time if not overridden.
final DateTime? endTimeOverride;
@override
String toString() => exitStatus.name;
}
/// Common flutter command line options.
abstract final class FlutterOptions {
static const String kExtraFrontEndOptions = 'extra-front-end-options';
static const String kExtraGenSnapshotOptions = 'extra-gen-snapshot-options';
static const String kEnableExperiment = 'enable-experiment';
static const String kFileSystemRoot = 'filesystem-root';
static const String kFileSystemScheme = 'filesystem-scheme';
static const String kSplitDebugInfoOption = 'split-debug-info';
static const String kDartObfuscationOption = 'obfuscate';
static const String kDartDefinesOption = 'dart-define';
static const String kDartDefineFromFileOption = 'dart-define-from-file';
static const String kBundleSkSLPathOption = 'bundle-sksl-path';
static const String kPerformanceMeasurementFile = 'performance-measurement-file';
static const String kNullSafety = 'sound-null-safety';
static const String kDeviceUser = 'device-user';
static const String kDeviceTimeout = 'device-timeout';
static const String kDeviceConnection = 'device-connection';
static const String kAnalyzeSize = 'analyze-size';
static const String kCodeSizeDirectory = 'code-size-directory';
static const String kNullAssertions = 'null-assertions';
static const String kAndroidGradleDaemon = 'android-gradle-daemon';
static const String kDeferredComponents = 'deferred-components';
static const String kAndroidProjectArgs = 'android-project-arg';
static const String kInitializeFromDill = 'initialize-from-dill';
static const String kAssumeInitializeFromDillUpToDate = 'assume-initialize-from-dill-up-to-date';
static const String kFatalWarnings = 'fatal-warnings';
static const String kUseApplicationBinary = 'use-application-binary';
static const String kWebBrowserFlag = 'web-browser-flag';
static const String kWebRendererFlag = 'web-renderer';
static const String kWebResourcesCdnFlag = 'web-resources-cdn';
static const String kWebWasmFlag = 'wasm';
}
/// flutter command categories for usage.
abstract final class FlutterCommandCategory {
static const String sdk = 'Flutter SDK';
static const String project = 'Project';
static const String tools = 'Tools & Devices';
}
abstract class FlutterCommand extends Command<void> {
/// The currently executing command (or sub-command).
///
/// Will be `null` until the top-most command has begun execution.
static FlutterCommand? get current => context.get<FlutterCommand>();
/// The option name for a custom VM Service port.
static const String vmServicePortOption = 'vm-service-port';
/// The option name for a custom VM Service port.
static const String observatoryPortOption = 'observatory-port';
/// The option name for a custom DevTools server address.
static const String kDevToolsServerAddress = 'devtools-server-address';
/// The flag name for whether to launch the DevTools or not.
static const String kEnableDevTools = 'devtools';
/// The flag name for whether or not to use ipv6.
static const String ipv6Flag = 'ipv6';
@override
ArgParser get argParser => _argParser;
final ArgParser _argParser = ArgParser(
usageLineLength: globals.outputPreferences.wrapText ? globals.outputPreferences.wrapColumn : null,
);
@override
FlutterCommandRunner? get runner => super.runner as FlutterCommandRunner?;
bool _requiresPubspecYaml = false;
/// Whether this command uses the 'target' option.
bool _usesTargetOption = false;
bool _usesPubOption = false;
bool _usesPortOption = false;
bool _usesIpv6Flag = false;
bool _usesFatalWarnings = false;
DeprecationBehavior get deprecationBehavior => DeprecationBehavior.none;
bool get shouldRunPub => _usesPubOption && boolArg('pub');
bool get shouldUpdateCache => true;
bool get deprecated => false;
/// When the command runs and this is true, trigger an async process to
/// discover devices from discoverers that support wireless devices for an
/// extended amount of time and refresh the device cache with the results.
bool get refreshWirelessDevices => false;
@override
bool get hidden => deprecated;
bool _excludeDebug = false;
bool _excludeRelease = false;
void requiresPubspecYaml() {
_requiresPubspecYaml = true;
}
void usesWebOptions({ required bool verboseHelp }) {
argParser.addOption('web-hostname',
defaultsTo: 'localhost',
help:
'The hostname that the web sever will use to resolve an IP to serve '
'from. The unresolved hostname is used to launch Chrome when using '
'the chrome Device. The name "any" may also be used to serve on any '
'IPV4 for either the Chrome or web-server device.',
hide: !verboseHelp,
);
argParser.addOption('web-port',
help: 'The host port to serve the web application from. If not provided, the tool '
'will select a random open port on the host.',
hide: !verboseHelp,
);
argParser.addOption('web-server-debug-protocol',
allowed: <String>['sse', 'ws'],
defaultsTo: 'ws',
help: 'The protocol (SSE or WebSockets) to use for the debug service proxy '
'when using the Web Server device and Dart Debug extension. '
'This is useful for editors/debug adapters that do not support debugging '
'over SSE (the default protocol for Web Server/Dart Debugger extension).',
hide: !verboseHelp,
);
argParser.addOption('web-server-debug-backend-protocol',
allowed: <String>['sse', 'ws'],
defaultsTo: 'ws',
help: 'The protocol (SSE or WebSockets) to use for the Dart Debug Extension '
'backend service when using the Web Server device. '
'Using WebSockets can improve performance but may fail when connecting through '
'some proxy servers.',
hide: !verboseHelp,
);
argParser.addOption('web-server-debug-injected-client-protocol',
allowed: <String>['sse', 'ws'],
defaultsTo: 'ws',
help: 'The protocol (SSE or WebSockets) to use for the injected client '
'when using the Web Server device. '
'Using WebSockets can improve performance but may fail when connecting through '
'some proxy servers.',
hide: !verboseHelp,
);
argParser.addFlag('web-allow-expose-url',
help: 'Enables daemon-to-editor requests (app.exposeUrl) for exposing URLs '
'when running on remote machines.',
hide: !verboseHelp,
);
argParser.addFlag('web-run-headless',
help: 'Launches the browser in headless mode. Currently only Chrome '
'supports this option.',
hide: !verboseHelp,
);
argParser.addOption('web-browser-debug-port',
help: 'The debug port the browser should use. If not specified, a '
'random port is selected. Currently only Chrome supports this option. '
'It serves the Chrome DevTools Protocol '
'(https://chromedevtools.github.io/devtools-protocol/).',
hide: !verboseHelp,
);
argParser.addFlag('web-enable-expression-evaluation',
defaultsTo: true,
help: 'Enables expression evaluation in the debugger.',
hide: !verboseHelp,
);
argParser.addOption('web-launch-url',
help: 'The URL to provide to the browser. Defaults to an HTTP URL with the host '
'name of "--web-hostname", the port of "--web-port", and the path set to "/".',
);
argParser.addMultiOption(
FlutterOptions.kWebBrowserFlag,
help: 'Additional flag to pass to a browser instance at startup.\n'
'Chrome: https://www.chromium.org/developers/how-tos/run-chromium-with-flags/\n'
'Firefox: https://wiki.mozilla.org/Firefox/CommandLineOptions\n'
'Multiple flags can be passed by repeating "--${FlutterOptions.kWebBrowserFlag}" multiple times.',
valueHelp: '--foo=bar',
hide: !verboseHelp,
);
}
void usesTargetOption() {
argParser.addOption('target',
abbr: 't',
defaultsTo: bundle.defaultMainPath,
help: 'The main entry-point file of the application, as run on the device.\n'
'If the "--target" option is omitted, but a file name is provided on '
'the command line, then that is used instead.',
valueHelp: 'path');
_usesTargetOption = true;
}
void usesFatalWarningsOption({ required bool verboseHelp }) {
argParser.addFlag(FlutterOptions.kFatalWarnings,
hide: !verboseHelp,
help: 'Causes the command to fail if warnings are sent to the console '
'during its execution.'
);
_usesFatalWarnings = true;
}
String get targetFile {
if (argResults?.wasParsed('target') ?? false) {
return stringArg('target')!;
}
final List<String>? rest = argResults?.rest;
if (rest != null && rest.isNotEmpty) {
return rest.first;
}
return bundle.defaultMainPath;
}
/// Path to the Dart's package config file.
///
/// This can be overridden by some of its subclasses.
String? get packagesPath => stringArg(FlutterGlobalOptions.kPackagesOption, global: true);
/// Whether flutter is being run from our CI.
bool get usingCISystem => boolArg(FlutterGlobalOptions.kContinuousIntegrationFlag, global: true);
/// The value of the `--filesystem-scheme` argument.
///
/// This can be overridden by some of its subclasses.
String? get fileSystemScheme =>
argParser.options.containsKey(FlutterOptions.kFileSystemScheme)
? stringArg(FlutterOptions.kFileSystemScheme)
: null;
/// The values of the `--filesystem-root` argument.
///
/// This can be overridden by some of its subclasses.
List<String>? get fileSystemRoots =>
argParser.options.containsKey(FlutterOptions.kFileSystemRoot)
? stringsArg(FlutterOptions.kFileSystemRoot)
: null;
void usesPubOption({bool hide = false}) {
argParser.addFlag('pub',
defaultsTo: true,
hide: hide,
help: 'Whether to run "flutter pub get" before executing this command.');
_usesPubOption = true;
}
/// Adds flags for using a specific filesystem root and scheme.
///
/// The `hide` argument indicates whether or not to hide these options when
/// the user asks for help.
void usesFilesystemOptions({ required bool hide }) {
argParser
..addOption('output-dill',
hide: hide,
help: 'Specify the path to frontend server output kernel file.',
)
..addMultiOption(FlutterOptions.kFileSystemRoot,
hide: hide,
help: 'Specify the path that is used as the root of a virtual file system '
'during compilation. The input file name should be specified as a URL '
'using the scheme given in "--${FlutterOptions.kFileSystemScheme}".\n'
'Requires the "--output-dill" option to be explicitly specified.',
)
..addOption(FlutterOptions.kFileSystemScheme,
defaultsTo: 'org-dartlang-root',
hide: hide,
help: 'Specify the scheme that is used for virtual file system used in '
'compilation. See also the "--${FlutterOptions.kFileSystemRoot}" option.',
);
}
/// Adds options for connecting to the Dart VM Service port.
void usesPortOptions({ required bool verboseHelp }) {
argParser.addOption(vmServicePortOption,
help: '(deprecated; use host-vmservice-port instead) '
'Listen to the given port for a Dart VM Service connection.\n'
'Specifying port 0 (the default) will find a random free port.\n '
'if the Dart Development Service (DDS) is enabled, this will not be the port '
'of the VmService instance advertised on the command line.',
hide: !verboseHelp,
);
argParser.addOption(observatoryPortOption,
help: '(deprecated; use host-vmservice-port instead) '
'Listen to the given port for a Dart VM Service connection.\n'
'Specifying port 0 (the default) will find a random free port.\n '
'if the Dart Development Service (DDS) is enabled, this will not be the port '
'of the VmService instance advertised on the command line.',
hide: !verboseHelp,
);
argParser.addOption('device-vmservice-port',
help: 'Look for vmservice connections only from the specified port.\n'
'Specifying port 0 (the default) will accept the first vmservice '
'discovered.',
);
argParser.addOption('host-vmservice-port',
help: 'When a device-side vmservice port is forwarded to a host-side '
'port, use this value as the host port.\nSpecifying port 0 '
'(the default) will find a random free host port.'
);
_usesPortOption = true;
}
/// Add option values for output directory of artifacts
void usesOutputDir() {
// TODO(eliasyishak): this feature has been added to [BuildWebCommand] and
// [BuildAarCommand]
argParser.addOption('output',
abbr: 'o',
aliases: <String>['output-dir'],
help:
'The absolute path to the directory where the repository is generated. '
'By default, this is <current-directory>/build/<target-platform>.\n'
'Currently supported for subcommands: aar, web.');
}
void addDevToolsOptions({required bool verboseHelp}) {
argParser.addFlag(
kEnableDevTools,
hide: !verboseHelp,
defaultsTo: true,
help: 'Enable (or disable, with "--no-$kEnableDevTools") the launching of the '
'Flutter DevTools debugger and profiler. '
'If specified, "--$kDevToolsServerAddress" is ignored.'
);
argParser.addOption(
kDevToolsServerAddress,
hide: !verboseHelp,
help: 'When this value is provided, the Flutter tool will not spin up a '
'new DevTools server instance, and will instead use the one provided '
'at the given address. Ignored if "--no-$kEnableDevTools" is specified.'
);
}
void addDdsOptions({required bool verboseHelp}) {
argParser.addOption('dds-port',
help: 'When this value is provided, the Dart Development Service (DDS) will be '
'bound to the provided port.\n'
'Specifying port 0 (the default) will find a random free port.'
);
argParser.addFlag(
'dds',
hide: !verboseHelp,
defaultsTo: true,
help: 'Enable the Dart Developer Service (DDS).\n'
'It may be necessary to disable this when attaching to an application with '
'an existing DDS instance (e.g., attaching to an application currently '
'connected to by "flutter run"), or when running certain tests.\n'
'Disabling this feature may degrade IDE functionality if a DDS instance is '
'not already connected to the target application.'
);
argParser.addFlag(
'disable-dds',
hide: !verboseHelp,
help: '(deprecated; use "--no-dds" instead) '
'Disable the Dart Developer Service (DDS).'
);
}
void addServeObservatoryOptions({required bool verboseHelp}) {
argParser.addFlag('serve-observatory',
hide: !verboseHelp,
help: 'Serve the legacy Observatory developer tooling through the VM service.',
);
}
late final bool enableDds = () {
bool ddsEnabled = false;
if (argResults?.wasParsed('disable-dds') ?? false) {
if (argResults?.wasParsed('dds') ?? false) {
throwToolExit(
'The "--[no-]dds" and "--[no-]disable-dds" arguments are mutually exclusive. Only specify "--[no-]dds".');
}
ddsEnabled = !boolArg('disable-dds');
// TODO(ianh): enable the following code once google3 is migrated away from --disable-dds (and add test to flutter_command_test.dart)
if (false) { // ignore: dead_code
if (ddsEnabled) {
globals.printWarning('${globals.logger.terminal
.warningMark} The "--no-disable-dds" argument is deprecated and redundant, and should be omitted.');
} else {
globals.printWarning('${globals.logger.terminal
.warningMark} The "--disable-dds" argument is deprecated. Use "--no-dds" instead.');
}
}
} else {
ddsEnabled = boolArg('dds');
}
return ddsEnabled;
}();
bool get _hostVmServicePortProvided => (argResults?.wasParsed(vmServicePortOption) ?? false)
|| (argResults?.wasParsed(observatoryPortOption) ?? false)
|| (argResults?.wasParsed('host-vmservice-port') ?? false);
int _tryParseHostVmservicePort() {
final String? vmServicePort = stringArg(vmServicePortOption) ??
stringArg(observatoryPortOption);
final String? hostPort = stringArg('host-vmservice-port');
if (vmServicePort == null && hostPort == null) {
throwToolExit('Invalid port for `--vm-service-port/--host-vmservice-port`');
}
try {
return int.parse((vmServicePort ?? hostPort)!);
} on FormatException catch (error) {
throwToolExit('Invalid port for `--vm-service-port/--host-vmservice-port`: $error');
}
}
int get ddsPort {
if (argResults?.wasParsed('dds-port') != true && _hostVmServicePortProvided) {
// If an explicit DDS port is _not_ provided, use the host-vmservice-port for DDS.
return _tryParseHostVmservicePort();
} else if (argResults?.wasParsed('dds-port') ?? false) {
// If an explicit DDS port is provided, use dds-port for DDS.
return int.tryParse(stringArg('dds-port')!) ?? 0;
}
// Otherwise, DDS can bind to a random port.
return 0;
}
Uri? get devToolsServerAddress {
if (argResults?.wasParsed(kDevToolsServerAddress) ?? false) {
final Uri? uri = Uri.tryParse(stringArg(kDevToolsServerAddress)!);
if (uri != null && uri.host.isNotEmpty && uri.port != 0) {
return uri;
}
}
return null;
}
/// Gets the vmservice port provided to in the 'vm-service-port' or
/// 'host-vmservice-port option.
///
/// Only one of "host-vmservice-port" and "vm-service-port" may be
/// specified.
///
/// If no port is set, returns null.
int? get hostVmservicePort {
if (!_usesPortOption || !_hostVmServicePortProvided) {
return null;
}
if ((argResults?.wasParsed(vmServicePortOption) ?? false)
&& (argResults?.wasParsed(observatoryPortOption) ?? false)
&& (argResults?.wasParsed('host-vmservice-port') ?? false)) {
throwToolExit('Only one of "--vm-service-port" and '
'"--host-vmservice-port" may be specified.');
}
// If DDS is enabled and no explicit DDS port is provided, use the
// host-vmservice-port for DDS instead and bind the VM service to a random
// port.
if (enableDds && argResults?.wasParsed('dds-port') != true) {
return null;
}
return _tryParseHostVmservicePort();
}
/// Gets the vmservice port provided to in the 'device-vmservice-port' option.
///
/// If no port is set, returns null.
int? get deviceVmservicePort {
final String? devicePort = stringArg('device-vmservice-port');
if (!_usesPortOption || devicePort == null) {
return null;
}
try {
return int.parse(devicePort);
} on FormatException catch (error) {
throwToolExit('Invalid port for `--device-vmservice-port`: $error');
}
}
void addPublishPort({ bool enabledByDefault = true, bool verboseHelp = false }) {
argParser.addFlag('publish-port',
hide: !verboseHelp,
help: 'Publish the VM service port over mDNS. Disable to prevent the '
'local network permission app dialog in debug and profile build modes (iOS devices only).',
defaultsTo: enabledByDefault,
);
}
Future<bool> get disablePortPublication async => !boolArg('publish-port');
void usesIpv6Flag({required bool verboseHelp}) {
argParser.addFlag(ipv6Flag,
negatable: false,
help: 'Binds to IPv6 localhost instead of IPv4 when the flutter tool '
'forwards the host port to a device port.',
hide: !verboseHelp,
);
_usesIpv6Flag = true;
}
bool? get ipv6 => _usesIpv6Flag ? boolArg('ipv6') : null;
void usesBuildNumberOption() {
argParser.addOption('build-number',
help: 'An identifier used as an internal version number.\n'
'Each build must have a unique identifier to differentiate it from previous builds.\n'
'It is used to determine whether one build is more recent than another, with higher numbers indicating more recent build.\n'
'On Android it is used as "versionCode".\n'
'On Xcode builds it is used as "CFBundleVersion".\n'
'On Windows it is used as the build suffix for the product and file versions.',
);
}
void usesBuildNameOption() {
argParser.addOption('build-name',
help: 'A "x.y.z" string used as the version number shown to users.\n'
'For each new version of your app, you will provide a version number to differentiate it from previous versions.\n'
'On Android it is used as "versionName".\n'
'On Xcode builds it is used as "CFBundleShortVersionString".\n'
'On Windows it is used as the major, minor, and patch parts of the product and file versions.',
valueHelp: 'x.y.z');
}
void usesDartDefineOption() {
argParser.addMultiOption(
FlutterOptions.kDartDefinesOption,
aliases: <String>[ kDartDefines ], // supported for historical reasons
help: 'Additional key-value pairs that will be available as constants '
'from the String.fromEnvironment, bool.fromEnvironment, and int.fromEnvironment '
'constructors.\n'
'Multiple defines can be passed by repeating "--${FlutterOptions.kDartDefinesOption}" multiple times.',
valueHelp: 'foo=bar',
splitCommas: false,
);
useDartDefineFromFileOption();
}
void useDartDefineFromFileOption() {
argParser.addMultiOption(
FlutterOptions.kDartDefineFromFileOption,
help:
'The path of a .json or .env file containing key-value pairs that will be available as environment variables.\n'
'These can be accessed using the String.fromEnvironment, bool.fromEnvironment, and int.fromEnvironment constructors.\n'
'Multiple defines can be passed by repeating "--${FlutterOptions.kDartDefineFromFileOption}" multiple times.',
valueHelp: 'use-define-config.json|.env',
splitCommas: false,
);
}
void usesWebRendererOption() {
argParser.addOption(
FlutterOptions.kWebRendererFlag,
defaultsTo: WebRendererMode.auto.name,
allowed: WebRendererMode.values.map((WebRendererMode e) => e.name),
help: 'The renderer implementation to use when building for the web.',
allowedHelp: CliEnum.allowedHelp(WebRendererMode.values)
);
}
void usesWebResourcesCdnFlag() {
argParser.addFlag(
FlutterOptions.kWebResourcesCdnFlag,
defaultsTo: true,
help: 'Use Web static resources hosted on a CDN.',
);
}
void usesDeviceUserOption() {
argParser.addOption(FlutterOptions.kDeviceUser,
help: 'Identifier number for a user or work profile on Android only. Run "adb shell pm list users" for available identifiers.',
valueHelp: '10');
}
void usesDeviceTimeoutOption() {
argParser.addOption(
FlutterOptions.kDeviceTimeout,
help: 'Time in seconds to wait for devices to attach. Longer timeouts may be necessary for networked devices.',
valueHelp: '10'
);
}
void usesDeviceConnectionOption() {
argParser.addOption(FlutterOptions.kDeviceConnection,
defaultsTo: 'both',
help: 'Discover devices based on connection type.',
allowed: <String>['attached', 'wireless', 'both'],
allowedHelp: <String, String>{
'both': 'Searches for both attached and wireless devices.',
'attached': 'Only searches for devices connected by USB or built-in (such as simulators/emulators, MacOS/Windows, Chrome)',
'wireless': 'Only searches for devices connected wirelessly. Discovering wireless devices may take longer.'
},
);
}
void usesApplicationBinaryOption() {
argParser.addOption(
FlutterOptions.kUseApplicationBinary,
help: 'Specify a pre-built application binary to use when running. For Android applications, '
'this must be the path to an APK. For iOS applications, the path to an IPA. Other device types '
'do not yet support prebuilt application binaries.',
valueHelp: 'path/to/app.apk',
);
}
/// Whether it is safe for this command to use a cached pub invocation.
bool get cachePubGet => true;
/// Whether this command should report null safety analytics.
bool get reportNullSafety => false;
late final Duration? deviceDiscoveryTimeout = () {
if ((argResults?.options.contains(FlutterOptions.kDeviceTimeout) ?? false)
&& (argResults?.wasParsed(FlutterOptions.kDeviceTimeout) ?? false)) {
final int? timeoutSeconds = int.tryParse(stringArg(FlutterOptions.kDeviceTimeout)!);
if (timeoutSeconds == null) {
throwToolExit( 'Could not parse "--${FlutterOptions.kDeviceTimeout}" argument. It must be an integer.');
}
return Duration(seconds: timeoutSeconds);
}
return null;
}();
DeviceConnectionInterface? get deviceConnectionInterface {
if ((argResults?.options.contains(FlutterOptions.kDeviceConnection) ?? false)
&& (argResults?.wasParsed(FlutterOptions.kDeviceConnection) ?? false)) {
final String? connectionType = stringArg(FlutterOptions.kDeviceConnection);
if (connectionType == 'attached') {
return DeviceConnectionInterface.attached;
} else if (connectionType == 'wireless') {
return DeviceConnectionInterface.wireless;
}
}
return null;
}
late final TargetDevices _targetDevices = TargetDevices(
platform: globals.platform,
deviceManager: globals.deviceManager!,
logger: globals.logger,
deviceConnectionInterface: deviceConnectionInterface,
);
void addBuildModeFlags({
required bool verboseHelp,
bool defaultToRelease = true,
bool excludeDebug = false,
bool excludeRelease = false,
}) {
// A release build must be the default if a debug build is not possible.
assert(defaultToRelease || !excludeDebug);
_excludeDebug = excludeDebug;
_excludeRelease = excludeRelease;
defaultBuildMode = defaultToRelease ? BuildMode.release : BuildMode.debug;
if (!excludeDebug) {
argParser.addFlag('debug',
negatable: false,
help: 'Build a debug version of your app${defaultToRelease ? '' : ' (default mode)'}.');
}
argParser.addFlag('profile',
negatable: false,
help: 'Build a version of your app specialized for performance profiling.');
if (!excludeRelease) {
argParser.addFlag('release',
negatable: false,
help: 'Build a release version of your app${defaultToRelease ? ' (default mode)' : ''}.');
argParser.addFlag('jit-release',
negatable: false,
hide: !verboseHelp,
help: 'Build a JIT release version of your app${defaultToRelease ? ' (default mode)' : ''}.');
}
}
void addSplitDebugInfoOption() {
argParser.addOption(FlutterOptions.kSplitDebugInfoOption,
help: 'In a release build, this flag reduces application size by storing '
'Dart program symbols in a separate file on the host rather than in the '
'application. The value of the flag should be a directory where program '
'symbol files can be stored for later use. These symbol files contain '
'the information needed to symbolize Dart stack traces. For an app built '
'with this flag, the "flutter symbolize" command with the right program '
'symbol file is required to obtain a human readable stack trace.\n'
'This flag cannot be combined with "--${FlutterOptions.kAnalyzeSize}".',
valueHelp: 'v1.2.3/',
);
}
void addDartObfuscationOption() {
argParser.addFlag(FlutterOptions.kDartObfuscationOption,
help: 'In a release build, this flag removes identifiers and replaces them '
'with randomized values for the purposes of source code obfuscation. This '
'flag must always be combined with "--${FlutterOptions.kSplitDebugInfoOption}" option, the '
'mapping between the values and the original identifiers is stored in the '
'symbol map created in the specified directory. For an app built with this '
'flag, the "flutter symbolize" command with the right program '
'symbol file is required to obtain a human readable stack trace.\n'
'\n'
'Because all identifiers are renamed, methods like Object.runtimeType, '
'Type.toString, Enum.toString, Stacktrace.toString, Symbol.toString '
'(for constant symbols or those generated by runtime system) will '
'return obfuscated results. Any code or tests that rely on exact names '
'will break.'
);
}
void addBundleSkSLPathOption({ required bool hide }) {
argParser.addOption(FlutterOptions.kBundleSkSLPathOption,
help: 'A path to a file containing precompiled SkSL shaders generated '
'during "flutter run". These can be included in an application to '
'improve the first frame render times.',
hide: hide,
valueHelp: 'flutter_1.sksl'
);
}
void addTreeShakeIconsFlag({
bool? enabledByDefault
}) {
argParser.addFlag('tree-shake-icons',
defaultsTo: enabledByDefault
?? kIconTreeShakerEnabledDefault,
help: 'Tree shake icon fonts so that only glyphs used by the application remain.',
);
}
void addShrinkingFlag({ required bool verboseHelp }) {
argParser.addFlag('shrink',
hide: !verboseHelp,
help: 'This flag has no effect. Code shrinking is always enabled in release builds. '
'To learn more, see: https://developer.android.com/studio/build/shrink-code'
);
}
void addNullSafetyModeOptions({ required bool hide }) {
argParser.addFlag(FlutterOptions.kNullSafety,
help: 'This flag is deprecated as only null-safe code is supported.',
defaultsTo: true,
hide: true,
);
argParser.addFlag(FlutterOptions.kNullAssertions,
help: 'This flag is deprecated as only null-safe code is supported.',
hide: true,
);
}
/// Enables support for the hidden options --extra-front-end-options and
/// --extra-gen-snapshot-options.
void usesExtraDartFlagOptions({ required bool verboseHelp }) {
argParser.addMultiOption(FlutterOptions.kExtraFrontEndOptions,
aliases: <String>[ kExtraFrontEndOptions ], // supported for historical reasons
help: 'A comma-separated list of additional command line arguments that will be passed directly to the Dart front end. '
'For example, "--${FlutterOptions.kExtraFrontEndOptions}=--enable-experiment=nonfunction-type-aliases".',
valueHelp: '--foo,--bar',
hide: !verboseHelp,
);
argParser.addMultiOption(FlutterOptions.kExtraGenSnapshotOptions,
aliases: <String>[ kExtraGenSnapshotOptions ], // supported for historical reasons
help: 'A comma-separated list of additional command line arguments that will be passed directly to the Dart native compiler. '
'(Only used in "--profile" or "--release" builds.) '
'For example, "--${FlutterOptions.kExtraGenSnapshotOptions}=--no-strip".',
valueHelp: '--foo,--bar',
hide: !verboseHelp,
);
}
void usesFuchsiaOptions({ bool hide = false }) {
argParser.addOption(
'target-model',
help: 'Target model that determines what core libraries are available.',
defaultsTo: 'flutter',
hide: hide,
allowed: const <String>['flutter', 'flutter_runner'],
);
argParser.addOption(
'module',
abbr: 'm',
hide: hide,
help: 'The name of the module (required if attaching to a fuchsia device).',
valueHelp: 'module-name',
);
}
void addEnableExperimentation({ required bool hide }) {
argParser.addMultiOption(
FlutterOptions.kEnableExperiment,
help:
'The name of an experimental Dart feature to enable. For more information see: '
'https://github.com/dart-lang/sdk/blob/main/docs/process/experimental-flags.md',
hide: hide,
);
}
void addBuildPerformanceFile({ bool hide = false }) {
argParser.addOption(
FlutterOptions.kPerformanceMeasurementFile,
help:
'The name of a file where flutter assemble performance and '
'cached-ness information will be written in a JSON format.',
hide: hide,
);
}
void addAndroidSpecificBuildOptions({ bool hide = false }) {
argParser.addFlag(
FlutterOptions.kAndroidGradleDaemon,
help: 'Whether to enable the Gradle daemon when performing an Android build. '
'Starting the daemon is the default behavior of the gradle wrapper script created '
'in a Flutter project. Setting this flag to false corresponds to passing '
'"--no-daemon" to the gradle wrapper script. This flag will cause the daemon '
'process to terminate after the build is completed.',
defaultsTo: true,
hide: hide,
);
argParser.addMultiOption(
FlutterOptions.kAndroidProjectArgs,
help: 'Additional arguments specified as key=value that are passed directly to the gradle '
'project via the -P flag. These can be accessed in build.gradle via the "project.property" API.',
splitCommas: false,
abbr: 'P',
);
}
void addNativeNullAssertions({ bool hide = false }) {
argParser.addFlag('native-null-assertions',
defaultsTo: true,
hide: hide,
help: 'Enables additional runtime null checks in web applications to ensure '
'the correct nullability of native (such as in dart:html) and external '
'(such as with JS interop) types. This is enabled by default but only takes '
'effect in sound mode. To report an issue with a null assertion failure in '
'dart:html or the other dart web libraries, please file a bug at: '
'https://github.com/dart-lang/sdk/issues/labels/web-libraries'
);
}
void usesInitializeFromDillOption({ required bool hide }) {
argParser.addOption(FlutterOptions.kInitializeFromDill,
help: 'Initializes the resident compiler with a specific kernel file instead of '
'the default cached location.',
hide: hide,
);
argParser.addFlag(FlutterOptions.kAssumeInitializeFromDillUpToDate,
help: 'If set, assumes that the file passed in initialize-from-dill is up '
'to date and skip the check and potential invalidation of files.',
hide: hide,
);
}
void addMultidexOption({ bool hide = false }) {
argParser.addFlag('multidex',
defaultsTo: true,
help: 'When enabled, indicates that the app should be built with multidex support. This '
'flag adds the dependencies for multidex when the minimum android sdk is 20 or '
'below. For android sdk versions 21 and above, multidex support is native.',
);
}
void addIgnoreDeprecationOption({ bool hide = false }) {
argParser.addFlag('ignore-deprecation',
negatable: false,
help: 'Indicates that the app should ignore deprecation warnings and continue to build '
'using deprecated APIs. Use of this flag may cause your app to fail to build when '
'deprecated APIs are removed.',
);
}
/// Adds build options common to all of the desktop build commands.
void addCommonDesktopBuildOptions({ required bool verboseHelp }) {
addBuildModeFlags(verboseHelp: verboseHelp);
addBuildPerformanceFile(hide: !verboseHelp);
addBundleSkSLPathOption(hide: !verboseHelp);
addDartObfuscationOption();
addEnableExperimentation(hide: !verboseHelp);
addNullSafetyModeOptions(hide: !verboseHelp);
addSplitDebugInfoOption();
addTreeShakeIconsFlag();
usesAnalyzeSizeFlag();
usesDartDefineOption();
usesExtraDartFlagOptions(verboseHelp: verboseHelp);
usesPubOption();
usesTargetOption();
usesTrackWidgetCreation(verboseHelp: verboseHelp);
usesBuildNumberOption();
usesBuildNameOption();
}
/// The build mode that this command will use if no build mode is
/// explicitly specified.
///
/// Use [getBuildMode] to obtain the actual effective build mode.
BuildMode defaultBuildMode = BuildMode.debug;
BuildMode getBuildMode() {
// No debug when _excludeDebug is true.
// If debug is not excluded, then take the command line flag.