极客工场

Appearance

共 1,359 字预计阅读约 5 分钟

Verilator 找不到 SV package 定义文件：PKGNODECL 报错与 -y 搜索目录无效的原因 ​

更新时间：2026-11-11。长尾速查篇，属于 EDA 报错排查系列，汇总入口见 开源 EDA 报错排查导航。SystemVerilog 的 package 单独放在一个文件里，模块里写 import iopkg::*; 引用，用 Verilator lint 时却收到 %Error-PKGNODECL。文件明明就在 rtl/ 目录下，为什么编译器看不见？本文用 Verilator 5.020 的最小设计把这条报错跑透，并解释 -y 搜索目录为什么对 package 无效。

首屏答案：verilator --lint-only rtl/top.sv 只把 top.sv 交给了编译器，定义 iopkg 的 rtl/iopkg.sv 根本没有进入编译，全局包名表里没有 iopkg 条目，import 查表失败抛出 PKGNODECL。-y rtl 只在解析未实例化的 module 时按模块名找文件，不会为 package 建立条目，所以加上照样报错。修复只有一条正路：把 package 文件显式列进命令行且放在使用者之前——verilator --lint-only rtl/iopkg.sv rtl/top.sv，复跑退出码 0。

PKGNODECL 分诊漏斗：从 lint 三连报错收窄到 package 文件漏列

这张漏斗对应本文的排查顺序：先读报错里的 IEEE 条款号确认是包声明问题，再核对命令行究竟交了哪些文件给编译器，最后才动目录参数。跳过文件清单核对直接试 -y、-I，是这类报错最常见的弯路。

本文要回答的问题 ​

  • 独立文件里的 SV package 没有列进 Verilator 命令行时，完整报错原文是什么，退出码是多少？
  • 报错里的 PKGNODECL 和后面那条 syntax error 是什么关系，真的有语法错误吗？
  • -y 模块搜索目录为什么救不了 package，它和普通 module 找不到文件的报错差在哪？
  • 正确的修复命令是什么，多个 package 文件时怎么固定编译顺序？

一、完整报错原文 ​

最小设计两个文件。rtl/iopkg.sv 定义一个带参数和枚举类型的 package：

systemverilog
package iopkg;
  parameter int WIDTH = 8;
  typedef enum logic [1:0] {OP_ADD, OP_SUB, OP_MUL} op_t;
endpackage

rtl/top.sv 通过通配导入引用包里的类型和枚举值，case 语句本身带 default，语法没有残缺：

systemverilog
module top;
  import iopkg::*;
  var op_t op = OP_ADD;
  logic [WIDTH-1:0] a = 8'd3, b = 8'd4, y;
  always @(*) begin
    case (op)
      OP_ADD: y = a + b;
      OP_SUB: y = a - b;
      OP_MUL: y = a * b;
      default: y = '0;
    endcase
  end
endmodule

只把 top.sv 交给 Verilator 做 lint，完整输出原样摘录如下：

exp-log
--- 1. package file missing from command line: PKGNODECL ---
$ verilator --lint-only rtl/top.sv
%Error-PKGNODECL: rtl/top.sv:2:10: Package/class 'iopkg' not found, and needs to be predeclared (IEEE 1800-2017 26.3)
    2 |   import iopkg::*;
      |          ^~~~~
                  ... For error description see https://verilator.org/warn/PKGNODECL?v=5.020
%Error: rtl/top.sv:2:10: Importing from missing package 'iopkg'
    2 |   import iopkg::*;
      |          ^~~~~
%Error: rtl/top.sv:3:12: syntax error, unexpected IDENTIFIER, expecting ',' or ';'
    3 |   var op_t op = OP_ADD;
      |            ^~
%Error: Exiting due to 3 error(s)
        ... See the manual at https://verilator.org/verilator_doc.html for more assistance.
exit code: 1

三条错误要连起来读。第一条 PKGNODECL 是根诊断，措辞直接引用 IEEE 1800-2017 第 26.3 节：package 在使用前必须预先声明，而编译器当前不认识 iopkg。第二条是同一位置的复述，明确说「从一个缺失的 package 导入」。第三条 syntax error 只是级联——op_t 这个类型名因为导入失败而未定义，解析器在第 3 行读到陌生标识符后无法继续，报出 unexpected IDENTIFIER。源码本身没有语法问题，不要去改第 3 行；包一旦可见，这条语法错误会自动消失。

二、工具与版本 ​

本次全部实验在 Docker 镜像 geek-eda:0.2 内完成，容器底层是 Debian bookworm，Verilator 版本为 5.020，与日志头部记录一致。宿主机只负责启动容器和挂载目录，不参与编译。

版本信息要先固定，因为 PKGNODECL 的诊断措辞、警告编号和附带的文档链接随版本演进。本文的报错原文、行号列号和退出码只对 5.020 这个构建负责；换到其他大版本时，应保留当次完整输出再对照，不能凭本文原文反推。另外，--lint-only 只做语法与静态规则检查、不生成 C++ 骨架，因此本文的现象与工程是否带 testbench、是否执行 make 无关，纯 RTL 工程同样会踩到。

三、根本原因：package 靠显式编译，-y 只服务 module ​

3.1 包名表与模块名表是两套解析机制 ​

Verilator 处理命令行上的位置参数时，会按给出的顺序逐个读入源文件。读到 package iopkg; ... endpackage 时，把包名和里面的参数、类型登记进一张全局包名表；之后遇到 import iopkg::*，就在这张表里查 iopkg。包名表的条目只有一个来源：被显式读入的源文件里的 package 声明。命令行上没有 iopkg.sv，这张表里就永远没有 iopkg，查表必然失败。

eda/ts-verilator-package-import-not-found.md D2 示意图

图中蓝色是编译器的输入，紫色是 package 专属的注册通道，灰色的 -y 搜索目录与这条通道不相连。Verilator 的 -y（配合 +libext+ 使用）机制继承自 Verilog 老传统：只有在层次展开时遇到一个找不到定义的 module 实例，编译器才去 -y 指定的目录里按「模块名加后缀」找文件。它的触发条件是模块实例化，服务对象是模块名表，对 import 语句完全不敏感。-I 则是反引号 `include 的头文件搜索路径，解决的是文本包含，同样不建立包条目。

3.2 实测：加 -y 后三条错误原样保留 ​

把搜索目录加上再跑一次，输出与第一步逐字相同，仍然是 3 errors、退出码 1：

exp-log
--- 2. -y module search dir does not resolve packages ---
$ verilator --lint-only -y rtl rtl/top.sv
%Error-PKGNODECL: rtl/top.sv:2:10: Package/class 'iopkg' not found, and needs to be predeclared (IEEE 1800-2017 26.3)
    2 |   import iopkg::*;
      |          ^~~~~
%Error: rtl/top.sv:2:10: Importing from missing package 'iopkg'
    2 |   import iopkg::*;
      |          ^~~~~
%Error: rtl/top.sv:3:12: syntax error, unexpected IDENTIFIER, expecting ',' or ';'
    3 |   var op_t op = OP_ADD;
      |            ^~
%Error: Exiting due to 3 error(s)
exit code: 1

这一步的价值是排除法：目录参数没有改变任何诊断，说明问题不在「编译器找不到目录」，而在「这种引用关系压根不走目录搜索」。

3.3 与普通 module 找不到文件的报错差异 ​

普通子模块漏列文件时，Verilator 的报错是 %Error: Cannot find file containing module: 'xxx'，并附带 Looked at、Looked in 清单，告诉你它试过哪些文件名和目录；这种情况下补 -y 加 +libext+.sv+.v 确实可能救回来。而 package 缺失走的是 PKGNODECL 通道，关键词是 Package/class、predeclared、Importing from missing package，没有任何「看过哪些目录」的提示——因为编译器根本没有启动目录搜索。两类报错的完整对照与 -y/-I 适用边界，见 Verilator %Error Cannot find file containing module：找不到模块文件排查。记住一个判据：报错名里带 PKG 或 Importing，就不要再试搜索目录参数。

四、排查清单：先核对文件清单，再看顺序与拼写 ​

eda/ts-verilator-package-import-not-found.md D2 示意图

图中红色是故障与弯路，蓝色是信息收集，灰色是判定点，橙色是修复动作，绿色是闭环。对照这张图，落地清单如下：

  • 先数命令行上的源文件：确认定义 package 的 .sv 是否真的作为位置参数传给了 verilator；用通配符 rtl/*.sv 时确认 shell 展开顺序，不要想当然。
  • 确认编译顺序：Verilator 按命令行顺序读文件，package 文件必须排在所有 import 它的文件之前；包之间有依赖时，被依赖的包更靠前。
  • 核对包名拼写与文件内容：文件名和 package 名不需要一致，但 import iopkg::* 里的名字必须与 package iopkg 严格一致，大小写敏感。
  • 放弃目录参数幻想：-y、+libext+、-I 都不会让 package 可见，看到 PKGNODECL 直接回到文件清单上找原因。
  • 工程化固定清单：文件一多就把全部源文件按顺序写进 .f 文件清单，用 verilator --lint-only -f files.f 调用，避免手工命令漏文件；这也能防止后续新增 package 时重蹈覆辙。

失败路径与修复路径在同一次运行里顺序执行，终端记录如下：

漏列 package 文件三连报错，补列后退出码 0 的对照记录

五、修复命令与复跑确认 ​

修复不需要改一个字的 RTL，只调整编译命令：把 rtl/iopkg.sv 显式补上，并且放在 rtl/top.sv 前面。

bash
verilator --lint-only rtl/iopkg.sv rtl/top.sv

第三步复跑的输出干净利落，没有任何诊断，进程以退出码 0 结束：

exp-log
--- 3. fixed: list iopkg.sv before top.sv on the command line ---
$ verilator --lint-only rtl/iopkg.sv rtl/top.sv
exit code: 0

判定修复成立要看两个证据。其一，退出码为 0，且第一步里的三条错误全部消失——包括第 3 行那条 syntax error，证明它确实是缺包导致的级联而非独立语法问题；其二，整条命令没有借助 -y 或 -I，说明可见性完全来自显式列入的 package 文件，机制理解与修复手段一致。如果工程里有多个 package，按依赖顺序全部列在使用者文件之前，或统一收进 .f 清单管理。

实验环境 ​

  • 机器/系统：macOS 宿主机启动 Docker 容器，容器内为 Debian bookworm
  • 工具版本：Verilator 5.020，镜像 geek-eda:0.2
  • 日期：2026-11-11
  • 完整命令：在实验目录执行 docker run --rm -v "$PWD":/work -w /work/ts-verilator-package-import-not-found geek-eda:0.2 bash run.sh，脚本依次运行三条 verilator --lint-only 命令并打印各自退出码。

代码获取 ​

完整源码与复现脚本位于公开仓 https://github.com/derekzhuo/geek-doc.cn/tree/main/experiments/ts-verilator-package-import-not-found，含 rtl/iopkg.sv、rtl/top.sv 与 run.sh。本地装有 Docker 并取得 geek-eda:0.2 镜像后，在该目录执行 bash run.sh 即可原样复现「漏列报错、-y 无效、补列通过」三步运行。

这一篇在知识体系里的位置 ​

本篇属于 开源 EDA 报错排查导航 的 Verilator 编译输入分支，回答「package 文件就在目录里为什么编译器看不见」。同簇的 Verilator %Error Cannot find file containing module：找不到模块文件排查 处理普通 module 漏列的场景，与本文构成「模块名表与包名表」两条解析通道的对照；全系列入口见 EDA 报错排查系列。

总结 ​

Verilator 找不到 SV package 定义文件，本质是编译输入不全而不是路径配置错误：package 只有被显式读入才会登记进全局包名表，命令行漏列 iopkg.sv 时，import iopkg::* 查表失败，Verilator 5.020 抛出 PKGNODECL、缺失包导入和一条级联 syntax error 共三条诊断后以退出码 1 中止。-y 搜索目录只在 module 实例化未解析时按模块名找文件，对 package 通道没有任何贡献，加上后报错逐字不变。修复方式是把 package 文件显式列进命令行并置于使用者之前，verilator --lint-only rtl/iopkg.sv rtl/top.sv 复跑退出码 0，三条错误同步消失；多文件工程用 .f 清单固定顺序即可避免复发。