Allow controlling linker re-use on Scala.js (#456)

scalameta · Feb 6, 2021 · 977d6c8 · 977d6c8
1 parent ccab290
commit 977d6c8
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 6 deletions.
diff --git a/docs/js.md b/docs/js.md
@@ -395,3 +395,18 @@ files:
   the markdown output as a `<script src="...">`.
 - `*-loader.js`: same as `*-library.js` but it comes after `*-library.js`.
 - `*.js.map`: optional source maps.
+
+### Batch mode linking
+
+By default, mdoc will re-use the Scala.js linker, exercising its ability to work
+incrementally. This can speed up linking and optimization dramatically.
+
+If incremental linking is causing issues in your project, use can use `js-batch-mode`
+site variable to enable batch mode (which will discard intermediate linker state 
+after processing each file):
+
+```scala
+mdocVariables := Map(
+  "js-batch-mode" -> "true"
+)
+```
diff --git a/mdoc-js/src/main/scala/mdoc/modifiers/JsConfig.scala b/mdoc-js/src/main/scala/mdoc/modifiers/JsConfig.scala
@@ -19,7 +19,8 @@ case class JsConfig(
     outPrefix: Option[String] = None,
     fullOpt: Boolean = true,
     htmlPrefix: String = "",
-    relativeLinkPrefix: String = ""
+    relativeLinkPrefix: String = "",
+    batchMode: Boolean = false
 ) {
   def isCommonJS: Boolean = moduleKind == ModuleKind.CommonJSModule
   def libraryScripts(
@@ -90,7 +91,8 @@ object JsConfig {
               !ctx.settings.watch
           }
       },
-      relativeLinkPrefix = ctx.site.getOrElse("js-relative-link-prefix", base.relativeLinkPrefix)
+      relativeLinkPrefix = ctx.site.getOrElse("js-relative-link-prefix", base.relativeLinkPrefix),
+      batchMode = ctx.site.getOrElse("js-batch-mode", "false").toBoolean
     )
   }
 }
diff --git a/mdoc-js/src/main/scala/mdoc/modifiers/JsModifier.scala b/mdoc-js/src/main/scala/mdoc/modifiers/JsModifier.scala
@@ -29,6 +29,7 @@ import org.scalajs.linker.interface.LinkerOutput
 import org.scalajs.linker.MemOutputFile
 import java.util.concurrent.Executor
 import scala.concurrent.ExecutionContext.Implicits.global
+import org.scalajs.linker.interface.ClearableLinker
 
 class JsModifier extends mdoc.PreModifier {
   override val name = "js"
@@ -37,7 +38,7 @@ class JsModifier extends mdoc.PreModifier {
   val target = new VirtualDirectory("(memory)", None)
   var maybeCompiler: Option[MarkdownCompiler] = None
   var config = JsConfig()
-  var linker: Linker = newLinker()
+  var linker: ClearableLinker = newLinker()
   var virtualIrFiles: Seq[IRFile] = Nil
   var classpathHash: Int = 0
   var reporter: mdoc.Reporter = new ConsoleReporter(System.out)
@@ -67,7 +68,7 @@ class JsModifier extends mdoc.PreModifier {
     result
   }
 
-  def newLinker(): Linker = {
+  def newLinker(): ClearableLinker = {
     val semantics: Semantics =
       if (config.fullOpt) Semantics.Defaults.optimized
       else Semantics.Defaults
@@ -76,9 +77,10 @@ class JsModifier extends mdoc.PreModifier {
       .withSemantics(semantics)
       .withSourceMap(false)
       .withModuleKind(config.moduleKind)
+      .withBatchMode(config.batchMode)
       .withClosureCompilerIfAvailable(config.fullOpt)
 
-    StandardImpl.linker(conf)
+    StandardImpl.clearableLinker(conf)
   }
 
   override def onLoad(ctx: OnLoadContext): Unit = {
@@ -165,7 +167,8 @@ class JsModifier extends mdoc.PreModifier {
     } else {
       val output = MemOutputFile.apply()
 
-      val linking = linker.link(virtualIrFiles ++ sjsir, Nil, LinkerOutput.apply(output), sjsLogger)
+      val linking =
+        linker.link(virtualIrFiles ++ sjsir, Nil, LinkerOutput.apply(output), sjsLogger)
       Await.result(linking, Duration.Inf)
 
       ctx.settings.toInputFile(ctx.inputFile) match {