Tweak public APIs and use them in patch_sdk, dart2js, and kernel-service

pkg/front_end/lib/compiler_options.dart

 // Copyright (c) 2016, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 library front_end.compiler_options;
 
 import 'package:front_end/src/base/performace_logger.dart';
 import 'package:front_end/src/incremental/byte_store.dart';
+import 'package:kernel/target/targets.dart' show Target;
 
 import 'compilation_error.dart';
 import 'file_system.dart';
 import 'physical_file_system.dart';
 
 /// Default error handler used by [CompilerOptions.onError].
 void defaultErrorHandler(CompilationError error) => throw error;
 
 /// Callback used to report errors encountered during compilation.
 typedef void ErrorHandler(CompilationError error);
 
 /// Front-end options relevant to compiler back ends.
 ///
 /// Not intended to be implemented or extended by clients.
 class CompilerOptions {
   /// The URI of the root of the Dart SDK (typically a "file:" URI).
   ///
   /// If `null`, the SDK will be searched for using
   /// [Platform.resolvedExecutable] as a starting point.
-  ///
-  /// This option is mutually exclusive with [sdkSummary].
   Uri sdkRoot;
 
-  /// Map of `dart.xyz` libraries to URIs in the [fileSystem].
-  /// E.g. {'core': 'file:///sdk/lib/core/core.dart'} (no `dart:` prefix).
-  Map<String, Uri> dartLibraries = {};
+  /// Map of `dart:*` libraries to URIs in the [fileSystem].
+  ///
+  /// Keys in the map are the name of the library with no `dart:` prefix, for
+  /// example:
+  ///
+  ///      {'core': 'file:///sdk/lib/core/core.dart'}
+  ///
+  /// If `null`, the default set of libraries will be loaded from
+  /// `sdkRoot/lib/libraries.json`.
+  // TODO(sigmund): also provide an option to specify the .json file, then
+  // consider dropping this option.
+  Map<String, Uri> dartLibraries;
 
   /// Callback to which compilation errors should be delivered.
   ///
   /// By default, the first error will be reported by throwing an exception of
   /// type [CompilationError].
   ErrorHandler onError = defaultErrorHandler;
 
   /// URI of the ".packages" file (typically a "file:" URI).
   ///
   /// If `null`, the ".packages" file will be found via the standard
   /// package_config search algorithm.
   ///
   /// If the URI's path component is empty (e.g. `new Uri()`), no packages file
   /// will be used.
   Uri packagesFileUri;
 
   /// URIs of input summary files (excluding the SDK summary; typically these
-  /// will be "file:" URIs).  These files should all be linked summaries.  They
-  /// should also be closed, in the sense that any libraries they reference
-  /// should also appear in [inputSummaries] or [sdkSummary].
+  /// will be "file:" URIs).
+  ///
+  /// These files should be summary files generated by this package (and not the
+  /// similarly named summary files from `package:analyzer`.)
+  ///
+  /// Summaries may be provided in any order, but they should be acyclic and
+  /// closed: any libraries that they reference should be defined in either one
+  /// of [inputSummaries] or [sdkSummary].
   List<Uri> inputSummaries = [];
 
+  /// URIs of other kernel programs to link.
+  ///
+  /// Commonly used to link the code for the SDK libraries that was compiled
+  /// separately. For example, dart2js needs to link the SDK so it can
+  /// optimize and tree-shake the code for the application, whereas the VM
+  /// always embeds the SDK internally and doesn't need it as part of the
+  /// program.
+  ///
+  /// The programs provided here should be closed and acyclic: any libraries
+  /// that they reference should be defined in a program in [linkedDependencies]
+  /// or any of the [inputSummaries] or [sdkSummary].
+  List<Uri> linkedDependencies = [];
+
   /// URI of the SDK summary file (typically a "file:" URI).
   ///
-  /// This should be a linked summary.  If `null`, the SDK summary will be
-  /// searched for at a default location within [sdkRoot].
+  /// This should should be a summary previosly generated by this package (and
+  /// not the similarly named summary files from `package:analyzer`.)
   ///
-  /// This option is mutually exclusive with [sdkRoot].  TODO(paulberry): if the
-  /// VM does not contain a pickled copy of the SDK, we might need to change
-  /// this.
+  /// If `null` and [compileSdk] is false, the SDK summary will be searched for
+  /// at a default location within [sdkRoot].
   Uri sdkSummary;
 
-  /// URI override map.
-  ///
-  /// This is a map from URIs that might appear in import/export/part statements
-  /// to URIs that should be used to locate the corresponding files in the
-  /// [fileSystem].  Any URI override listed in this map takes precedence over
-  /// the URI resolution that would be implied by the packages file (see
-  /// [packagesFileUri]) and/or [multiRoots].
-  ///
-  /// If a URI is not listed in this map, then the normal URI resolution
-  /// algorithm will be used.
-  ///
-  /// TODO(paulberry): transition analyzer and dev_compiler to use the
-  /// "multi-root:" mechanism, and then remove this.
-  @deprecated
-  Map<Uri, Uri> uriOverride = {};
-
   /// Multi-roots.
   ///
-  /// Any Uri that resolves to "multi-root:///$rest" will be searched for
-  /// at "$root/$rest", where "$root" is drawn from this list.
+  /// Any Uri that resolves to "multi-root:///$absolute-path" will be searched

[Paul Berry, 2017/07/04 15:12:14]

Nit: consider changing this to "multi-root:///$absolute_path" to minimize
confusion.  Brains which are used to Dart syntax might incorrectly interpret
"multi-root:///$absolute-path" as meaning "multi-root:///${absolute}-path" :)

[Siggi Cherem (dart-lang), 2017/07/05 18:42:11]

Done.

+  /// for at "$root/$absolute-path", where "$root" is drawn from this list.
   ///
   /// Intended use: if the user has a Bazel workspace located at path
   /// "$workspace", this could be set to the file URIs corresponding to the
   /// paths for "$workspace", "$workspace/bazel-bin",
   /// and "$workspace/bazel-genfiles", effectively overlaying source and
   /// generated files.
   List<Uri> multiRoots = [];
 
   /// The declared variables for use by configurable imports and constant
   /// evaluation.
   Map<String, String> declaredVariables;
 
   /// The [FileSystem] which should be used by the front end to access files.
   ///
   /// All file system access performed by the front end goes through this
   /// mechanism, with one exception: if no value is specified for
   /// [packagesFileUri], the packages file is located using the actual physical
   /// file system.  TODO(paulberry): fix this.
   FileSystem fileSystem = PhysicalFileSystem.instance;
 
-  /// The byte storage to get and put serialized data.
+  /// The byte storage to access serialized data.
   ByteStore byteStore = new NullByteStore();
 
   /// The logger to report compilation progress.
   PerformanceLog logger = new PerformanceLog(new StringBuffer());
 
-  /// Whether to generate code for the SDK when compiling a whole-program.
+  /// Whether to generate code for the SDK.
+  ///
+  /// By default the front end resolves programs using a prebuilt SDK summary.
+  /// When this option is `true`, [sdkSummary] must be null.
   bool compileSdk = false;
 
-  /// Whether a modular build compiles only the files listed explicitly or if it
-  /// compiles dependencies as well.
+  /// Whether the compiler should read files that are discovered as
+  /// dependencies, or only access the files listed explicitly.
   ///
-  /// This option is intended only for modular APIs like `kernelForBuildUnit`.
-  /// These APIs by default ensure that builds are hermetic, where all files
-  /// that will be compiled are listed explicitly and all other dependencies
-  /// are covered by summary files.
+  /// This option has different defaults depending on the API.
   ///
-  /// When this option is true, these APIs will treat any dependency that is
-  /// not described in a summary as if it was explicitly listed as an input.
-  bool chaseDependencies = false;
+  /// For modular APIs like `kernelForBuildUnit` and `summaryFor` the default
+  /// behavior is `false`. These APIs want to ensure that builds are hermetic,
+  /// where all files that will be compiled are listed explicitly and all other
+  /// dependencies are covered by summary files.
+  ///
+  /// For whole-program APIs like `kernelForProgram`, this option is true by
+  /// default, so they can treat any dependency that is not described in a
+  /// summary as if it was explicitly listed as an input.
+  bool chaseDependencies;
 
   /// Whether to interpret Dart sources in strong-mode.
   bool strongMode = true;
 
-  // All options below are target-specific options.
-  //
-  // TODO(sigmund): revisit the right layout for these options. We might want to
-  // split them out into a separate bag of options or provide factories for
-  // common combinations of these options.
-
   /// Patch files to apply on the core libraries for a specific target platform.
   ///
-  /// Keys on this map are expected to be `dart:*` URIs. The values can be
-  /// either absolute or relative URIs. Absolute URIs are read directly, while
-  /// relative URIs are resolved from the [sdkRoot].
-  Map<Uri, List<Uri>> targetPatches = {};
+  /// Keys in the map are the name of the library with no `dart:` prefix, for
+  /// example:
+  ///
+  ///      {'core': [
+  ///         'file:///location/of/core/patch_file1.dart',
+  ///         'file:///location/of/core/patch_file2.dart',
+  ///         ]}
+  ///
+  /// The values can be either absolute or relative URIs. Absolute URIs are read
+  /// directly, while relative URIs are resolved from the [sdkRoot].
+  // TODO(sigmund): provide also a flag to load this data from a file (like
+  // libraries.json)
+  Map<String, List<Uri>> targetPatches = {};
 
-  /// Additional core libraries to be loaded when building a program.
-  // TODO(sigmund): delete. Ideally building a program only needs what's
-  // reachable and we can use kernelForBuildUnit when creating a snapshot of the
-  // SDK itself.
-  List<Uri> additionalLibraries = [];
+  /// The target platform that will consume the compiled code.
+  ///
+  /// Used to provide platform-specific details to the compiler like:
+  ///   * the set of libraries are part of a platform's SDK (e.g. dart:html for
+  ///     dart2js, dart:ui for flutter).
+  ///
+  ///   * what kernel transformations should be applied to the program
+  ///     (async/await, mixin inlining, etc).
+  ///
+  ///   * how to deal with non-standard features like `native` extensions.
+  ///
+  /// If not specified, the default target is the VM.
+  Target target;
+
+  /// Whether to show verbose messages (mainly for debugging and performance
+  /// tracking).
+  ///
+  /// Messages are printed on stdout.
+  // TODO(sigmund): improve the diagnotics API to provide mechanism to intercept
+  // verbose data (Issue #30056)
+  bool verbose = false;
+
+  /// Whether to run extra verification steps to validate that compiled programs
+  /// are well formed.
+  ///
+  /// Errors are reported via the [onError] callback.
+  // TODO(sigmund): ensure we don't print errors to stdout (Issue #30056)
+  bool verify = false;
+
+  /// Whether to dump generated programs in a text format (also mainly for
+  /// debugging).
+  ///
+  /// Dumped data is printed in stdout.
+  bool debugDump = false;
 }