Merge pull request scala-js#3790 from gzm0/linker-interface

Split linker interface into separate artifact

Author: gzm0

Jenkinsfile

@@ -308,20 +308,22 @@ def Tasks = [
         'set scalaJSStage in testSuite := FastOptStage' \
         ++$scala testSuite/bootstrap:test &&
     sbt ++$scala irJS/mimaReportBinaryIssues \
-        loggingJS/mimaReportBinaryIssues linkerJS/mimaReportBinaryIssues
+        loggingJS/mimaReportBinaryIssues \
+        linkerInterfaceJS/mimaReportBinaryIssues linkerJS/mimaReportBinaryIssues
   ''',
 
   "tools": '''
     setJavaVersion $java
     npm install &&
-    sbt ++$scala ir/test logging/compile linker/compile \
-        jsEnvs/test nodeJSEnv/test testAdapter/test \
-        ir/mimaReportBinaryIssues \
-        logging/mimaReportBinaryIssues linker/mimaReportBinaryIssues \
+    sbt ++$scala ir/test logging/compile linkerInterface/compile \
+        linker/compile jsEnvs/test nodeJSEnv/test testAdapter/test \
+        ir/mimaReportBinaryIssues logging/mimaReportBinaryIssues \
+        linkerInterface/mimaReportBinaryIssues linker/mimaReportBinaryIssues \
         jsEnvs/mimaReportBinaryIssues jsEnvsTestKit/mimaReportBinaryIssues \
         nodeJSEnv/mimaReportBinaryIssues \
         testAdapter/mimaReportBinaryIssues &&
     sbt ++$scala ir/compile:doc logging/compile:doc \
+        linkerInterface/compile:doc \
         linker/compile:doc jsEnvs/compile:doc \
         jsEnvsTestKit/compile:doc nodeJSEnv/compile:doc \
         testAdapter/compile:doc
@@ -330,11 +332,11 @@ def Tasks = [
   "tools-sbtplugin": '''
     setJavaVersion $java
     npm install &&
-    sbt ++$scala ir/test logging/compile linker/compile \
-        jsEnvs/test nodeJSEnv/test testAdapter/test \
+    sbt ++$scala ir/test logging/compile linkerInterface/compile \
+        linker/compile jsEnvs/test nodeJSEnv/test testAdapter/test \
         sbtPlugin/package \
-        ir/mimaReportBinaryIssues \
-        logging/mimaReportBinaryIssues linker/mimaReportBinaryIssues \
+        ir/mimaReportBinaryIssues logging/mimaReportBinaryIssues \
+        linkerInterface/mimaReportBinaryIssues linker/mimaReportBinaryIssues \
         jsEnvs/mimaReportBinaryIssues jsEnvsTestKit/mimaReportBinaryIssues \
         nodeJSEnv/mimaReportBinaryIssues \
         testAdapter/mimaReportBinaryIssues \
@@ -343,6 +345,8 @@ def Tasks = [
         ir/scalastyle compiler/scalastyle \
         compiler/test:scalastyle \
         logging/scalastyle logging/test:scalastyle \
+        linkerInterface/scalastyle \
+        linkerInterface/scalastyle \
         linker/scalastyle linker/test:scalastyle \
         jsEnvs/scalastyle jsEnvsTestKit/scalastyle nodeJSEnv/scalastyle \
         jsEnvs/test:scalastyle nodeJSEnv/test:scalastyle testAdapter/scalastyle \
@@ -356,6 +360,7 @@ def Tasks = [
         jUnitTestOutputsJVM/scalastyle jUnitTestOutputsJVM/test:scalastyle \
         jUnitTestOutputsJS/scalastyle jUnitTestOutputsJS/test:scalastyle &&
     sbt ++$scala ir/compile:doc logging/compile:doc \
+        linkerInterface/compile:doc \
         linker/compile:doc jsEnvs/compile:doc \
         jsEnvsTestKit/compile:doc nodeJSEnv/compile:doc \
         testAdapter/compile:doc \
@@ -378,6 +383,7 @@ def Tasks = [
                   jUnitPlugin/publishLocal jUnitRuntime/publishLocal &&
     sbt ++$toolsscala \
         ir/publishLocal logging/publishLocal \
+        linkerInterface/publishLocal \
         linker/publishLocal jsEnvs/publishLocal \
         nodeJSEnv/publishLocal testAdapter/publishLocal \
         sbtPlugin/publishLocal &&

build.sbt

@@ -6,6 +6,8 @@ val irJS = Build.irProjectJS
 val compiler = Build.compiler
 val logging = Build.logging
 val loggingJS = Build.loggingJS
+val linkerInterface = Build.linkerInterface
+val linkerInterfaceJS = Build.linkerInterfaceJS
 val linker = Build.linker
 val linkerJS = Build.linkerJS
 val jsEnvs = Build.jsEnvs

linker/js/src/main/scala/org/scalajs/linker/StandardLinkerPlatformExtensions.scala renamed to linker-interface/js/src/main/scala/org/scalajs/linker/interface/StandardConfigPlatformExtensions.scala

@@ -10,12 +10,11 @@
  * additional information regarding copyright ownership.
  */
 
-package org.scalajs.linker
+package org.scalajs.linker.interface
 
-object StandardLinkerPlatformExtensions {
-  import StandardLinker.Config
+object StandardConfigPlatformExtensions {
 
-  final class ConfigExt private[linker] (private val self: Config)
+  final class ConfigExt private[linker] (private val self: StandardConfig)
       extends AnyVal {
 
     /** Whether to actually use the Google Closure Compiler pass.

linker/jvm/src/main/scala/org/scalajs/linker/StandardLinkerPlatformExtensions.scala renamed to linker-interface/jvm/src/main/scala/org/scalajs/linker/interface/StandardConfigPlatformExtensions.scala

@@ -10,20 +10,17 @@
  * additional information regarding copyright ownership.
  */
 
-package org.scalajs.linker
+package org.scalajs.linker.interface
 
-object StandardLinkerPlatformExtensions {
-  import StandardLinker.Config
+object StandardConfigPlatformExtensions {
 
-  final class ConfigExt private[linker] (val __private_self: Config)
+  final class ConfigExt private[linker] (private val self: StandardConfig)
       extends AnyVal {
 
-    @inline private def self: Config = __private_self
-
     /** Whether to actually use the Google Closure Compiler pass. */
     def closureCompiler: Boolean = self.closureCompilerIfAvailable
 
-    def withClosureCompiler(closureCompiler: Boolean): Config =
+    def withClosureCompiler(closureCompiler: Boolean): StandardConfig =
       self.withClosureCompilerIfAvailable(closureCompiler)
   }
 }

linker/shared/src/main/scala/org/scalajs/linker/CheckedBehavior.scala renamed to linker-interface/shared/src/main/scala/org/scalajs/linker/interface/CheckedBehavior.scala

@@ -10,7 +10,7 @@
  * additional information regarding copyright ownership.
  */
 
-package org.scalajs.linker
+package org.scalajs.linker.interface
 
 sealed abstract class CheckedBehavior {
   import CheckedBehavior._

linker-interface/shared/src/main/scala/org/scalajs/linker/interface/ClearableLinker.scala

@@ -0,0 +1,37 @@
+/*
+ * Scala.js (https://www.scala-js.org/)
+ *
+ * Copyright EPFL.
+ *
+ * Licensed under Apache License 2.0
+ * (https://www.apache.org/licenses/LICENSE-2.0).
+ *
+ * See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.
+ */
+
+package org.scalajs.linker.interface
+
+/** A box around a [[Linker]] to support clearing.
+ *
+ *  Calling `clear()` completely resets the state of this `ClearableLinker`, so
+ *  that it can be used again without being affected by previous calls to
+ *  `link`, even of those would have corrupted the internal state.
+ *
+ *  In addition to the contract of [[Linker]], if [[Linker.link]] throws an
+ *  exception, the `ClearableLinker` is automatically `clear()`'ed.
+ *
+ *  Implementations are allowed to automatically `clear()` in other cases, but
+ *  never while a linking is in progress.
+ *
+ *  Unless otherwise specified, instances of this trait are not thread-safe.
+ */
+trait ClearableLinker extends Linker {
+  /** Completely resets the state of this `ClearableLinker`.
+   *
+   *  After calling this method, this `ClearableLinker`, it can be used again
+   *  without being affected by previous calls to `link`, even of those would
+   *  have corrupted the internal state.
+   */
+  def clear(): Unit
+}

linker/shared/src/main/scala/org/scalajs/linker/ESFeatures.scala renamed to linker-interface/shared/src/main/scala/org/scalajs/linker/interface/ESFeatures.scala

@@ -10,7 +10,7 @@
  * additional information regarding copyright ownership.
  */
 
-package org.scalajs.linker
+package org.scalajs.linker.interface
 
 /** ECMAScript features to use when linking to JavaScript.
  *

linker/shared/src/main/scala/org/scalajs/linker/IRContainer.scala renamed to linker-interface/shared/src/main/scala/org/scalajs/linker/interface/IRContainer.scala

@@ -10,17 +10,17 @@
  * additional information regarding copyright ownership.
  */
 
-package org.scalajs.linker
+package org.scalajs.linker.interface
 
 import scala.concurrent._
 
-import org.scalajs.linker.standard._
+import org.scalajs.linker.interface.unstable.{IRContainerImpl, IRFileImpl}
 
-abstract class IRContainer private[linker] () {
-  private[linker] def impl: IRContainerImpl
+abstract class IRContainer private[interface] () {
+  private[interface] def impl: IRContainerImpl
 }
 
-object IRContainer extends IRContainerPlatformExtensions {
+object IRContainer {
   def fromIRFile(irFile: IRFile): IRContainer = {
     val f = IRFileImpl.fromIRFile(irFile)
     new IRContainerImpl(f.path, f.version) {

linker/shared/src/main/scala/org/scalajs/linker/IRFile.scala renamed to linker-interface/shared/src/main/scala/org/scalajs/linker/interface/IRFile.scala

@@ -10,12 +10,10 @@
  * additional information regarding copyright ownership.
  */
 
-package org.scalajs.linker
+package org.scalajs.linker.interface
 
-import org.scalajs.linker.standard.IRFileImpl
+import org.scalajs.linker.interface.unstable.IRFileImpl
 
-abstract class IRFile private[linker] () {
-  private[linker] def impl: IRFileImpl
+abstract class IRFile private[interface] () {
+  private[interface] def impl: IRFileImpl
 }
-
-object IRFile extends IRFilePlatformExtensions

linker/shared/src/main/scala/org/scalajs/linker/IRFileCache.scala renamed to linker-interface/shared/src/main/scala/org/scalajs/linker/interface/IRFileCache.scala

@@ -10,19 +10,17 @@
  * additional information regarding copyright ownership.
  */
 
-package org.scalajs.linker
+package org.scalajs.linker.interface
 
 import scala.concurrent._
 
-import org.scalajs.linker.standard.StandardIRFileCache
-
 /** Centralized Scala.js IR cache.
  *
  *  Caches all Scala.js IR used in a given JVM. It supports creating of multiple
  *  sub-caches ([[IRFileCache.Cache]]) that track individual file sets.
  *  The global cache is fully thread-safe. However, the sub-caches are not.
  */
-abstract class IRFileCache private[linker] () {
+abstract class IRFileCache private[interface] () {
   /** Create a new sub-cache.
    *
    *  Users should call [[IRFileCache.Cache.free]] once they are done to allow
@@ -38,10 +36,8 @@ abstract class IRFileCache private[linker] () {
 }
 
 object IRFileCache {
-  def apply(): IRFileCache = new StandardIRFileCache()
-
   /** A cache to use for individual runs. Not threadsafe */
-  abstract class Cache private[linker] () {
+  abstract class Cache private[interface] () {
     /** Extract and cache IR.
      *
      *  The returned value is valid until the next invocation of [[cached]] or
@@ -64,7 +60,7 @@ object IRFileCache {
   }
 
   /** Statistics about an individual run. */
-  abstract class Stats private[linker] {
+  abstract class Stats private[interface] {
     /** Descriptive line to display in logs */
     def logLine: String
   }

linker/shared/src/main/scala/org/scalajs/linker/Linker.scala renamed to linker-interface/shared/src/main/scala/org/scalajs/linker/interface/Linker.scala

@@ -10,7 +10,7 @@
  * additional information regarding copyright ownership.
  */
 
-package org.scalajs.linker
+package org.scalajs.linker.interface
 
 import scala.concurrent._
 
@@ -22,7 +22,7 @@ import org.scalajs.logging.Logger
  *  module initializers, link them together, and write the output to a writable
  *  .js file.
  */
-abstract class Linker private[linker] () {
+abstract class Linker private[interface] () {
   def link(irFiles: Seq[IRFile],
       moduleInitializers: Seq[ModuleInitializer],
       output: LinkerOutput, logger: Logger)(

linker-interface/shared/src/main/scala/org/scalajs/linker/interface/LinkerOutput.scala

@@ -0,0 +1,76 @@
+/*
+ * Scala.js (https://www.scala-js.org/)
+ *
+ * Copyright EPFL.
+ *
+ * Licensed under Apache License 2.0
+ * (https://www.apache.org/licenses/LICENSE-2.0).
+ *
+ * See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.
+ */
+
+package org.scalajs.linker.interface
+
+import scala.concurrent._
+
+import java.io.ByteArrayOutputStream
+import java.nio.ByteBuffer
+
+import java.net.URI
+
+import org.scalajs.linker.interface.unstable.OutputFileImpl
+
+/** Output specification for a linker run.
+ *
+ *  @param jsFile The JavaScript file a [[Linker]] writes to.
+ *
+ *  @param sourceMap The sourceMap file the linker writes to. A [[Linker]] may
+ *      ignore this file. N.b. the standard linker will ignore it if
+ *      [[StandardConfig.sourceMap]] is false. Further, a [[Linker]] must not
+ *      fail if this is not set, but rather not write a source map (even if it
+ *      is configured to write a source map).
+ *
+ *  @param sourceMapURI URI to reach the source map from the JavaScript file.
+ *      This is typically a relative URI but is not required. A [[Linker]]
+ *      should ignore this, if [[sourceMap]] is not set or source map production
+ *      is disabled.
+ *
+ *  @param jsFileURI URI to reach the JavaScript file from the source map. This
+ *      is typically a relative URI but is not required. A [[Linker]] may use
+ *      this even if [[sourceMap]] is not set, but it is typically meaningless.
+ */
+final class LinkerOutput private (
+    val jsFile: LinkerOutput.File,
+    val sourceMap: Option[LinkerOutput.File],
+    val sourceMapURI: Option[URI],
+    val jsFileURI: Option[URI]
+) {
+  private def this(jsFile: LinkerOutput.File) =
+    this(jsFile, None, None, None)
+
+  def withSourceMap(sourceMap: LinkerOutput.File): LinkerOutput =
+    copy(sourceMap = Some(sourceMap))
+
+  def withSourceMapURI(sourceMapURI: URI): LinkerOutput =
+    copy(sourceMapURI = Some(sourceMapURI))
+
+  def withJSFileURI(jsFileURI: URI): LinkerOutput =
+    copy(jsFileURI = Some(jsFileURI))
+
+  private def copy(
+      jsFile: LinkerOutput.File = jsFile,
+      sourceMap: Option[LinkerOutput.File] = sourceMap,
+      sourceMapURI: Option[URI] = sourceMapURI,
+      jsFileURI: Option[URI] = jsFileURI): LinkerOutput = {
+    new LinkerOutput(jsFile, sourceMap, sourceMapURI, jsFileURI)
+  }
+}
+
+object LinkerOutput {
+  def apply(jsFile: LinkerOutput.File): LinkerOutput = new LinkerOutput(jsFile)
+
+  abstract class File private[interface] () {
+    private[interface] def impl: OutputFileImpl
+  }
+}

linker/shared/src/main/scala/org/scalajs/linker/LinkingException.scala renamed to linker-interface/shared/src/main/scala/org/scalajs/linker/interface/LinkingException.scala

@@ -10,7 +10,7 @@
  * additional information regarding copyright ownership.
  */
 
-package org.scalajs.linker
+package org.scalajs.linker.interface
 
 /** Thrown by the linker when linking cannot be performed. */
 class LinkingException(message: String, cause: Throwable)