Add a dotty-interfaces package

We introduce a new entry point for the compiler in
`dotty.tools.dotc.Driver`:
```
def process(args: Array[String], simple: interfaces.SimpleReporter,
  callback: interfaces.CompilerCallback): interfaces.ReporterResult
```
Except for `args` which is just an array, the argument types and return
type of this method are Java interfaces defined in a new package called
`dotty-interfaces` which has a stable ABI. This means that you can
programmatically run a compiler with a custom reporter and callbacks
without having to recompile it against every version of dotty: you only
need to have `dotty-interfaces` present at compile-time and call the
`process` method using Java reflection.

See `test/test/InterfaceEntryPointTest.scala` for a concrete example.

This design is based on discussions with the IntelliJ IDEA Scala plugin
team. Thanks to Nikolay Tropin for the discussions and his PR
proposal (see #1011).

Author: smarter

bin/dotc

@@ -42,7 +42,8 @@ ReplMain=test.DottyRepl
 
 
 
-# autodetecting the compiler jar. this is location where sbt 'packages' it
+# autodetecting the compiler jars. this is the location where sbt 'packages' them
+INTERFACES_JAR=$DOTTY_ROOT/interfaces/target/dotty-interfaces-$DOTTY_VERSION.jar
 MAIN_JAR=$DOTTY_ROOT/target/scala-$SCALA_BINARY_VERSION/dotty_$SCALA_BINARY_VERSION-$DOTTY_VERSION.jar
 TEST_JAR=$DOTTY_ROOT/target/scala-$SCALA_BINARY_VERSION/dotty_$SCALA_BINARY_VERSION-$DOTTY_VERSION-tests.jar
 DOTTY_JAR=$DOTTY_ROOT/dotty.jar
@@ -62,7 +63,7 @@ function checkjar {
       echo "The required jar file was built successfully."
     fi
   else
-    NEW_FILES="$(find "$DOTTY_ROOT/$3" -iname "*.scala" -newer "$1")"
+    NEW_FILES="$(find "$DOTTY_ROOT/$3" \( -iname "*.scala" -o -iname "*.java" \) -newer "$1")"
     if [ ! -z "$NEW_FILES" ]; 
     then
       echo "new files detected. rebuilding"
@@ -74,6 +75,7 @@ function checkjar {
   fi
 }
 
+checkjar $INTERFACES_JAR interfaces/package interfaces
 checkjar $MAIN_JAR package src
 checkjar $TEST_JAR test:package test
 
@@ -198,6 +200,8 @@ classpathArgs () {
   else
     toolchain="$SCALA_LIBRARY_JAR:$SCALA_REFLECT_JAR:$SCALA_COMPILER_JAR:$JLINE_JAR"
   fi
+  bcpJars="$INTERFACES_JAR:$MAIN_JAR"
+  cpJars="$INTERFACES_JAR:$MAIN_JAR:$TEST_JAR"
 
   if [[ -n "$cygwin" ]]; then
     if [[ "$OS" = "Windows_NT" ]] && cygpath -m .>/dev/null 2>/dev/null ; then
@@ -207,18 +211,18 @@ classpathArgs () {
     fi
 
     if [[ -n $bootcp ]]; then
-      boot_classpath="$(cygpath --path --$format "$toolchain:$MAIN_JAR")"
-      classpath="$(cygpath --path --$format "$MAIN_JAR:$TEST_JAR")"
+      boot_classpath="$(cygpath --path --$format "$toolchain:$bcpJars")"
+      classpath="$(cygpath --path --$format "$cpJars")"
       cpArgs="-Xbootclasspath/a:$boot_classpath -classpath $classpath"
     else
-      classpath="$(cygpath --path --$format "$toolchain:$MAIN_JAR:$TEST_JAR")"
+      classpath="$(cygpath --path --$format "$toolchain:$cpJars")"
       cpArgs="-classpath $classpath"
     fi
   else
     if [[ -n $bootcp ]]; then
-      cpArgs="-Xbootclasspath/a:$toolchain:$MAIN_JAR -classpath $MAIN_JAR:$TEST_JAR"
+      cpArgs="-Xbootclasspath/a:$toolchain:$bcpJars -classpath $cpJars"
     else
-      cpArgs="-classpath $toolchain:$MAIN_JAR:$TEST_JAR"
+      cpArgs="-classpath $toolchain:$cpJars"
     fi
   fi
   echo ${cpArgs}

interfaces/src/main/java/dotty/tools/dotc/interfaces/CompilerCallback.java

@@ -0,0 +1,30 @@
+package dotty.tools.dotc.interfaces;
+
+import java.io.File;
+
+/** Set of callbacks called in response to events during the compilation process.
+ *
+ *  You should implement this interface if you want to react to one or more of
+ *  these events.
+ *
+ *  @see the method `process` of `dotty.tools.dotc.Driver` for more information.
+ */
+public interface CompilerCallback {
+  /** Called when a class has been generated.
+   *
+   *  @param source         The source file corresponding to this class.
+   *                        Example: ./src/library/scala/collection/Seq.scala
+   *  @param generatedClass The generated classfile for this class.
+   *                        Example: ./scala/collection/Seq$.class
+   *  @param className      The name of this class.
+   *                        Example: scala.collection.Seq$
+   */
+  default void onClassGenerated(File source, File generatedClass, String className) {};
+
+  /** Called when every class for this file has been generated.
+   *
+   *  @param source         The source file.
+   *                        Example: ./src/library/scala/collection/Seq.scala
+   */
+  default void onSourceCompiled(File source) {};
+}

interfaces/src/main/java/dotty/tools/dotc/interfaces/Diagnostic.java

@@ -0,0 +1,26 @@
+package dotty.tools.dotc.interfaces;
+
+import java.util.Optional;
+
+/** A diagnostic is a message emitted during the compilation process.
+ *
+ *  It can either be an error, a warning or an information.
+ *
+ *  User code should not implement this interface, but it may have to
+ *  manipulate objects of this type.
+ */
+public interface Diagnostic {
+  public static final int ERROR = 2;
+  public static final int WARNING = 1;
+  public static final int INFO = 0;
+
+  /** The message to report */
+  String message();
+
+  /** Level of the diagnostic, can be either ERROR, WARNING or INFO */
+  int level();
+
+  /** The position in a source file of the code that caused this diagnostic
+   *  to be emitted. */
+  Optional<SourcePosition> position();
+}

interfaces/src/main/java/dotty/tools/dotc/interfaces/ReporterResult.java

@@ -0,0 +1,18 @@
+package dotty.tools.dotc.interfaces;
+
+/** Summary of the diagnostics emitted by a Reporter.
+ *
+ *  User code should not implement this interface, but it may have to
+ *  manipulate objects of this type.
+ */
+public interface ReporterResult {
+  /** Have we emitted any error ? */
+  boolean hasErrors();
+  /** Number of errors that have been emitted */
+  int errorCount();
+
+  /** Have we emitted any warning ? */
+  boolean hasWarnings();
+  /** Number of warnings that have been emitted */
+  int warningCount();
+}

interfaces/src/main/java/dotty/tools/dotc/interfaces/SimpleReporter.java

@@ -0,0 +1,13 @@
+package dotty.tools.dotc.interfaces;
+
+/** Report errors, warnings and info messages during the compilation process
+ *
+ *  You should implement this interface if you want to handle the diagnostics
+ *  returned by the compiler yourself.
+ *
+ *  @see the method `process` of `dotty.tools.dotc.Driver` for more information.
+ */
+public interface SimpleReporter {
+  /** Report a diagnostic. */
+  void report(Diagnostic diag);
+}

interfaces/src/main/java/dotty/tools/dotc/interfaces/SourceFile.java

@@ -0,0 +1,19 @@
+package dotty.tools.dotc.interfaces;
+
+import java.io.File;
+
+/** A source file that may correspond to a file on disk but may also be virtual.
+ *
+ *  User code should not implement this interface, but it may have to
+ *  manipulate objects of this type.
+ */
+public interface SourceFile {
+  /** The name of this file, note that two files may have the same name. */
+  String name();
+
+  /** The path of this file, this might be a virtual path of an unspecified format. */
+  String path();
+
+  /** The content of this file as seen by the compiler. */
+  char[] content();
+}

interfaces/src/main/java/dotty/tools/dotc/interfaces/SourcePosition.java

@@ -0,0 +1,44 @@
+package dotty.tools.dotc.interfaces;
+
+/** A position in a source file.
+ *
+ *  A position is a range between a start offset and an end offset, as well as a
+ *  point inside this range.
+ *
+ *  As a convenience, we also provide methods that return the line and the column
+ *  corresponding to each offset.
+ *
+ *  User code should not implement this interface, but it may have to
+ *  manipulate objects of this type.
+ */
+public interface SourcePosition {
+  /** Content of the line which contains the point */
+  String lineContent();
+
+  /** Offset to the point */
+  int point();
+  /** Line number of the point, starting at 0 */
+  int line();
+  /** Column number of the point, starting at 0 */
+  int column();
+
+  /** Offset to the range start */
+  int start();
+  /** Line number of the range start, starting at 0 */
+  int startLine();
+  /** Column number of the range start, starting at 0 */
+  int startColumn();
+
+  /** Offset to the range end */
+  int end();
+  /** Line number of the range end, starting at 0 */
+  int endLine();
+  /** Column number of the range end, starting at 0 */
+  int endColumn();
+
+  /** The source file corresponding to this position.
+   *  The values returned by `point()`, `start()` and `end()`
+   *  are indices in the array returned by `source().content()`.
+   */
+  SourceFile source();
+}

project/Build.scala

@@ -35,7 +35,16 @@ object DottyBuild extends Build {
     )
   }
 
+  lazy val `dotty-interfaces` = project.in(file("interfaces")).
+    settings(
+      // Do not append Scala versions to the generated artifacts
+      crossPaths := false,
+      // Do not depend on the Scala library
+      autoScalaLibrary := false
+    )
+
   lazy val dotty = project.in(file(".")).
+    dependsOn(`dotty-interfaces`).
     settings(
       // set sources to src/, tests to test/ and resources to resources/
       scalaSource in Compile := baseDirectory.value / "src",
@@ -105,7 +114,7 @@ object DottyBuild extends Build {
       parallelExecution in Test := false,
 
       // http://grokbase.com/t/gg/simple-build-tool/135ke5y90p/sbt-setting-jvm-boot-paramaters-for-scala
-      javaOptions <++= (managedClasspath in Runtime, packageBin in Compile) map { (attList, bin) =>
+      javaOptions <++= (dependencyClasspath in Runtime, packageBin in Compile) map { (attList, bin) =>
         // put the Scala {library, reflect} in the classpath
         val path = for {
           file <- attList.map(_.data)

src/dotty/tools/dotc/CompilerCallback.scala

@@ -7,6 +7,12 @@ import util.DotClass
 import reporting._
 import scala.util.control.NonFatal
 
+/** Run the Dotty compiler.
+ *
+ *  Extending this class lets you customize many aspect of the compilation
+ *  process, but in most cases you only need to call [[process]] on the
+ *  existing object [[Main]].
+ */
 abstract class Driver extends DotClass {
 
   val prompt = "\ndotc> "
@@ -41,12 +47,35 @@ abstract class Driver extends DotClass {
     (fileNames, ctx)
   }
 
+  /** Entry point to the compiler that can be conveniently used with Java reflection.
+   *
+   *  This entry point can easily be used without depending on the `dotty` package,
+   *  you only need to depend on `dotty-interfaces` and call this method using
+   *  reflection. This allows you to write code that will work against multiple
+   *  versions of dotty without recompilation.
+   *
+   *  The trade-off is that you can only pass a SimpleReporter to this method
+   *  and not a normal Reporter which is more powerful.
+   *
+   *  Usage example: [[https://github.com/lampepfl/dotty/tree/master/test/test/InterfaceEntryPointTest.scala]]
+   *
+   *  @param args       Arguments to pass to the compiler.
+   *  @param simple     Used to log errors, warnings, and info messages.
+   *                    The default reporter is used if this is `null`.
+   *  @param callback   Used to execute custom code during the compilation
+   *                    process. No callbacks will be executed if this is `null`.
+   *  @return
+   */
+  final def process(args: Array[String], simple: interfaces.SimpleReporter,
+    callback: interfaces.CompilerCallback): interfaces.ReporterResult = {
+    val reporter = if (simple == null) null else Reporter.fromSimpleReporter(simple)
+    process(args, reporter, callback)
+  }
 
   /** Principal entry point to the compiler.
-   *  Creates a new compiler instance and run it with arguments `args`.
    *
-   *  The optional arguments of this method all have `null` as their default
-   *  value, this makes it easier to call this method by reflection or from Java.
+   *  Usage example: [[https://github.com/lampepfl/dotty/tree/master/test/test/OtherEntryPointsTest.scala]]
+   *  in method `runCompiler`
    *
    *  @param args       Arguments to pass to the compiler.
    *  @param reporter   Used to log errors, warnings, and info messages.
@@ -57,7 +86,7 @@ abstract class Driver extends DotClass {
    *                    if compilation succeeded.
    */
   final def process(args: Array[String], reporter: Reporter = null,
-    callback: CompilerCallback = null): Reporter = {
+    callback: interfaces.CompilerCallback = null): Reporter = {
     val ctx = initCtx.fresh
     if (reporter != null)
       ctx.setReporter(reporter)
@@ -75,7 +104,7 @@ abstract class Driver extends DotClass {
    *  with sbt.
    */
   final def process(args: Array[String]): Reporter =
-    process(args, null, null)
+    process(args, null: Reporter, null: interfaces.CompilerCallback)
 
   /** Entry point to the compiler using a custom `Context`.
    *
@@ -84,6 +113,9 @@ abstract class Driver extends DotClass {
    *  the other overloads cannot be overriden, instead you
    *  should override this one which they call internally.
    *
+   *  Usage example: [[https://github.com/lampepfl/dotty/tree/master/test/test/OtherEntryPointsTest.scala]]
+   *  in method `runCompilerWithContext`
+   *
    *  @param args       Arguments to pass to the compiler.
    *  @param rootCtx    The root Context to use.
    *  @return           The `Reporter` used. Use `Reporter#hasErrors` to check

src/dotty/tools/dotc/Driver.scala

@@ -2,6 +2,7 @@ package dotty.tools
 package dotc
 package core
 
+import interfaces.CompilerCallback
 import Decorators._
 import Periods._
 import Names._