Merge pull request #2314 from chipsalliance/fix-unidoc

Fix unidoc

5 files changed, 51 insertions, 24 deletions

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index ce18fab0..71be8c09 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -45,7 +45,7 @@ jobs:
         uses: coursier/cache-action@v5
       - name: Documentation (Scala 2.12 only)
         if: startsWith(matrix.scala, '2.12')
-        run: sbt ++${{ matrix.scala }} docs/mdoc
+        run: sbt ++${{ matrix.scala }} docs/mdoc unidoc
       - name: Test
         run: sbt ++${{ matrix.scala }} test
       - name: Binary compatibility
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 67d744fc..e56380a1 100644
--- a/plugin/src/main/scala/chisel3/internal/plugin/BundleComponent.scala
+++ b/plugin/src/main/scala/chisel3/internal/plugin/BundleComponent.scala
@@ -22,20 +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 && arguments.useBundlePlugin) {
+      if (ChiselPlugin.runComponent(global, arguments)(unit)) {
         unit.body = new MyTypingTransformer(unit).transform(unit.body)
-      } else {
-        val reason = if (!scalaVersionOk) {
-          s"invalid Scala version '${scala.util.Properties.versionNumberString}'"
-        } else {
-          s"not enabled via '${arguments.useBundlePluginFullOpt}'"
-        }
-        // 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 23082329..eadb76b6 100644
--- a/plugin/src/main/scala/chisel3/internal/plugin/ChiselPlugin.scala
+++ b/plugin/src/main/scala/chisel3/internal/plugin/ChiselPlugin.scala
@@ -6,19 +6,49 @@ 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(var useBundlePlugin: Boolean = true) {
+private[plugin] case class ChiselPluginArguments(val skipFiles: mutable.HashSet[String] = mutable.HashSet.empty) {
   def useBundlePluginOpt = "useBundlePlugin"
-  def useBundlePluginFullOpt = s"-P:chiselplugin:$useBundlePluginOpt"
+  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
 class ChiselPlugin(val global: Global) extends Plugin {
-  val name = "chiselplugin"
+  val name = ChiselPlugin.name
   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)
   )
 
@@ -27,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'")
       }