[firtool] Add include directory flag (#4539)

Can be used to provide nicer diagnostics or to help find supporting files like annotations.

test/firtool/include-dirs-annotations.fir

@@ -0,0 +1,16 @@
+; Test interaction between include directory and annotation files.
+
+; Setup:
+; RUN: rm -rf %t && mkdir -p %t
+; RUN: echo '[{ "class": "circt.test", "target": "~Test" }]' > %t/test.anno.json
+
+; Confirm annotation file not found without include directory provided:
+; RUN: not firtool %s --parse-only --annotation-file test.anno.json
+; Confirm annotation file is found.
+; RUN: firtool %s --parse-only --annotation-file test.anno.json -I %t | grep circt.test
+
+circuit Test:
+  module Test:
+    output o : UInt<1>
+    o <= UInt<1>(0)
+

test/firtool/include-dirs.fir

@@ -0,0 +1,27 @@
+; Test using "include directory" options for resolving source locators in diagnostics.
+
+; Setup:
+; RUN: rm -rf %t && mkdir -p %t/subdir %t/alt/subdir
+; RUN: echo -e "foo\ngenerate_bad_circuit" > %t/subdir/source.dummy
+; RUN: echo -e "foo\nalternate" > %t/alt/subdir/source.dummy
+
+; Check behavior when unable to find the mentioned file.
+; RUN: not firtool %s 2>&1 | FileCheck %s --check-prefixes=COMMON,MISSING
+; RUN: not firtool %s -I %t/subdir 2>&1 | FileCheck %s --check-prefixes=COMMON,MISSING
+
+; Check referenced file is found when its directory is specified.
+; RUN: not firtool %s -I %t -I %t/subdir 2>&1 | FileCheck %s --check-prefixes=COMMON,FOUND
+
+; Check search order.
+; RUN: not firtool %s -I %t/alt -I %t 2>&1 | FileCheck %s --check-prefixes=COMMON,ALTERNATE
+; RUN: not firtool %s -I %t -I %t/alt 2>&1 | FileCheck %s --check-prefixes=COMMON,FOUND
+
+; COMMON: subdir/source.dummy:2:3:
+; MISSING-NOT: alternate
+; MISSING-NOT: generate
+; ALTERNATE-NEXT: alternate
+; FOUND-NEXT: generate_bad_circuit
+
+; Invalid circuit that generates errors with the specified source locator:
+circuit Test: @[subdir/source.dummy 2:3]
+  module Oops:

tools/firtool/firtool.cpp

@@ -85,6 +85,10 @@ static cl::opt<bool>
                             "chunk independently"),
                    cl::init(false), cl::Hidden, cl::cat(mainCategory));
 
+static cl::list<std::string> includeDirs(
+    "I", cl::desc("Directory to search in when resolving source references"),
+    cl::value_desc("directory"), cl::Prefix, cl::cat(mainCategory));
+
 static cl::opt<bool>
     verifyDiagnostics("verify-diagnostics",
                       cl::desc("Check that emitted diagnostics match "
@@ -941,6 +945,7 @@ static LogicalResult processInputSplit(
     std::optional<std::unique_ptr<llvm::ToolOutputFile>> &outputFile) {
   llvm::SourceMgr sourceMgr;
   sourceMgr.AddNewSourceBuffer(std::move(buffer), llvm::SMLoc());
+  sourceMgr.setIncludeDirs(includeDirs);
   if (!verifyDiagnostics) {
     SourceMgrDiagnosticHandler sourceMgrHandler(sourceMgr, &context);
     return processBuffer(context, ts, sourceMgr, outputFile);