Initial API for the Dart front_end package.

pkg/front_end/lib/kernel_generator.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.
+
+/// Defines the front-end API for converting source code to Dart Kernel objects.
+library front_end.kernel_generator;
+
+import 'dart:async';
+import 'options.dart';
+import 'package:kernel/kernel.dart' as kernel;
+
+/// Processes the program whose main library is in the given [source].

[Siggi Cherem (dart-lang), 2016/10/17 16:27:29]

Processes => Generate Kernel for ... 

[Paul Berry, 2016/10/17 17:04:27]

Done.

+///
+/// Intended for whole program (non-modular) compilation.
+///
+/// Given the Uri of a file containing a program's `main` method, this function
+/// follows `import`, `export`, and `part` declarations to discover the whole
+/// program, and converts the result to Dart Kernel format.
+///
+/// If summaries are provided in [options], they may be used to speed up
+/// analysis, but they will not take the place of Dart source code (since the
+/// Dart source code is still needed to access the contents of method bodies).
+Future<kernel.Program> compileProgram(Options options, Uri source) =>

[Brian Wilkerson, 2016/10/17 15:08:14]

Using "compile" seems wrong here (and below), because this is only doing part of
the work that I think "compile" is typically used to mean. I don't like
"analyze" any better, because this is still a subset. I'm not sure what to
suggest, but I think it would be worth trying to find a better name. I'd even
prefer something generic, such as "process" or "create", or a made-up term, such
as "kernelize". One of the properties of the Kernel form is that it lowers Dart
to a more primitive form, so perhaps something like "lower".

[Siggi Cherem (dart-lang), 2016/10/17 16:27:29]

other ideas:
 - generateKernel
 - programToKernel
 - lowerProgramToKernel
 - programKernelFor

another nit: consider moving options as a second argument.

[Paul Berry, 2016/10/17 17:04:27]

I like the "fooFor" convention, but when we need to disambiguate possible things
that might be converted to form "foo", it's not obvious to me that "barFooFor"
means "convert a bar to a foo".  How about "kernelForProgram"?  I think it's
pretty intuitive for that to mean "convert a program to kernel form".
Done.

+    throw new UnimplementedError();
+
+/// Processes the build unit whose source files are in [sources].
+///
+/// Intended for modular compilation.
+///
+/// [sources] should be the complete set of source files for a build unit
+/// (including both library and part files).  All of the library files are
+/// compiled to Dart Kernel objects.

[Brian Wilkerson, 2016/10/17 15:08:14]

nit: Does Kernel have a name for its representation of a library other than
"object"? If so, it would be better to be more specific.

[Paul Berry, 2016/10/17 17:04:27]

Kernel calls them "Library".  Changed to "Dart Kernel Library objects".

+///
+/// The compilation process is hermetic, meaning that the only files which will
+/// be read are those listed in [sources], [Options.inputSummaries], and
+/// [Options.sdkSummary].  If a source file attempts to refer to a file which is
+/// not obtainable from these paths, that will result in an error, even if the
+/// file exists on the filesystem.
+///
+/// Any `part` declarations found in [sources] must refer to part files which
+/// are also listed in [sources], otherwise an error results.  (It is not
+/// permitted to refer to a part file declared in another build unit).
+///
+/// The return value is a [kernel.Program] object with no main method set.
+///
+/// TODO(paulberry): does additional information need to be output to allow the
+/// caller to match up referenced elements to the summary files they were
+/// obtained from?
+Future<kernel.Program> compileBuildUnit(Options options, List<Uri> sources) =>

[Siggi Cherem (dart-lang), 2016/10/17 16:27:29]

if we rename "compileProgram", I'd rename this too to match. My thinking is:

programKernelFor(source, options);
buildUnitKernelFor(List sources, options); // or moduleKernelFor(List sources,
options);

I've seen the style "somethingFor" a lot in dart2js, so I've grown to like it.
If we pick that, I'd suggest renaming the others (resolveBuildUnit =>
resolvedAstFor, summarizeBuildUnit => summaryFor)

[Siggi Cherem (dart-lang), 2016/10/17 16:27:29]

nit: change the return type, since a build-unit is not a kernel.Program, maybe
List<kernel.Library>? (not sure if this is related to your TODO above)

[Paul Berry, 2016/10/17 17:04:27]

Went with "kernelForBuildUnit" here, and "resolvedAstFor"/"summaryFor" in the
other files (where there is no ambiguity).

[Paul Berry, 2016/10/17 17:04:27]

kernel.Program also contains a `uriToLineStarts` map, which I think will still
be needed in the case of modular compilation.  But it might be even better to
add a data type to kernel to represent the result of compiling a build unit. 
I've added a TODO to that effect.

+    throw new UnimplementedError();