[circt-verilog-lsp] Add -C command line option

This PR extends the CIRCT Verilog LSP server with support for project command files (`-C` / `--command-file`) and improves robustness around source locations and diagnostics.

- **Command file support**
  - Added `commandFiles` option to `VerilogServerOptions`.
  - Extended the CLI with `-C`/`--command-file` flags to pass one or more command files.
  - Each buffer’s `Driver` now processes command files, filtering out the current main buffer to avoid duplication.
  - Implemented `removeFileToTemp` helper to strip the main file from command files and materialize a temporary version.

- **Source location handling**
  - Improved absolute/real path resolution when constructing LSP URIs.
  - Fallbacks added for when `slang::SourceManager` has no full path info.

- **Compilation setup**
  - Ensure all definitions in the buffer/project scope are treated as top modules.

- **Indexing improvements**
  - Skip top instances not defined in the current file.
  - Added guards against invalid or empty ranges (especially macro expansions).

Author: Scheremo

include/circt/Tools/circt-verilog-lsp-server/CirctVerilogLspServerMain.h

@@ -35,13 +35,17 @@ namespace circt {
 namespace lsp {
 struct VerilogServerOptions {
   VerilogServerOptions(const std::vector<std::string> &libDirs,
-                       const std::vector<std::string> &extraSourceLocationDirs)
-      : libDirs(libDirs), extraSourceLocationDirs(extraSourceLocationDirs) {}
+                       const std::vector<std::string> &extraSourceLocationDirs,
+                       const std::vector<std::string> &commandFiles)
+      : libDirs(libDirs), extraSourceLocationDirs(extraSourceLocationDirs),
+        commandFiles(commandFiles) {}
   /// Additional list of RTL directories to search.
   const std::vector<std::string> &libDirs;
-
   /// Additional list of external source directories to search.
   const std::vector<std::string> &extraSourceLocationDirs;
+  /// Additional list of command files that reference dependencies of the
+  /// project.
+  const std::vector<std::string> &commandFiles;
 };
 // namespace lsp
 

lib/Tools/circt-verilog-lsp-server/LSPServer.cpp

@@ -8,6 +8,7 @@
 
 #include "LSPServer.h"
 #include "VerilogServerImpl/VerilogServer.h"
+#include "llvm/Support/JSON.h"
 #include "llvm/Support/LSP/Protocol.h"
 #include "llvm/Support/LSP/Transport.h"
 #include <optional>

lib/Tools/circt-verilog-lsp-server/VerilogServerImpl/VerilogServer.cpp

@@ -23,9 +23,12 @@
 #include "mlir/IR/MLIRContext.h"
 #include "slang/ast/ASTVisitor.h"
 #include "slang/ast/Compilation.h"
+#include "slang/ast/Scope.h"
+#include "slang/ast/symbols/CompilationUnitSymbols.h"
 #include "slang/diagnostics/DiagnosticClient.h"
 #include "slang/diagnostics/Diagnostics.h"
 #include "slang/driver/Driver.h"
+#include "slang/syntax/AllSyntax.h"
 #include "slang/syntax/SyntaxTree.h"
 #include "slang/text/SourceLocation.h"
 #include "slang/text/SourceManager.h"
@@ -42,6 +45,8 @@
 #include "llvm/Support/SMLoc.h"
 #include "llvm/Support/SourceMgr.h"
 
+#include <filesystem>
+#include <fstream>
 #include <memory>
 #include <optional>
 #include <string>
@@ -247,13 +252,107 @@ void LSPDiagnosticClient::report(const slang::ReportedDiagnostic &slangDiag) {
 // VerilogDocument
 //===----------------------------------------------------------------------===//
 
+// Filter out the main buffer file from the command file list, if it is in
+// there.
+static inline std::string removeFileToTemp(const std::string &cmdfileStr,
+                                           const std::string &targetAbsStr) {
+  namespace fs = std::filesystem;
+
+  fs::path cmdfile(cmdfileStr);
+  fs::path targetAbs(targetAbsStr);
+  const fs::path base = cmdfile.parent_path();
+  std::error_code ec;
+
+  // Normalize target
+  fs::path target = fs::weakly_canonical(targetAbs, ec);
+  if (ec) {
+    ec.clear();
+    target = targetAbs.lexically_normal();
+  }
+
+  std::ifstream in(cmdfile);
+  if (!in) {
+    // return the original path so the caller still has a valid file to use
+    return cmdfileStr;
+  }
+
+  std::string line, outbuf;
+  bool removed = false;
+
+  while (std::getline(in, line)) {
+    std::string s = line;
+    s.erase(0, s.find_first_not_of(" \t\r\n")); // left-trim
+
+    // Keep plusargs
+    if (!s.empty() &&
+        (s.rfind("+incdir+", 0) == 0 || s.rfind("+define+", 0) == 0 ||
+         s.rfind("-I", 0) == 0 || s.rfind("-D", 0) == 0)) {
+      outbuf += line;
+      outbuf.push_back('\n');
+      continue;
+    }
+    // Preserve blank lines
+    if (s.empty()) {
+      outbuf.push_back('\n');
+      continue;
+    }
+
+    // Treat everything else as a path (relative entries resolved vs. cmdfile
+    // dir)
+    fs::path candRel = s;
+    fs::path candAbs = candRel.is_absolute() ? candRel : (base / candRel);
+
+    fs::path cand = fs::weakly_canonical(candAbs, ec);
+    if (ec) {
+      ec.clear();
+      cand = candAbs.lexically_normal();
+    }
+
+    if (cand == target) {
+      removed = true; // skip writing this line
+    } else {
+      outbuf += line;
+      outbuf.push_back('\n');
+    }
+  }
+
+  if (!removed) {
+    // Nothing changed: return the original commandfile path
+    return cmdfileStr;
+  }
+  // Write updated content to a temp file next to the original
+  fs::path tmp = base / (cmdfile.filename().string() + ".tmp");
+  std::ofstream out(tmp, std::ios::trunc);
+  out << outbuf;
+  return tmp.string();
+}
+
+static inline std::string removeFileToTemp(llvm::StringRef cmdfile,
+                                           llvm::StringRef target_abs) {
+  return removeFileToTemp(cmdfile.str(), target_abs.str());
+}
+
 VerilogDocument::VerilogDocument(
     VerilogServerContext &context, const llvm::lsp::URIForFile &uri,
     StringRef contents, std::vector<llvm::lsp::Diagnostic> &diagnostics)
     : globalContext(context), index(*this), uri(uri) {
   unsigned int bufferId;
+
+  llvm::SmallString<256> canonPath(uri.file());
+  if (std::error_code ec = llvm::sys::fs::real_path(uri.file(), canonPath))
+    canonPath = uri.file(); // fall back, but try to keep it absolute
+
+  // --- Apply project command files (the “-C”s) to this per-buffer driver ---
+  for (const std::string &cmdFile : context.options.commandFiles) {
+    if (!driver.processCommandFiles(removeFileToTemp(cmdFile, canonPath), false,
+                                    true)) {
+      circt::lsp::Logger::error(Twine("Failed to open command file ") +
+                                cmdFile);
+    }
+  }
+
   if (auto memBufferOwn =
-          llvm::MemoryBuffer::getMemBufferCopy(contents, uri.file())) {
+          llvm::MemoryBuffer::getMemBufferCopy(contents, canonPath)) {
 
     bufferId = sourceMgr.AddNewSourceBuffer(std::move(memBufferOwn), SMLoc());
   } else {
@@ -303,6 +402,18 @@ VerilogDocument::VerilogDocument(
     return;
   }
 
+  compilation = driver.createCompilation();
+  if (failed(compilation))
+    return;
+
+  std::vector<std::string> topModules;
+  for (const auto *defs : (*compilation)->getDefinitions())
+    topModules.emplace_back(defs->name);
+
+  // Make sure that all possible definitions in the file / project scope are
+  // topModules!
+  driver.options.topModules = topModules;
+
   compilation = driver.createCompilation();
   if (failed(compilation))
     return;
@@ -321,19 +432,28 @@ VerilogDocument::getLspLocation(slang::SourceLocation loc) const {
     auto line = slangSourceManager.getLineNumber(loc) - 1;
     auto column = slangSourceManager.getColumnNumber(loc) - 1;
     auto it = bufferIDMap.find(loc.buffer().getId());
-    // Check if the current buffer is the main file.
     if (it != bufferIDMap.end() && it->second == sourceMgr.getMainFileID())
       return llvm::lsp::Location(uri, llvm::lsp::Range(Position(line, column)));
 
-    // Otherwise, construct URI from slang source manager.
-    auto fileName = slangSourceManager.getFileName(loc);
-    auto loc = llvm::lsp::URIForFile::fromFile(fileName);
-    if (auto e = loc.takeError())
-      return llvm::lsp::Location();
-    return llvm::lsp::Location(loc.get(),
-                               llvm::lsp::Range(Position(line, column)));
-  }
+    llvm::StringRef fileName = slangSourceManager.getFileName(loc);
+    // Ensure absolute path for LSP:
+    llvm::SmallString<256> abs(fileName);
+    if (!llvm::sys::path::is_absolute(abs)) {
+      // Try realPath first
+      if (std::error_code ec = llvm::sys::fs::real_path(fileName, abs)) {
+        // Fallback: make it absolute relative to the process CWD
+        llvm::sys::fs::current_path(abs); // abs = CWD
+        llvm::sys::path::append(abs, fileName);
+      }
+    }
 
+    if (auto uriOrErr = llvm::lsp::URIForFile::fromFile(abs)) {
+      return llvm::lsp::Location(*uriOrErr,
+                                 llvm::lsp::Range(Position(line, column)));
+    }
+    // If we can't form a URI, return empty (avoids crashing)
+    return llvm::lsp::Location();
+  }
   return llvm::lsp::Location();
 }
 
@@ -357,8 +477,24 @@ llvm::SMLoc VerilogDocument::getSMLoc(slang::SourceLocation loc) {
   auto bufferIDMapIt = bufferIDMap.find(bufferID);
   if (bufferIDMapIt == bufferIDMap.end()) {
     // If not, open the source file and add it to the LLVM source manager.
-    auto path = getSlangSourceManager().getFullPath(loc.buffer());
-    auto memBuffer = llvm::MemoryBuffer::getFile(path.string());
+    const slang::SourceManager &ssm = getSlangSourceManager();
+    auto path = ssm.getFullPath(loc.buffer());
+
+    std::string name;
+    if (path.empty()) {
+      // Get filename from slang source manager - might've been loaded already!
+      llvm::StringRef fname = ssm.getFileName(loc);
+      llvm::SmallString<256> realPath;
+      if (!llvm::sys::fs::real_path(fname, realPath)) {
+        name = realPath.str().str();
+      } else {
+        name = fname.str();
+      }
+    } else {
+      name = path.string();
+    }
+
+    auto memBuffer = llvm::MemoryBuffer::getFile(name);
     if (!memBuffer) {
       circt::lsp::Logger::error(
           "Failed to open file: " + path.filename().string() +
@@ -523,6 +659,13 @@ struct VerilogIndexer : slang::ast::ASTVisitor<VerilogIndexer, true, true> {
       return;
     assert(range.start().valid() && range.end().valid() &&
            "range must be valid");
+
+    // TODO: This implementation does not handle expanded MACROs. Return
+    // instead.
+    if (range.start() >= range.end()) {
+      return;
+    }
+
     index.insertSymbol(symbol, range, isDefinition);
   }
 
@@ -557,6 +700,30 @@ struct VerilogIndexer : slang::ast::ASTVisitor<VerilogIndexer, true, true> {
     visitDefault(expr);
   }
 
+  void visit(const slang::ast::InstanceSymbol &expr) {
+    auto *def = &expr.getDefinition();
+    if (!def)
+      return;
+
+    // Add the module definition
+    insertSymbol(def, def->location, /*isDefinition=*/true);
+
+    // Walk up the syntax tree until we hit the type token;
+    // Link that token back to the instance declaration.
+    if (auto *hierInst =
+            expr.getSyntax()
+                ->as_if<slang::syntax::HierarchicalInstanceSyntax>())
+      if (auto *modInst =
+              hierInst->parent
+                  ->as_if<slang::syntax::HierarchyInstantiationSyntax>())
+        if (modInst->type)
+          insertSymbol(def, modInst->type.location(), false);
+
+    // Link the module instance name back to the module definition
+    insertSymbol(def, expr.location, /*isDefinition=*/false);
+    visitDefault(expr);
+  }
+
   void visit(const slang::ast::VariableDeclStatement &expr) {
     insertSymbol(&expr.symbol, expr.sourceRange, /*isDefinition=*/true);
     visitDefault(expr);
@@ -580,7 +747,13 @@ struct VerilogIndexer : slang::ast::ASTVisitor<VerilogIndexer, true, true> {
 void VerilogIndex::initialize(slang::ast::Compilation &compilation) {
   const auto &root = compilation.getRoot();
   VerilogIndexer visitor(*this);
+
   for (auto *inst : root.topInstances) {
+
+    // Skip all modules, interfaces, etc. that are not defined in this files
+    if (!(document.getLspLocation(inst->location).uri == document.getURI()))
+      continue;
+
     // Visit the body of the instance.
     inst->body.visit(visitor);
 
@@ -752,10 +925,17 @@ void circt::lsp::VerilogServer::findReferencesOf(
 void VerilogIndex::insertSymbol(const slang::ast::Symbol *symbol,
                                 slang::SourceRange from, bool isDefinition) {
   assert(from.start().valid() && from.end().valid());
+
+  // TODO: Currently doesn't handle expanded macros
+  if (!from.start().valid() || !from.end().valid() ||
+      from.start() >= from.end())
+    return;
+
   const char *startLoc = getDocument().getSMLoc(from.start()).getPointer();
   const char *endLoc = getDocument().getSMLoc(from.end()).getPointer() + 1;
-  if (!startLoc || !endLoc)
+  if (!startLoc || !endLoc || startLoc >= endLoc)
     return;
+
   assert(startLoc && endLoc);
 
   if (startLoc != endLoc && !intervalMap.overlaps(startLoc, endLoc)) {

test/Tools/circt-verilog-lsp-server/command-files.test

@@ -0,0 +1,64 @@
+// RUN: cd %S && circt-verilog-lsp-server -lit-test -C %S/include/filelist.f < %s | FileCheck %s
+// REQUIRES: slang
+{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"processId":123,"rootPath":"verilog","capabilities":{},"trace":"off"}}
+// -----
+{"jsonrpc":"2.0","method":"textDocument/didOpen","params":{"textDocument":{
+  "uri":"test:///foo.sv",
+  "languageId":"verilog",
+  "version":1,
+  "text":"module test(output out\n);ifdef#()i_dut(.out(out));\nendmodule"
+}}}
+// -----
+// Find definition of `i_dut`
+{"jsonrpc":"2.0","id":1,"method":"textDocument/definition","params":{
+  "textDocument":{"uri":"test:///foo.sv"},
+  "position":{"line":1,"character":12}
+}}
+// -----
+// CHECK:  "id": 1,
+// CHECK-NEXT:  "jsonrpc": "2.0",
+// CHECK-NEXT:  "result": [
+// CHECK-NEXT:    {
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:        "end": {
+// CHECK-NEXT:          "character": 12,
+// CHECK-NEXT:          "line": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "start": {
+// CHECK-NEXT:          "character": 7,
+// CHECK-NEXT:          "line": 0
+// CHECK-NEXT:        }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "uri": "file:///{{.*}}/include/ifdef.sv"
+// CHECK-NEXT:    }
+// CHECK-NEXT:  ]
+// CHECK-NEXT:}
+// -----
+// Find definition of `ifdef`
+{"jsonrpc":"2.0","id":2,"method":"textDocument/definition","params":{
+  "textDocument":{"uri":"test:///foo.sv"},
+  "position":{"line":1,"character":4}
+}}
+// -----
+// CHECK:  "id": 2,
+// CHECK-NEXT:  "jsonrpc": "2.0",
+// CHECK-NEXT:  "result": [
+// CHECK-NEXT:    {
+// CHECK-NEXT:      "range": {
+// CHECK-NEXT:        "end": {
+// CHECK-NEXT:          "character": 12,
+// CHECK-NEXT:          "line": 0
+// CHECK-NEXT:        },
+// CHECK-NEXT:        "start": {
+// CHECK-NEXT:          "character": 7,
+// CHECK-NEXT:          "line": 0
+// CHECK-NEXT:        }
+// CHECK-NEXT:      },
+// CHECK-NEXT:      "uri": "file:///{{.*}}/include/ifdef.sv"
+// CHECK-NEXT:    }
+// CHECK-NEXT:  ]
+// CHECK-NEXT:}
+// -----
+{"jsonrpc":"2.0","id":3,"method":"shutdown"}
+// -----
+{"jsonrpc":"2.0","method":"exit"}

test/Tools/circt-verilog-lsp-server/include/filelist.f

@@ -0,0 +1 @@
+include/ifdef.sv

test/Tools/circt-verilog-lsp-server/include/ifdef.sv

@@ -0,0 +1,3 @@
+module ifdef(output out);
+   assign out = 1'b1;
+endmodule