KLayout DRC 脚本报错:SyntaxError、NoMethodError 与空 layer 静默零结果的批处理排查
更新时间:2026-11-20。长尾排查篇,属于 EDA 报错排查系列,汇总入口见 开源 EDA 报错排查导航。KLayout 的 DRC deck(设计规则检查脚本)本质是一段 Ruby 代码,既可能在语法解析阶段就失败,也可能跑到一半才报未定义方法;还有一种更隐蔽的情况:脚本引用了版图里根本不存在的 layer,进程退出码却是 0,只留下一份零结果报告。本文用四个最小 deck 把三类现象一次跑透。
首屏答案:report( 缺右括号属于 Ruby 语法错误,KLayout 在执行任何 DRC 操作前的解析期就抛 SyntaxError,报错直接给出文件名与行号;把 width 拼写成 wdith 语法上合法,但 DRC 解释器执行到该行时在 DRC::DRCLayer 对象上找不到这个方法,抛 NoMethodError,且因为报告数据库已经打开,磁盘上会留下一个 384 字节的不完整 .lyrdb;而引用不存在的 input(99, 0) 既不报错也退出码 0,只产出 501 字节的空报告——所以退出码 0 不等于 DRC 真的检查过图形,必须再核对报告数据库的体积与条目数。
这张流程卡对应本文的排查顺序:先用批处理模式拿到带行号的确定性报错,再按异常属于解析期还是执行期分流处理,最后即使退出码为 0 也要检查磁盘上的报告数据库。跳过最后一步,正是空 layer 静默零结果坑埋人的地方。
本文要回答的问题
- 同一个 KLayout 批处理入口下,
SyntaxError与NoMethodError的完整报错原文分别是什么,各自卡在哪个阶段? - 报错栈里的
drc_interpreters.lym:31是什么帧,为什么真正要改的是 deck 文件的第 4 行? - 为什么方法名拼错后磁盘上会多出一个不完整的
.lyrdb,它能不能当作检查结果使用? - deck 引用版图中不存在的 layer 时,KLayout 为什么退出码仍是 0,怎样用报告数据库体积识破静默零结果?
- 日常调试 DRC deck 时,
klayout -b -r批处理模式相对 Macro Editor 图形界面有什么优势?
一、完整报错原文:两类硬失败的真实输出
实验先用一段 Ruby 脚本 make_gds.rb 生成最小输入版图 demo.gds:一个 TOP 单元,layer 1、datatype 0 上有一个 1 微米乘 2 微米的矩形,数据库单位 dbu 为 1 纳米。四个 deck 都拿这同一个 GDS2 跑,变量只有脚本本身。
第一个坏 deck drc_bad_syntax.drc 故意让 report( 调用缺少右括号,全文只有两个有效行:
# Intentionally broken: the report() call misses its closing parenthesis,
# so the Ruby parser fails before any DRC operation runs.
report("demo DRC"
input(1, 0).width(10.um).output("w10")第二个坏 deck drc_bad_method.drc 语法完整,但把宽度检查方法 width 拼成了 wdith:
# Intentionally broken: width() is misspelled as wdith(), which is an
# undefined method on DRCLayer and raises NoMethodError at execute time.
report("demo DRC", "drc_bad_method.lyrdb")
input(1, 0).wdith(10.um).output("w10")在容器里执行 bash run.sh,两个失败 case 的日志原样摘录如下,未作润色:
读这段输出抓住两条主线。第一条是 drc_bad_syntax.drc:4: syntax error, unexpected local variable or method, expecting ')':Ruby 解析器读到第 4 行时期待一个右括号却遇到了下一个语句,它甚至把出错的源码行和 ^~~~~ 指示符一起打了出来,这类错误发生在任何 DRC 操作执行之前,属于解析期失败。第二条是 undefined method 'wdith' for #<DRC::DRCLayer...>:脚本语法完全合法,解释器已经开始执行,直到第 4 行对图层对象调用一个不存在的方法才抛出 NoMethodError,属于执行期失败。两个 case 的退出码都是 1。
栈帧里反复出现的 :/built-in-macros/drc_interpreters.lym:31:in 'instance_eval' 是 KLayout 自带的 DRC 解释器宏,属于框架代码;真正可操作的帧是 drc_bad_method.drc:4:in 'execute'——它把问题精确指回你自己 deck 的第 4 行。调试时盯住带自己文件名的帧即可,内置宏帧不用改也改不到。商用工具里同类「解析器先行、语法不过根本不进检查」的行为可对照 Calibre 语法解析错误排查。
二、工具与版本
本次实验全部在容器内以 KLayout 无头批处理模式完成,版本与日志头部逐字一致:
- 运行环境:Docker 镜像
geek-eda:0.5-asic,底层 Ubuntu 24.04 - 工具版本:KLayout 0.28.16,
klayout -v输出首行即TOOL_VERSION: KLayout 0.28.16 - 批处理入口:
klayout -b -r <deck>.drc demo.gds,其中-b是无头后台模式,-r指定要执行的 Ruby 宏脚本 - 运行日期:2026-11-20
版本要先固定,因为异常类名、栈帧格式和 .lyrdb 报告数据库的内部结构都随 KLayout 版本演进。本文的报错文案与文件体积只对 0.28.16 这个构建负责;换到大版本不同的环境时,应保留当次完整输出再对照,不能凭本文文案反推。
KLayout 自带的 Macro Editor(宏编辑器)是一个带语法高亮和运行按钮的图形界面,适合交互式开发;但排查报错时更推荐 klayout -b -r 批处理模式:报错直接进终端、退出码可被 shell 脚本捕获、同一份命令可以在容器或持续集成里原样复跑,不依赖显示器和鼠标点击。
三、根本原因:一套 Ruby 解释器,两种失败时机
3.1 解析期与执行期:为什么报错长相完全不同
KLayout 的 DRC deck 不是自定义声明式格式,而是嵌入在 Ruby 里的领域特定语言(DSL,Domain-Specific Language):input、width、output、report 都是方法调用,10.um 是 KLayout 给数值类补上的单位转换方法。这带来一个直接推论——deck 要先像普通 Ruby 程序一样通过语法解析,才谈得上执行。
缺右括号的 deck 倒在第一关。Ruby 解析器看到 report("demo DRC" 之后语句没有闭合,解析整个中断,KLayout 把它包装成 ERROR: SyntaxError 打出。此时报告数据库还没创建,磁盘上不会留下任何 .lyrdb 残骸。
拼错方法名的 deck 倒在第二关。wdith 在 Ruby 语法里是一个合法的消息发送,解析器挑不出毛病;直到解释器真正对 DRC::DRCLayer 图层对象发送 wdith 消息,对象查无此方法,才抛出 NoMethodError。关键区别在这里:report 语句已经执行完毕,报告数据库文件已经打开并写入了头部,异常中断后续写入后,磁盘上留下一个 384 字节的不完整 drc_bad_method.lyrdb。它是事故残骸,不是检查结果,不能拿来做签核依据,应当删除后重跑。
3.2 更隐蔽的第三类:退出码 0 的静默零结果
第三个 deck drc_empty_layer.drc 把输入换成版图里不存在的 layer 99、datatype 0:
# Silent-pitfall probe: layer 99/0 does not exist in demo.gds. KLayout
# treats an empty input as a legal DRC run with zero results, so this
# deck exits 0 and writes an empty report database.
report("demo DRC empty-layer probe", "drc_empty_layer.lyrdb")
input(99, 0).width(10.um).output("w10")KLayout 对「空输入」的语义是合法的:版图里没有这个 layer,等价于拿到一个空图形集合,对空集合做宽度检查自然得到零条违规,整个脚本正常跑完,退出码 0,还一本正经地写出了 501 字节的 drc_empty_layer.lyrdb。layer 编号与 datatype 在 GDS2 里只是一对整数索引,拼错编号不会触发任何异常,这套编号机制见 GDS2 layer 与 datatype 编号映射。
这就是本篇最容易被自动化流程吞掉的坑:脚本只判断退出码就会宣布 DRC 通过,实际上一条图形都没检查。识破办法是把「报告数据库非空且条目数符合预期」加进复核动作——本次实验里正常 deck 产出的 drc_good.lyrdb 是 930 字节,空 layer 探针只有 501 字节,体积差异在 ls -l 清单里一目了然;正式流程里还可以用 KLayout 的报告 API 读取数据库条目数,对「输入图形总数为 0」直接告警。
三类现象的对照如下:
| deck | 失败阶段 | 异常/现象 | 退出码 | 磁盘产物 |
|---|---|---|---|---|
| drc_bad_syntax | Ruby 解析期 | SyntaxError,提示缺 ) | 1 | 无 lyrdb |
| drc_bad_method | DRC 执行期 | NoMethodError,无 wdith 方法 | 1 | 384 字节不完整 lyrdb |
| drc_empty_layer | 不失败 | 空集合检查,零结果 | 0 | 501 字节空 lyrdb |
| drc_good | 正常执行 | 宽度检查落库 | 0 | 930 字节正常 lyrdb |
四、排查清单:按异常类型分流,按产物收口
排查按五步走,顺序不要反:
- 先固定批处理入口复现:用
klayout -b -r deck.drc demo.gds在终端重跑,拿到带文件名和行号的完整报错;只在 Macro Editor 弹窗里看错误摘要,容易丢掉栈帧。 - 看到 SyntaxError 就查语法结构:重点核对括号配对、
do/end与花括号闭合、字符串引号、逗号分隔。报错行号指向解析器察觉异常的位置,真正的漏写点有时在上一行末尾。 - 看到 NoMethodError 就查方法名与接收者:先确认方法拼写(
width不是wdith),再确认调用对象类型——同名方法在DRCLayer和Region上的可用集合不同,对象类型不对也会报同样的错。 - 忽略内置宏栈帧,盯住自己的 deck 帧:
drc_interpreters.lym是框架代码,栈里你的deck.drc:行号那一帧才是修改点。 - 退出码 0 后再核报告数据库:检查
.lyrdb是否存在、体积是否明显大于空报告、条目数是否与输入图形规模相称;发现异常的零结果,回头核对input(layer, datatype)编号与版图实际层别。
五、修复代码与复跑确认
两处硬失败都是单行级修复。语法 case 给 report 补上右括号和报告文件名;方法 case 把 wdith 改回 width。修好的 deck 与仓内合法基准 drc_good.drc 完全同构:
# Healthy deck: width check on the real layer, report database written
# next to the deck so the run leaves an inspectable artifact.
report("demo DRC", "drc_good.lyrdb")
input(1, 0).width(10.um).output("w10")修复后整组重跑,两个静默 case 的退出码与磁盘清单如下:
drc_empty_layer 与 drc_good 的退出码都是 0,差异只在产物:空 layer 探针留下 501 字节的空报告,合法 deck 留下 930 字节、含真实检查结果的报告,而执行期失败 case 还残着那个 384 字节的不完整文件。三个数字放在一起,正好对应「残骸、空转、正常」三种状态。复跑确认的完整动作因此是:退出码为 0、报错流中无 ERROR: 行、.lyrdb 体积与条目数符合预期,三者同时成立才算闭环。开源流程里 DRC 违规本身的解读与修图方法,可参考 OpenLane 与 Magic 的 DRC 报错处理。
实验环境
- 机器/系统:Docker 容器
geek-eda:0.5-asic,底层 Ubuntu 24.04,KLayout 无头批处理模式 - 工具版本:KLayout 0.28.16
- 日期:2026-11-20
- 完整命令:在实验目录执行
bash run.sh;脚本先运行klayout -b -r make_gds.rb生成demo.gds,再依次执行klayout -b -r drc_bad_syntax.drc demo.gds、klayout -b -r drc_bad_method.drc demo.gds、klayout -b -r drc_empty_layer.drc demo.gds、klayout -b -r drc_good.drc demo.gds,逐组打印退出码,最后ls -l ./*.lyrdb列出全部报告数据库。
代码获取
完整 deck、版图生成脚本与复现脚本位于公开仓:https://github.com/derekzhuo/geek-doc.cn/tree/main/experiments/klayout-drc-script-macro-error,含 make_gds.rb、四个 .drc、run.sh 与 README。在装有 Docker 的机器上拉取该目录后,一条命令即可原样复现五组运行:
docker run --rm -v "$PWD":/work -w /work geek-eda:0.5-asic bash -lc 'bash run.sh'本机已装 KLayout 0.28 时,也可以直接在该目录执行 bash run.sh。
这一篇在知识体系里的位置
本篇属于 开源 EDA 报错排查导航 的 KLayout 分支,回答「DRC deck 抛异常或静默零结果时怎样定位与收口」。语言层面的解析期/执行期之分与 Calibre 语法解析错误排查 互为对照,一篇讲商用规则检查器、一篇讲开源 Ruby DSL;空 layer 坑涉及的编号语义在 GDS2 layer 与 datatype 编号映射 展开;检查出违规之后怎样改版图,承接 OpenLane 与 Magic 的 DRC 报错处理。
总结
KLayout DRC 脚本报错分三个层次理解:缺右括号这类语法问题在 Ruby 解析期就抛 SyntaxError 并给出 deck 行号,不留任何产物;width 拼成 wdith 这类问题语法合法、执行期才在 DRC::DRCLayer 对象上抛 NoMethodError,栈帧里只盯自己 deck 的行号、忽略内置解释器帧,并要删掉残留的 384 字节不完整 lyrdb;引用不存在的 input(99, 0) 则既不报错又退出码 0,只产出 501 字节空报告,所以退出码 0 永远不是充分条件——用 klayout -b -r 批处理模式拿到确定性报错、按异常类型分流修复、再以 930 字节正常报告为基准核对 lyrdb 体积与条目数,三步齐备才算一次真正通过的 DRC 运行。