[plugin] add -P:chiselplugin:INTERNALskipFile

This enables skipping files in the compiler plugin, only needed for
unidoc generation.

4 files changed, 44 insertions, 17 deletions

diff --git a/build.sbt b/build.sbt
index 8a39d958..7cad3e6d 100644
--- a/build.sbt
+++ b/build.sbt
@@ -218,7 +218,13 @@ lazy val chisel = (project in file(".")).
           }
         s"https://github.com/chipsalliance/chisel3/tree/$branch€{FILE_PATH_EXT}#L€{FILE_LINE}"
       }
-    )
+    ) ++
+    // Suppress compiler plugin for source files in core
+    // We don't need this in regular compile because we just don't add the chisel3-plugin to core's scalacOptions
+    // This works around an issue where unidoc uses the exact same arguments for all source files.
+    // This is probably fundamental to how ScalaDoc works so there may be no solution other than this workaround.
+    // See https://github.com/sbt/sbt-unidoc/issues/107
+    (core / Compile / sources).value.map("-P:chiselplugin:INTERNALskipFile:" + _)
   )
 
 // tests elaborating and executing/formally verifying a Chisel circuit with chiseltest
diff --git a/plugin/src/main/scala/chisel3/internal/plugin/BundleComponent.scala b/plugin/src/main/scala/chisel3/internal/plugin/BundleComponent.scala
index c3a001fa..e56380a1 100644
--- a/plugin/src/main/scala/chisel3/internal/plugin/BundleComponent.scala
+++ b/plugin/src/main/scala/chisel3/internal/plugin/BundleComponent.scala
@@ -22,16 +22,8 @@ private[plugin] class BundleComponent(val global: Global, arguments: ChiselPlugi
   private class BundlePhase(prev: Phase) extends StdPhase(prev) {
     override def name: String = phaseName
     def apply(unit: CompilationUnit): Unit = {
-      // This plugin doesn't work on Scala 2.11 nor Scala 3. Rather than complicate the sbt build flow,
-      // instead we just check the version and if its an early Scala version, the plugin does nothing
-      val scalaVersion = scala.util.Properties.versionNumberString.split('.')
-      val scalaVersionOk = scalaVersion(0).toInt == 2 && scalaVersion(1).toInt >= 12
-      if (scalaVersionOk) {
+      if (ChiselPlugin.runComponent(global, arguments)(unit)) {
         unit.body = new MyTypingTransformer(unit).transform(unit.body)
-      } else {
-        val reason = s"invalid Scala version '${scala.util.Properties.versionNumberString}'"
-        // Enable this with scalacOption '-Ylog:chiselbundlephase'
-        global.log(s"Skipping BundleComponent on account of $reason.")
       }
     }
   }
diff --git a/plugin/src/main/scala/chisel3/internal/plugin/ChiselComponent.scala b/plugin/src/main/scala/chisel3/internal/plugin/ChiselComponent.scala
index af22e6a7..cee11df5 100644
--- a/plugin/src/main/scala/chisel3/internal/plugin/ChiselComponent.scala
+++ b/plugin/src/main/scala/chisel3/internal/plugin/ChiselComponent.scala
@@ -11,7 +11,7 @@ import scala.tools.nsc.transform.TypingTransformers
 
 // The component of the chisel plugin. Not sure exactly what the difference is between
 //   a Plugin and a PluginComponent.
-class ChiselComponent(val global: Global) extends PluginComponent with TypingTransformers {
+class ChiselComponent(val global: Global, arguments: ChiselPluginArguments) extends PluginComponent with TypingTransformers {
   import global._
   val runsAfter: List[String] = List[String]("typer")
   val phaseName: String = "chiselcomponent"
@@ -19,10 +19,7 @@ class ChiselComponent(val global: Global) extends PluginComponent with TypingTra
   class ChiselComponentPhase(prev: Phase) extends StdPhase(prev) {
     override def name: String = phaseName
     def apply(unit: CompilationUnit): Unit = {
-      // This plugin doesn't work on Scala 2.11 nor Scala 3. Rather than complicate the sbt build flow,
-      // instead we just check the version and if its an early Scala version, the plugin does nothing
-      val scalaVersion = scala.util.Properties.versionNumberString.split('.')
-      if (scalaVersion(0).toInt == 2 && scalaVersion(1).toInt >= 12) {
+      if (ChiselPlugin.runComponent(global, arguments)(unit)) {
         unit.body = new MyTypingTransformer(unit).transform(unit.body)
       }
     }
diff --git a/plugin/src/main/scala/chisel3/internal/plugin/ChiselPlugin.scala b/plugin/src/main/scala/chisel3/internal/plugin/ChiselPlugin.scala
index 2282059f..eadb76b6 100644
--- a/plugin/src/main/scala/chisel3/internal/plugin/ChiselPlugin.scala
+++ b/plugin/src/main/scala/chisel3/internal/plugin/ChiselPlugin.scala
@@ -6,14 +6,40 @@ import scala.tools.nsc
 import nsc.Global
 import nsc.plugins.{Plugin, PluginComponent}
 import scala.reflect.internal.util.NoPosition
+import scala.collection.mutable
 
-private[plugin] case class ChiselPluginArguments() {
+private[plugin] case class ChiselPluginArguments(val skipFiles: mutable.HashSet[String] = mutable.HashSet.empty) {
   def useBundlePluginOpt = "useBundlePlugin"
   def useBundlePluginFullOpt = s"-P:${ChiselPlugin.name}:$useBundlePluginOpt"
+
+  // Annoying because this shouldn't be used by users
+  def skipFilePluginOpt = "INTERNALskipFile:"
+  def skipFilePluginFullOpt = s"-P:${ChiselPlugin.name}:$skipFilePluginOpt"
 }
 
 object ChiselPlugin {
   val name = "chiselplugin"
+
+  // Also logs why the compoennt was not run
+  private[plugin] def runComponent(global: Global, arguments: ChiselPluginArguments)(unit: global.CompilationUnit): Boolean = {
+    // This plugin doesn't work on Scala 2.11 nor Scala 3. Rather than complicate the sbt build flow,
+    // instead we just check the version and if its an early Scala version, the plugin does nothing
+    val scalaVersion = scala.util.Properties.versionNumberString.split('.')
+    val scalaVersionOk = scalaVersion(0).toInt == 2 && scalaVersion(1).toInt >= 12
+    val skipFile = arguments.skipFiles(unit.source.file.path)
+    if (scalaVersionOk && !skipFile) {
+      true
+    } else {
+      val reason = if (!scalaVersionOk) {
+        s"invalid Scala version '${scala.util.Properties.versionNumberString}'"
+      } else {
+        s"file skipped via '${arguments.skipFilePluginFullOpt}'"
+      }
+      // Enable this with scalacOption '-Ylog:chiselbundlephase'
+      global.log(s"Skipping BundleComponent on account of $reason.")
+      false
+    }
+  }
 }
 
 // The plugin to be run by the Scala compiler during compilation of Chisel code
@@ -22,7 +48,7 @@ class ChiselPlugin(val global: Global) extends Plugin {
   val description = "Plugin for Chisel 3 Hardware Description Language"
   private val arguments = ChiselPluginArguments()
   val components: List[PluginComponent] = List[PluginComponent](
-    new ChiselComponent(global),
+    new ChiselComponent(global, arguments),
     new BundleComponent(global, arguments)
   )
 
@@ -31,6 +57,12 @@ class ChiselPlugin(val global: Global) extends Plugin {
       if (option == arguments.useBundlePluginOpt) {
         val msg = s"'${arguments.useBundlePluginFullOpt}' is now default behavior, you can stop using the scalacOption."
         global.reporter.warning(NoPosition, msg)
+      } else if (option.startsWith(arguments.skipFilePluginOpt)) {
+        val filename = option.stripPrefix(arguments.skipFilePluginOpt)
+        arguments.skipFiles += filename
+        // Be annoying and warn because users are not supposed to use this
+        val msg = s"Option -P:${ChiselPlugin.name}:$option should only be used for internal chisel3 compiler purposes!"
+        global.reporter.warning(NoPosition, msg)
       } else {
         error(s"Option not understood: '$option'")
       }