ucs_logviewer

浏览工程目录、搜索文件与内容、并排查看多种文件、定位行号和跟踪运行日志的完整用户指南

Program

ucs_logviewer

Release

UCS-1.1.1 · 2026-07-25

Interface

原生桌面界面，不启动 HTTP 服务，不依赖浏览器

Input

一个 root directory；可在启动时打开一个或多个文件

Search

Glob、Find、Content、In File、In Page

License

启动时检查 UCS license；debug level 受 license 限制

Support

support@universalchipstudio.com

1. Quick Start

# 以一个工程目录为可见范围
./ucs_logviewer --root /proj/chip/run_001

# 启动时打开一个文件并定位到第 850 行
./ucs_logviewer \
  --root /proj/chip/run_001 \
  --open logs/place_opt.log \
  --line 850

# 启动时并排打开多个文件；--open 可以重复
./ucs_logviewer --root /proj/chip/run_001 \
  --open reports/setup.rpt.gz \
  --open reports/hold.rpt.gz \
  --open reports/qor.csv

2. 界面结构

1. 左侧选择 Content，输入正则 ERROR|WARNING，结果按文件、行号和摘要列出。
2. 点击第 1 条结果后，右侧自动打开对应文件、跳到第 4 行，并以黄色高亮命中行。
3. 顶部行号框同步显示 4；底部状态栏显示规范化文件路径和行号。

3. Browse 与 Root

3.1 进入和返回目录

1. 双击带 [DIR] 的行进入目录；指向目录的 symlink 也可双击进入。
2. 点击 Up 返回父目录。到达 root 后继续点击不会越过 root。
3. 点击 Refresh 重新读取当前目录，适合 run 正在产生新文件的场景。
4. 勾选 Hidden 后显示以点开头的文件和目录；搜索也会按相同设置决定是否进入隐藏目录。

3.2 更换 Root

点击 Choose Root，选择一个存在且可读的目录。程序会 canonicalize 路径并验证目录可访问；选择 / 不会重启程序，但会把整个本机文件系统设为搜索范围，通常不建议这样做。

4. 五种搜索模式

Case sensitive 未勾选时，glob 与正则均不区分大小写。Content / In File / In Page 的 pattern 是正则，不是普通字符串。

4.1 文件名搜索案例

# 当前目录下所有压缩报告
Mode = Glob
Pattern = *.rpt.gz

# 递归找所有 setup/hold 报告
Mode = Find
Pattern = *setup*.rpt*

# 根据相对路径找 reports 子树中的文件
Mode = Find
Pattern = reports/**/*.log

4.2 内容搜索案例

# 递归找 ERROR 或 FATAL
Mode = Content
Pattern = \b(ERROR|FATAL)\b

# 查找小于 0 的 slack 行
Mode = Content
Pattern = ^\s*slack\b.*-\d

# active file 内动态搜索 startpoint
Mode = In File
Pattern = ^Startpoint:

Content search 内置读取普通文本、.gz、.bz2 和 .xz；不需要外部解压命令。遇到二进制 NUL 字节时停止读取该文件，避免把二进制误当文本。

4.3 从结果跳到命中行

1. 点击一条带行号的结果，程序打开对应文件并高亮该行。
2. 文件已打开时直接切换 active pane，不重复构造 preview。
3. 双击单条带行号的结果可另外打开前后各 10 行的 context 窗口。
4. 多选来自不同文件的结果后，双击或点击 Open Selected 可并排查看这些文件。

5. 同时打开多个文件

1. 在 Directory 或 Search Results 中选择多个文件。
2. 点击 Open Selected。重复路径会自动去重。
3. Workspace 根据文件数自动等分为 grid；内容超过窗口高度时出现 workspace 纵向滚动条。
4. 单击 pane 标题把它设为 active，Go to line、Tail、Copy Path、Export、Edit 都作用于 active file。
5. 双击 pane 标题临时最大化；再次双击恢复全部 pane。

程序最多缓存 24 个 preview。再次打开尺寸相同的近期文件时可复用缓存；切换普通文本且语法类型相同时也会复用单一文本 pane，减少重新建 UI 的等待。

1. 每个 pane 都有独立标题、滚动条和文本导航；点击标题即可切换 active file。
2. Tcl pane 自动显示关键字、字符串、变量和注释高亮。
3. 空白区域只用于补齐规则 grid；双击任一标题可临时最大化该文件，再次双击恢复。

6. 文本浏览、Page Mode 与高亮

6.1 Scroll Mode

默认显示完整 preview 内容，可以连续滚动。In Page 在 Scroll Mode 下搜索当前已加载的全文。

6.2 Page Mode

1. 点击 Mode: Scroll 切换为 Mode: Page。
2. 使用 First、Prev、Next、Last 翻页。
3. 页大小可选 50、100、200、500 行。
4. Page 信息显示当前页、总页数和当前行范围。
5. In Page 只搜索当前页的行范围；换页后再次搜索即可得到新页结果。

6.3 Go to line

输入一条从 1 开始的行号并点击 Go to line。Scroll Mode 将目标行放到视图中部附近；Page Mode 自动切到包含该行的页并高亮该行。Content 搜索结果也使用同一定位逻辑。

6.4 自动语法高亮

根据文件扩展名或 shebang 识别并高亮关键字、字符串、注释、数字和变量。支持 Tcl/SDC/UPF、Perl、Python、Shell、Verilog/SystemVerilog、Rust、C/C++/Java/JavaScript/TypeScript/Go、JSON、HTML/XML/SVG、YAML 和 Makefile。压缩后缀会先移除，因此 flow.tcl.gz 仍按 Tcl 显示。

7. 文件格式与静态预览

HTML 的相对 stylesheet、image 和 hyperlink 以 HTML 文件所在目录解析，并且必须留在 root 内。外部 HTTP/HTTPS 链接保持链接形式，但预览是静态的；不会运行页面脚本。

1. 上方显示 Prev、Next、页码输入、Go 和当前页数。
2. 单页与多页文件使用相同界面；多页文件可顺序翻页，也可输入页码直达。
3. 转换结果以矢量页面显示，适合检查 floorplan、框图和带尺寸标注的图纸。

8. Live Tail

1. 打开一个正在增长的 log，使它成为 active file。
2. 点击 Live Tail。程序立即读取最后若干行，并按配置周期刷新。
3. Tail 激活后文本自动回到 Scroll Mode 并滚动到末尾。
4. 再次点击 Live Tail 停止刷新。

默认显示最后 200 行，每 3 秒刷新。普通文件从文件尾部读取；压缩文本需要解压已加载范围，因此更适合已完成报告，不建议对仍在写入的压缩文件做实时 Tail。

9. Copy、Export、Edit 与 ZIP

10. Configuration

--config 接受 strict JSON：未知字段会报错。CLI 的 --root 优先于 JSON 中的 root。

{
  "root": "/proj/chip/run_001",
  "show_hidden": false,
  "preview_max_bytes": 33554432,
  "search_max_results": 10000,
  "tail_lines": 500,
  "tail_refresh_seconds": 2
}

11. Command-Line Reference

Usage: ucs_logviewer [OPTIONS]

Options:
      --root <DIRECTORY>  Root directory available in the browser
      --open <FILE>       File to open at startup; repeatable
      --line <NUMBER>     One-based line after opening a text file
      --config <JSON>     Strict JSON configuration file
      --debug <0-4>      Requested debug level [default: 0]
  -h, --help
  -V, --version

--line 必须与至少一个 --open 同时使用。兼容 -debug N 拼写。相对 --open 路径以最终 root 为基准。

11.1 Debug 与日志

日志依次尝试写入 $UCS_LOG_DIR、启动时当前目录、系统临时目录；文件名为 ucs_logviewer_YYYYMMDD_HHMMSS_PID.log。Debug level 3 会在日志目录的 debug/run_.../ 下写 effective config、目录项和搜索结果等诊断材料。

12. 完整使用案例

12.1 查找所有严重 timing violation

1. Root 选择当前 STA run。
2. 进入 reports 的共同父目录。
3. Content 输入 ^\s*slack\b.*-\d，点击 Search。
4. 勾选需要比较的多个报告结果，点击 Open Selected。
5. 点击各 pane 标题切换 active，再用 Go to line 或 In File 缩小范围。

12.2 对比三个阶段的 QoR CSV

./ucs_logviewer --root /proj/chip \
  --open create_db/qor.csv \
  --open place_opt/qor.csv \
  --open route_opt/qor.csv

三个 CSV 以等分 pane 显示；双击某一 pane 标题可以临时最大化检查长表。

12.3 跟踪 PnR run log

./ucs_logviewer --root /proj/chip/run_001 \
  --open logs/route_opt.log

启动后点击 Live Tail；需要检查已有 ERROR 时切换 In File，输入 \b(ERROR|FATAL)\b，结果会随输入动态出现。完成搜索后可重新打开 Live Tail。

12.4 查看报告包而不解压到项目

直接打开 .zip 或 .tar.gz，在 archive member 列表中选择 HTML、CSV、图片或文本成员预览。程序不会把成员写回项目目录。

12.5 打开多页 VSD floorplan

./ucs_logviewer --root /proj/chip \
  --open docs/floorplan_review.vsd

打开后页面保持矢量清晰度。使用 Prev / Next 顺序浏览，或在页码框中输入目标页并点击 Go。VSD 转换在本机进程内完成，不上传文件，也不调用客户环境中的外部应用。

13. Troubleshooting