[dart2js] recommend using 'dart compile js'.

This is the first deprecation step, moving towards having dart2js
under the more general dart command line interface.

Going forward 'dart compile js' is the recommended way to invoke
dart2js.

This CL adds:
* an internal flag used to detect how was dart2js invoked and
  provide a warning when invoked in an unsupported way.
* ensures the flag is provided in the dart cli, as well as our
  (developer's only) scripts. These scripts will likely move to a
  different location in the future. Note that the `dart2js_sdk*`
  scripts are not providing this flag (these are the script that get
  eventually shipped with our built SDK), as such, invokations of the
  dart2js binary will show the new warning.

Change-Id: I96e40ecf01598eadab20dfc59114f5fff7438084
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/229062
Reviewed-by: Joshua Litt <joshualitt@google.com>
Commit-Queue: Sigmund Cherem <sigmund@google.com>

CHANGELOG.md

@@ -17,6 +17,19 @@
 - `IdbFactory.supportsDatabaseNames` has been deprecated. It will always return
   `false`.
 
+### Tools
+
+#### Dart command line
+
+- **Breaking Change** [#46100](https://github.com/dart-lang/sdk/issues/46100):
+  The standalone `dart2js` tool has been
+  marked deprecated as previously announced.
+  Its replacement is the `dart compile js` command.
+  Should you find any issues, or missing features, in the replacement
+  command, kindly file [an issue][].
+
+[an issue]: https://github.com/dart-lang/sdk/issues/new
+
 ## 2.16.0
 
 ### Core libraries

pkg/compiler/lib/src/commandline_options.dart

@@ -142,6 +142,10 @@ class Flags {
 
   static const String cfeInvocationModes = '--cfe-invocation-modes';
 
+  /// Flag to indicate how the compiler is invoked. Used to ensure
+  /// dart2js is only invoked from supported tools and through the Dart CLI.
+  static const String invoker = '--invoker';
+
   /// Flag to stop after splitting the program.
   static const String stopAfterProgramSplit = '--stop-after-program-split';
 

pkg/compiler/lib/src/dart2js.dart

@@ -139,6 +139,7 @@ Future<api.CompilationResult> compile(List<String> argv,
   ReadStrategy readStrategy = ReadStrategy.fromDart;
   WriteStrategy writeStrategy = WriteStrategy.toJs;
   FeatureOptions features = FeatureOptions();
+  String invoker;
 
   void passThrough(String argument) => options.add(argument);
   void ignoreOption(String argument) {}
@@ -480,6 +481,10 @@ Future<api.CompilationResult> compile(List<String> argv,
     passThrough(argument);
   }
 
+  void setInvoker(String argument) {
+    invoker = extractParameter(argument);
+  }
+
   void handleThrowOnError(String argument) {
     throwOnError = true;
     String parameter = extractParameter(argument, isOptionalArgument: true);
@@ -645,6 +650,7 @@ Future<api.CompilationResult> compile(List<String> argv,
     OptionHandler(Flags.testMode, passThrough),
     OptionHandler('${Flags.dumpSsa}=.+', passThrough),
     OptionHandler('${Flags.cfeInvocationModes}=.+', passThrough),
+    OptionHandler('${Flags.invoker}=.+', setInvoker),
     OptionHandler('${Flags.verbosity}=.+', passThrough),
 
     // Experimental features.
@@ -694,6 +700,13 @@ Future<api.CompilationResult> compile(List<String> argv,
 
   parseCommandLine(handlers, argv);
 
+  if (invoker == null) {
+    warning("The 'dart2js' entrypoint script is deprecated, "
+        "please use 'dart compile js' instead.");
+  } else if (verbose != null) {
+    print("Compiler invoked from: '$invoker'");
+  }
+
   // TODO(johnniwinther): Measure time for reading files.
   SourceFileProvider inputProvider;
   if (bazelPaths != null) {
@@ -1128,7 +1141,7 @@ void help() {
   // before and after running the compiler. Another two lines may be
   // used to print an error message.
   print('''
-Usage: dart2js [options] dartfile
+Usage: dart compile js [options] dartfile
 
 Compiles Dart to JavaScript.
 
@@ -1140,7 +1153,7 @@ Common options:
 
 void verboseHelp() {
   print(r'''
-Usage: dart2js [options] dartfile
+Usage: dart compile js [options] dartfile
 
 Compiles Dart to JavaScript.
 
@@ -1352,6 +1365,15 @@ void helpAndFail(String message) {
   fail(message);
 }
 
+void warning(String message) {
+  if (diagnosticHandler != null) {
+    diagnosticHandler.report(
+        null, null, -1, -1, message, api.Diagnostic.WARNING);
+  } else {
+    print('Warning: $message');
+  }
+}
+
 Future<void> main(List<String> arguments) async {
   // Expand `@path/to/file`
   // When running from bazel, argument of the form `@path/to/file` might be

pkg/dartdev/lib/src/commands/compile.dart

@@ -90,6 +90,7 @@ class CompileJSCommand extends CompileSubcommandCommand {
         [
           '--libraries-spec=$librariesPath',
           '--cfe-invocation-modes=compile',
+          '--invoker=dart_cli',
           ...argResults.arguments,
         ],
         packageConfigOverride: null);

sdk/bin/dart2js

@@ -25,6 +25,7 @@ DART="$BIN_DIR/dart"
 unset EXTRA_OPTIONS
 declare -a EXTRA_OPTIONS
 
+EXTRA_OPTIONS+=('--invoker=development_script')
 if test -t 1; then
   # Stdout is a terminal.
   if test 8 -le `tput colors`; then