Deprecate support for Scala 2.11 (#1842)

* Deprecate support for Scala 2.11

Printed as warning in transform, can be suppressed via CLI

* Place version deprecation message in object

Refactor CheckScalaVersion to place the deprecation message inside the
companion object. This lets the object be reused in other places, like
in tests.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Check Scala 2.11 deprecation messages in tests

Fix FirrtlMainSpec to check that the Scala 2.11 deprecation message
added by the CheckScalaVersion transform shows up on stdout, but only
if tests are running under 2.11.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

Co-authored-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

7 files changed, 89 insertions, 3 deletions

diff --git a/src/main/scala/firrtl/passes/CheckChirrtl.scala b/src/main/scala/firrtl/passes/CheckChirrtl.scala
index 579dba30..9903f445 100644
--- a/src/main/scala/firrtl/passes/CheckChirrtl.scala
+++ b/src/main/scala/firrtl/passes/CheckChirrtl.scala
@@ -5,9 +5,12 @@ package firrtl.passes
 import firrtl.Transform
 import firrtl.ir._
 import firrtl.options.Dependency
+import firrtl.stage.transforms.CheckScalaVersion
 
 object CheckChirrtl extends Pass with CheckHighFormLike {
 
+  override def prerequisites = Dependency[CheckScalaVersion] :: Nil
+
   override val optionalPrerequisiteOf = firrtl.stage.Forms.ChirrtlForm ++
     Seq( Dependency(CInferTypes),
          Dependency(CInferMDir),
diff --git a/src/main/scala/firrtl/stage/FirrtlAnnotations.scala b/src/main/scala/firrtl/stage/FirrtlAnnotations.scala
index 91c5609b..d587fd8c 100644
--- a/src/main/scala/firrtl/stage/FirrtlAnnotations.scala
+++ b/src/main/scala/firrtl/stage/FirrtlAnnotations.scala
@@ -222,3 +222,18 @@ case class FirrtlCircuitAnnotation(circuit: Circuit) extends NoTargetAnnotation
   override lazy val hashCode: Int = circuit.hashCode
 
 }
+
+/** Suppresses warning about Scala 2.11 deprecation
+  *
+  *  - set with `--Wno-scala-version-warning`
+  */
+case object SuppressScalaVersionWarning extends NoTargetAnnotation with FirrtlOption with HasShellOptions {
+  def longOption: String = "Wno-scala-version-warning"
+  val options = Seq(
+    new ShellOption[Unit](
+      longOption      = longOption,
+      toAnnotationSeq = { _ => Seq(this) },
+      helpText        = "Suppress Scala 2.11 deprecation warning (ignored in Scala 2.12+)"
+    )
+  )
+}
diff --git a/src/main/scala/firrtl/stage/FirrtlCli.scala b/src/main/scala/firrtl/stage/FirrtlCli.scala
index be1100c3..39b89bea 100644
--- a/src/main/scala/firrtl/stage/FirrtlCli.scala
+++ b/src/main/scala/firrtl/stage/FirrtlCli.scala
@@ -19,7 +19,8 @@ trait FirrtlCli { this: Shell =>
        RunFirrtlTransformAnnotation,
        firrtl.EmitCircuitAnnotation,
        firrtl.EmitAllModulesAnnotation,
-       NoCircuitDedupAnnotation )
+       NoCircuitDedupAnnotation,
+       SuppressScalaVersionWarning)
     .map(_.addOptions(parser))
 
   phases.DriverCompatibility.TopNameAnnotation.addOptions(parser)
diff --git a/src/main/scala/firrtl/stage/package.scala b/src/main/scala/firrtl/stage/package.scala
index e9cf3fb4..123c763a 100644
--- a/src/main/scala/firrtl/stage/package.scala
+++ b/src/main/scala/firrtl/stage/package.scala
@@ -33,6 +33,7 @@ package object stage {
           case InfoModeAnnotation(i)             => c.copy(infoModeName = i)
           case FirrtlCircuitAnnotation(cir)      => c.copy(firrtlCircuit = Some(cir))
           case a : CompilerAnnotation => logger.warn(s"Use of CompilerAnnotation is deprecated. Ignoring $a") ; c
+          case SuppressScalaVersionWarning       => c
         }
       }
   }
diff --git a/src/main/scala/firrtl/stage/transforms/CheckScalaVersion.scala b/src/main/scala/firrtl/stage/transforms/CheckScalaVersion.scala
new file mode 100644
index 00000000..a7127dba
--- /dev/null
+++ b/src/main/scala/firrtl/stage/transforms/CheckScalaVersion.scala
@@ -0,0 +1,37 @@
+// See LICENSE for license details.
+
+package firrtl.stage.transforms
+
+import firrtl.{BuildInfo, CircuitState, DependencyAPIMigration, Transform}
+import firrtl.stage.SuppressScalaVersionWarning
+import firrtl.options.StageUtils.dramaticWarning
+
+object CheckScalaVersion {
+  def migrationDocumentLink: String = "https://www.chisel-lang.org/chisel3/upgrading-from-scala-2-11.html"
+
+  private def getScalaMajorVersion: Int = {
+    val "2" :: major :: _ :: Nil = BuildInfo.scalaVersion.split("\\.").toList
+    major.toInt
+  }
+
+  final def deprecationMessage(version: String, option: String) =
+    s"""|FIRRTL support for Scala $version is deprecated, please upgrade to Scala 2.12.
+        |  Migration guide: $migrationDocumentLink
+        |  Suppress warning with '$option'""".stripMargin
+
+}
+
+class CheckScalaVersion extends Transform with DependencyAPIMigration {
+  import CheckScalaVersion._
+
+  override def invalidates(a: Transform) = false
+
+  def execute(state: CircuitState): CircuitState = {
+    def suppress = state.annotations.contains(SuppressScalaVersionWarning)
+    if (getScalaMajorVersion == 11 && !suppress) {
+      val option = s"--${SuppressScalaVersionWarning.longOption}"
+      dramaticWarning(deprecationMessage("2.11", option))
+    }
+    state
+  }
+}
diff --git a/src/test/scala/firrtlTests/LoweringCompilersSpec.scala b/src/test/scala/firrtlTests/LoweringCompilersSpec.scala
index e1de7e34..f0f2042e 100644
--- a/src/test/scala/firrtlTests/LoweringCompilersSpec.scala
+++ b/src/test/scala/firrtlTests/LoweringCompilersSpec.scala
@@ -36,6 +36,7 @@ class LoweringCompilersSpec extends AnyFlatSpec with Matchers {
 
   def legacyTransforms(a: CoreTransform): Seq[Transform] = a match {
     case _: ChirrtlToHighFirrtl => Seq(
+      new firrtl.stage.transforms.CheckScalaVersion,
       firrtl.passes.CheckChirrtl,
       firrtl.passes.CInferTypes,
       firrtl.passes.CInferMDir,
diff --git a/src/test/scala/firrtlTests/stage/FirrtlMainSpec.scala b/src/test/scala/firrtlTests/stage/FirrtlMainSpec.scala
index 1b4a1375..7d57f7ed 100644
--- a/src/test/scala/firrtlTests/stage/FirrtlMainSpec.scala
+++ b/src/test/scala/firrtlTests/stage/FirrtlMainSpec.scala
@@ -8,9 +8,10 @@ import org.scalatest.matchers.should.Matchers
 
 import java.io.{File, PrintWriter}
 
-import firrtl.FileUtils
+import firrtl.{BuildInfo, FileUtils}
 
-import firrtl.stage.FirrtlMain
+import firrtl.stage.{FirrtlMain, SuppressScalaVersionWarning}
+import firrtl.stage.transforms.CheckScalaVersion
 import firrtl.util.BackendCompilationUtilities
 import org.scalatest.featurespec.AnyFeatureSpec
 import org.scalatest.matchers.should.Matchers
@@ -159,6 +160,16 @@ class FirrtlMainSpec extends AnyFeatureSpec with GivenWhenThen with Matchers wit
          |""".stripMargin
   }
 
+  /** This returns a string containing the default standard out string based on the Scala version. E.g., if there are
+    * version-specific deprecation warnings, those are available here and can be passed to tests that should have them.
+    */
+  val defaultStdOut: Option[String] = BuildInfo.scalaVersion.split("\\.").toList match {
+    case "2" :: v :: _ :: Nil if v.toInt <= 11 =>
+      Some(CheckScalaVersion.deprecationMessage("2.11", s"--${SuppressScalaVersionWarning.longOption}"))
+    case x =>
+      None
+  }
+
   info("As a FIRRTL command line user")
   info("I want to compile some FIRRTL")
   Feature("FirrtlMain command line interface") {
@@ -192,32 +203,43 @@ class FirrtlMainSpec extends AnyFeatureSpec with GivenWhenThen with Matchers wit
       FirrtlMainTest(args   = Array("-X", "none", "-E", "chirrtl"),
                       files  = Seq("Top.fir")),
       FirrtlMainTest(args   = Array("-X", "high", "-E", "high"),
+                      stdout = defaultStdOut,
                       files  = Seq("Top.hi.fir")),
       FirrtlMainTest(args   = Array("-X", "middle", "-E", "middle", "-foaf", "Top"),
+                      stdout = defaultStdOut,
                       files  = Seq("Top.mid.fir", "Top.anno.json")),
       FirrtlMainTest(args   = Array("-X", "low", "-E", "low", "-foaf", "annotations.anno.json"),
+                      stdout = defaultStdOut,
                       files  = Seq("Top.lo.fir", "annotations.anno.json")),
       FirrtlMainTest(args   = Array("-X", "verilog", "-E", "verilog", "-foaf", "foo.anno"),
+                      stdout = defaultStdOut,
                       files  = Seq("Top.v", "foo.anno.anno.json")),
       FirrtlMainTest(args   = Array("-X", "sverilog", "-E", "sverilog", "-foaf", "foo.json"),
+                      stdout = defaultStdOut,
                       files  = Seq("Top.sv", "foo.json.anno.json")),
 
       /* Test all one file per module emitters */
       FirrtlMainTest(args   = Array("-X", "none", "-e", "chirrtl"),
                       files  = Seq("Top.fir", "Child.fir")),
       FirrtlMainTest(args   = Array("-X", "high", "-e", "high"),
+                      stdout = defaultStdOut,
                       files  = Seq("Top.hi.fir", "Child.hi.fir")),
       FirrtlMainTest(args   = Array("-X", "middle", "-e", "middle"),
+                      stdout = defaultStdOut,
                       files  = Seq("Top.mid.fir", "Child.mid.fir")),
       FirrtlMainTest(args   = Array("-X", "low", "-e", "low"),
+                      stdout = defaultStdOut,
                       files  = Seq("Top.lo.fir", "Child.lo.fir")),
       FirrtlMainTest(args   = Array("-X", "verilog", "-e", "verilog"),
+                      stdout = defaultStdOut,
                       files  = Seq("Top.v", "Child.v")),
       FirrtlMainTest(args   = Array("-X", "sverilog", "-e", "sverilog"),
+                      stdout = defaultStdOut,
                       files  = Seq("Top.sv", "Child.sv")),
 
       /* Test mixing of -E with -e */
       FirrtlMainTest(args     = Array("-X", "middle", "-E", "high", "-e", "middle"),
+                     stdout   = defaultStdOut,
                      files    = Seq("Top.hi.fir", "Top.mid.fir", "Child.mid.fir"),
                      notFiles = Seq("Child.hi.fir")),
 
@@ -225,14 +247,19 @@ class FirrtlMainSpec extends AnyFeatureSpec with GivenWhenThen with Matchers wit
       FirrtlMainTest(args   = Array("-X", "none", "-E", "chirrtl", "-o", "foo"),
                       files  = Seq("foo.fir")),
       FirrtlMainTest(args   = Array("-X", "high", "-E", "high", "-o", "foo"),
+                      stdout = defaultStdOut,
                       files  = Seq("foo.hi.fir")),
       FirrtlMainTest(args   = Array("-X", "middle", "-E", "middle", "-o", "foo.middle"),
+                      stdout = defaultStdOut,
                       files  = Seq("foo.middle.mid.fir")),
       FirrtlMainTest(args   = Array("-X", "low", "-E", "low", "-o", "foo.lo.fir"),
+                      stdout = defaultStdOut,
                       files  = Seq("foo.lo.fir")),
       FirrtlMainTest(args   = Array("-X", "verilog", "-E", "verilog", "-o", "foo.sv"),
+                      stdout = defaultStdOut,
                       files  = Seq("foo.sv.v")),
       FirrtlMainTest(args   = Array("-X", "sverilog", "-E", "sverilog", "-o", "Foo"),
+                      stdout = defaultStdOut,
                       files  = Seq("Foo.sv"))
     )
       .foreach(runStageExpectFiles)
@@ -373,4 +400,5 @@ class FirrtlMainSpec extends AnyFeatureSpec with GivenWhenThen with Matchers wit
     )
       .foreach(runStageExpectFiles)
   }
+
 }