Give a source line and caret for errors when possible (#3039)

This includes new command-line option --source-root which allows the
user of Chisel to point to one or more root directories for source files.
If no --source-root arguments are provided, it will default to using
"." which should work for typical SBT and Mill projects.

Author: jackkoenig

core/src/main/scala/chisel3/experimental/hierarchy/core/Definition.scala

@@ -103,7 +103,7 @@ object Definition extends SourceInfoDoc {
   ): Definition[T] = {
     val dynamicContext = {
       val context = Builder.captureContext()
-      new DynamicContext(Nil, context.throwOnFirstError, context.warningsAsErrors)
+      new DynamicContext(Nil, context.throwOnFirstError, context.warningsAsErrors, context.sourceRoots)
     }
     Builder.globalNamespace.copyTo(dynamicContext.globalNamespace)
     dynamicContext.inDefinition = true

core/src/main/scala/chisel3/internal/Builder.scala

@@ -20,6 +20,7 @@ import logger.LazyLogging
 
 import scala.collection.mutable
 import scala.annotation.tailrec
+import java.io.File
 
 private[chisel3] class Namespace(keywords: Set[String]) {
   // This HashMap is compressed, not every name in the namespace is present here.
@@ -425,7 +426,8 @@ private[chisel3] class ChiselContext() {
 private[chisel3] class DynamicContext(
   val annotationSeq:     AnnotationSeq,
   val throwOnFirstError: Boolean,
-  val warningsAsErrors:  Boolean) {
+  val warningsAsErrors:  Boolean,
+  val sourceRoots:       Seq[File]) {
   val importDefinitionAnnos = annotationSeq.collect { case a: ImportDefinitionAnnotation[_] => a }
 
   // Map holding the actual names of extModules
@@ -484,7 +486,7 @@ private[chisel3] class DynamicContext(
   var whenStack:            List[WhenContext] = Nil
   var currentClock:         Option[Clock] = None
   var currentReset:         Option[Reset] = None
-  val errors = new ErrorLog(warningsAsErrors)
+  val errors = new ErrorLog(warningsAsErrors, sourceRoots)
   val namingStack = new NamingStack
 
   // Used to indicate if this is the top-level module of full elaboration, or from a Definition

core/src/main/scala/chisel3/internal/Error.scala

@@ -6,6 +6,8 @@ import scala.annotation.tailrec
 import scala.collection.mutable.{ArrayBuffer, LinkedHashMap, LinkedHashSet}
 import scala.util.control.NoStackTrace
 import _root_.logger.Logger
+import java.io.File
+import scala.io.Source
 
 import chisel3.experimental.{NoSourceInfo, SourceInfo, SourceLine, UnlocatableSourceInfo}
 
@@ -98,7 +100,29 @@ private[chisel3] object ErrorLog {
   val errTag = s"[${Console.RED}error${Console.RESET}]"
 }
 
-private[chisel3] class ErrorLog(warningsAsErrors: Boolean) {
+private[chisel3] class ErrorLog(warningsAsErrors: Boolean, sourceRoots: Seq[File]) {
+
+  private def getErrorLineInFile(sl: SourceLine): List[String] = {
+    def tryFileInSourceRoot(sourceRoot: File): Option[List[String]] = {
+      try {
+        val file = new File(sourceRoot, sl.filename)
+        val lines = Source.fromFile(file).getLines()
+        var i = 0
+        while (i < (sl.line - 1) && lines.hasNext) {
+          lines.next()
+          i += 1
+        }
+        val line = lines.next()
+        val caretLine = (" " * (sl.col - 1)) + "^"
+        Some(line :: caretLine :: Nil)
+      } catch {
+        case scala.util.control.NonFatal(_) => None
+      }
+    }
+    val sourceRootsWithDefault = if (sourceRoots.nonEmpty) sourceRoots else Seq(new File("."))
+    // View allows us to search the directories one at a time and early out
+    sourceRootsWithDefault.view.map(tryFileInSourceRoot(_)).collectFirst { case Some(value) => value }.getOrElse(Nil)
+  }
 
   /** Returns an appropriate location string for the provided source info.
     * If the source info is of `NoSourceInfo` type, the source location is looked up via stack trace.
@@ -119,8 +143,9 @@ private[chisel3] class ErrorLog(warningsAsErrors: Boolean) {
 
   private def errorEntry(msg: String, si: Option[SourceInfo], isFatal: Boolean): ErrorEntry = {
     val location = errorLocationString(si)
+    val sourceLineAndCaret = si.collect { case sl: SourceLine => getErrorLineInFile(sl) }.getOrElse(Nil)
     val fullMessage = if (location.isEmpty) msg else s"$location: $msg"
-    ErrorEntry(fullMessage, isFatal)
+    ErrorEntry(fullMessage :: sourceLineAndCaret, isFatal)
   }
 
   /** Log an error message */
@@ -158,7 +183,7 @@ private[chisel3] class ErrorLog(warningsAsErrors: Boolean) {
       case ((message, sourceLoc), count) =>
         logger.warn(s"${ErrorLog.depTag} $sourceLoc ($count calls): $message")
     }
-    errors.foreach(e => logger.error(s"${e.tag} ${e.msg}"))
+    errors.foreach(e => logger.error(e.serialize))
 
     if (!deprecations.isEmpty) {
       logger.warn(
@@ -237,6 +262,8 @@ private[chisel3] class ErrorLog(warningsAsErrors: Boolean) {
   private def elapsedTime: Long = System.currentTimeMillis - startTime
 }
 
-private case class ErrorEntry(msg: String, isFatal: Boolean) {
+private case class ErrorEntry(lines: Seq[String], isFatal: Boolean) {
   def tag = if (isFatal) ErrorLog.errTag else ErrorLog.warnTag
+
+  def serialize: String = lines.map(s"$tag " + _).mkString("\n")
 }

src/main/scala/chisel3/aop/injecting/InjectingAspect.scala

@@ -62,7 +62,8 @@ abstract class InjectorAspect[T <: RawModule, M <: RawModule](
         new DynamicContext(
           annotationsInAspect,
           chiselOptions.throwOnFirstError,
-          chiselOptions.warningsAsErrors
+          chiselOptions.warningsAsErrors,
+          chiselOptions.sourceRoots
         )
       // Add existing module names into the namespace. If injection logic instantiates new modules
       //  which would share the same name, they will get uniquified accordingly

src/main/scala/chisel3/stage/ChiselAnnotations.scala

@@ -99,6 +99,30 @@ case object WarningsAsErrorsAnnotation
 
 }
 
+/** A root directory for source files, used for enhanced error reporting
+  *
+  * More than one may be provided. If a source file is found in more than one source root,
+  * the first match will be used in error reporting.
+  */
+case class SourceRootAnnotation(directory: File) extends NoTargetAnnotation with Unserializable with ChiselOption
+
+object SourceRootAnnotation extends HasShellOptions {
+  val options = Seq(
+    new ShellOption[String](
+      longOption = "source-root",
+      toAnnotationSeq = { dir =>
+        val f = new File(dir)
+        if (!f.isDirectory()) {
+          throw new OptionsException(s"Must be directory that exists!")
+        }
+        Seq(SourceRootAnnotation(f))
+      },
+      helpText = "Root directory for source files, used for enhanced error reporting",
+      helpValueName = Some("<file>")
+    )
+  )
+}
+
 /** Warn when reflective naming changes names of signals */
 @deprecated("Support for reflective naming has been removed, this object no longer does anything", "Chisel 3.6")
 case object WarnReflectiveNamingAnnotation

src/main/scala/chisel3/stage/ChiselCli.scala

@@ -13,6 +13,7 @@ trait ChiselCli { this: Shell =>
     PrintFullStackTraceAnnotation,
     ThrowOnFirstErrorAnnotation,
     WarningsAsErrorsAnnotation,
+    SourceRootAnnotation,
     WarnReflectiveNamingAnnotation,
     ChiselOutputFileAnnotation,
     ChiselGeneratorAnnotation

src/main/scala/chisel3/stage/ChiselOptions.scala

@@ -3,22 +3,25 @@
 package chisel3.stage
 
 import chisel3.internal.firrtl.Circuit
+import java.io.File
 
 class ChiselOptions private[stage] (
   val runFirrtlCompiler:   Boolean = true,
   val printFullStackTrace: Boolean = false,
   val throwOnFirstError:   Boolean = false,
   val warningsAsErrors:    Boolean = false,
   val outputFile:          Option[String] = None,
-  val chiselCircuit:       Option[Circuit] = None) {
+  val chiselCircuit:       Option[Circuit] = None,
+  val sourceRoots:         Vector[File] = Vector.empty) {
 
   private[stage] def copy(
     runFirrtlCompiler:   Boolean = runFirrtlCompiler,
     printFullStackTrace: Boolean = printFullStackTrace,
     throwOnFirstError:   Boolean = throwOnFirstError,
     warningsAsErrors:    Boolean = warningsAsErrors,
     outputFile:          Option[String] = outputFile,
-    chiselCircuit:       Option[Circuit] = chiselCircuit
+    chiselCircuit:       Option[Circuit] = chiselCircuit,
+    sourceRoots:         Vector[File] = sourceRoots
   ): ChiselOptions = {
 
     new ChiselOptions(
@@ -27,7 +30,8 @@ class ChiselOptions private[stage] (
       throwOnFirstError = throwOnFirstError,
       warningsAsErrors = warningsAsErrors,
       outputFile = outputFile,
-      chiselCircuit = chiselCircuit
+      chiselCircuit = chiselCircuit,
+      sourceRoots = sourceRoots
     )
 
   }

src/main/scala/chisel3/stage/package.scala

@@ -27,6 +27,7 @@ package object stage {
           case WarnReflectiveNamingAnnotation => c // Do nothing, ignored
           case ChiselOutputFileAnnotation(f)  => c.copy(outputFile = Some(f))
           case ChiselCircuitAnnotation(a)     => c.copy(chiselCircuit = Some(a))
+          case SourceRootAnnotation(s)        => c.copy(sourceRoots = c.sourceRoots :+ s)
         }
       }
 

src/main/scala/chisel3/stage/phases/Elaborate.scala

@@ -33,7 +33,8 @@ class Elaborate extends Phase {
           new DynamicContext(
             annotations,
             chiselOptions.throwOnFirstError,
-            chiselOptions.warningsAsErrors
+            chiselOptions.warningsAsErrors,
+            chiselOptions.sourceRoots
           )
         val (circuit, dut) =
           Builder.build(Module(gen()), context)

src/main/scala/circt/stage/CIRCTStage.scala

@@ -6,6 +6,7 @@ import chisel3.deprecatedMFCMessage
 import chisel3.stage.{
   ChiselGeneratorAnnotation,
   PrintFullStackTraceAnnotation,
+  SourceRootAnnotation,
   ThrowOnFirstErrorAnnotation,
   WarningsAsErrorsAnnotation
 }
@@ -23,6 +24,7 @@ trait CLI { this: Shell =>
     PrintFullStackTraceAnnotation,
     ThrowOnFirstErrorAnnotation,
     WarningsAsErrorsAnnotation,
+    SourceRootAnnotation,
     SplitVerilog
   ).foreach(_.addOptions(parser))
 }