Report firtool version when firtool invocation errors (backport #3174) (#3175)

* Report firtool version when firtool invocation errors (#3174)

* the firtool version is now included in the BuildInfo
* firtool now must be on the path when publishing, but is not required
  for building or testing
* FirtoolNonZeroExitCode now no longer includes a stack trace

(cherry picked from commit 06b569d)

# Conflicts:
#	build.sbt

* Resolve backport conflicts

* [CI] Install firtool in the publish step (#3176)

---------

Co-authored-by: Jack Koenig <koenig@sifive.com>

Author: mergify[bot]

.github/workflows/test.yml

@@ -195,6 +195,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+      - name: Install CIRCT
+        uses: ./.github/workflows/install-circt
       - name: Setup Scala
         uses: actions/setup-java@v3
         with:

build.sbt

@@ -5,6 +5,18 @@ enablePlugins(SiteScaladocPlugin)
 addCommandAlias("fmt", "; scalafmtAll ; scalafmtSbt")
 addCommandAlias("fmtCheck", "; scalafmtCheckAll ; scalafmtSbtCheck")
 
+lazy val firtoolVersion = settingKey[Option[String]]("Determine the version of firtool on the PATH")
+ThisBuild / firtoolVersion := {
+  import scala.sys.process._
+  val Version = """^CIRCT firtool-(\S+)$""".r
+  try {
+    val lines = Process(Seq("firtool", "--version")).lineStream
+    lines.collectFirst { case Version(v) => v }
+  } catch {
+    case e: java.io.IOException => None
+  }
+}
+
 val defaultVersions = Map(
   "firrtl" -> "edu.berkeley.cs" %% "firrtl" % "1.6-SNAPSHOT"
   // chiseltest intentionally excluded so that release automation does not try to set its version
@@ -69,6 +81,16 @@ lazy val publishSettings = Seq(
   versionScheme := Some("pvp"),
   publishMavenStyle := true,
   Test / publishArtifact := false,
+  // We are just using 'publish / skip' as a hook to run checks required for publishing,
+  // but that are not necessarily required for local development or running testing in CI
+  publish / skip := {
+    // Check that firtool exists on the PATH so Chisel can use the version it was tested against
+    // in error messages
+    if (firtoolVersion.value.isEmpty) {
+      sys.error(s"Failed to determine firtool version. Make sure firtool is found on the PATH.")
+    }
+    (publish / skip).value
+  },
   pomIncludeRepository := { x => false },
   pomExtra := <url>http://chisel.eecs.berkeley.edu/</url>
     <licenses>
@@ -197,7 +219,7 @@ lazy val core = (project in file("core"))
   .settings(
     buildInfoPackage := "chisel3",
     buildInfoUsePackageAsPath := true,
-    buildInfoKeys := Seq[BuildInfoKey](buildInfoPackage, version, scalaVersion, sbtVersion)
+    buildInfoKeys := Seq[BuildInfoKey](buildInfoPackage, version, scalaVersion, sbtVersion, firtoolVersion)
   )
   .settings(publishSettings: _*)
   .settings(mimaPreviousArtifacts := Set())

src/main/scala/circt/stage/phases/CIRCT.scala

@@ -4,6 +4,7 @@ package circt.stage.phases
 
 import chisel3.experimental.hierarchy.core.ImportDefinitionAnnotation
 import chisel3.stage.{ChiselCircuitAnnotation, DesignAnnotation, SourceRootAnnotation}
+import chisel3.BuildInfo.{version => chiselVersion, firtoolVersion}
 
 import circt.Implicits.BooleanImplicits
 import circt.stage.{CIRCTOptions, CIRCTTarget, EmittedMLIR, PreserveAggregate}
@@ -26,6 +27,7 @@ import firrtl.stage.{FirrtlOptions, RunFirrtlTransformAnnotation}
 import _root_.logger.LogLevel
 import chisel3.InternalErrorException
 
+import scala.util.control.NoStackTrace
 import scala.collection.mutable
 import java.io.File
 
@@ -81,6 +83,10 @@ private[this] object Exceptions {
         |${"-" * 78}""".stripMargin
   }
 
+  def versionAdvice: String =
+    s"Note that this version of Chisel ($chiselVersion) was published against firtool version " +
+      firtoolVersion.getOrElse("<unknown>") + "."
+
   /** Indicates that the firtool binary failed with a non-zero exit code.  This generally indicates a compiler error
     * either originating from a user error or from a crash.
     *
@@ -92,10 +98,11 @@ private[this] object Exceptions {
   class FirtoolNonZeroExitCode(binary: String, exitCode: Int, stdout: String, stderr: String)
       extends RuntimeException(
         dramaticError(
-          header = s"${binary} returned a non-zero exit code",
+          header = s"${binary} returned a non-zero exit code. $versionAdvice",
           body = s"ExitCode:\n${exitCode}\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}"
         )
       )
+      with NoStackTrace
 
   /** Indicates that the firtool binary was not found.  This likely indicates that the user didn't install
     * CIRCT/firtool.

src/test/scala/circtTests/stage/ChiselStageSpec.scala

@@ -503,6 +503,13 @@ class ChiselStageSpec extends AnyFunSpec with Matchers with chiselTests.Utils {
       lines(idx + 2) should equal("         ^")
     }
 
+    it("should report the firtool version against which Chisel was published in error messages") {
+      val e = intercept[java.lang.Exception] {
+        ChiselStage.emitSystemVerilog(new ChiselStageSpec.ErrorCaughtByFirtool)
+      }
+      val version = chisel3.BuildInfo.firtoolVersion.getOrElse("<unknown>")
+      e.getMessage should include(s"firtool version $version")
+    }
   }
 
   describe("ChiselStage custom transform support") {