极客工场

Appearance

共 2,802 字预计阅读约 9 分钟

Vivado 依赖缺失速查：系统库没装、子模块没拉与私有 IP 源找不到怎么办 ​

更新时间：2026-10-22。FAQ 速查页，属于 FPGA 工具报错排错系列。Vivado 依赖缺失最迷惑人的地方在于，报错里出现的都是「not found / cannot open / missing」，但缺的东西分属四个完全不同的层次：操作系统的共享库（Linux 启动阶段就挂）、Vivado 自身的版本与器件/板卡支持库（选 part、打开 IP 时挂）、git 子模块形式随工程分发的 IP 源码（clone 后目录是空的）、以及团队私有 IP 仓库与板卡板件 board_files（别人机器上好好的，你的 IP catalog 里没有）。四层依赖的安装动作一个都不能互换，本篇以真实报错文案为锚做一次分流。版本不兼容方向的姊妹篇见 Vivado 版本不兼容速查，IP 的常规用法见 FPGA 入门 29：IP 核怎么调。

本文要回答的问题 ​

  1. Linux 下启动 Vivado 报 libncurses.so.5: cannot open shared object file，缺的是 Vivado 还是系统包？
  2. 打开工程报某个 IP could not be found in IP catalog，是没装 Vivado 还是没配仓库？
  3. git clone 下来的工程 ip_repo/ 目录是空的，综合全挂，缺的文件去哪了？
  4. 板卡下拉框里选不到同事用的那块板子，board part not found 缺的是什么？
  5. 私有 IP 和板卡文件在团队里怎么随工程分发，才能做到新人 clone 即可综合？

一、报错原文与典型现象 ​

以下路径与工程名均为占位（D:/proj/demo、demo_top），不确定的报错编号统一以 [IP_Flow 19-xxxx] 形式占位。

1. 操作系统共享库缺失——Vivado 本体启动不了。 Linux 新装机器上最常见，安装器能跑完，首次启动或编译仿真库时报：

bash
# 启动 vivado 或加载其自带组件时：
./vivado: error while loading shared libraries: libncurses.so.5:
cannot open shared object file: No such file or directory
# 另一类高发：编译器运行时版本太旧
libstdc++.so.6: version `GLIBCXX_3.4.xx' not found
(required by /tools/Xilinx/Vivado/2023.2/lib/lnx64.o/libxxx.so)

这类错误在 Vivado 打印自己的 banner 之前就由操作系统动态链接器（ld.so）抛出，与工程、IP、授权都无关，缺的是发行版的 32/64 位兼容包。

2. 版本要求不满足或产品库未安装——Vivado 能开，但 IP/器件打不开。

text
[IP_Flow 19-xxxx] IP 'xxx_0' could not be found in the IP catalog.
The IP definition for 'xxx:1.0' was not found in the IP repositories.
[Board 19-xx] Board part not found: xilinx.com:myvendor:myboard:part0:1.x
[Common 17-xxx] The board_part definition was not found for
'xilinx.com:myvendor:myboard:part0:1.x'.

前者可能是 IP 由更新版本 Vivado 生成（此时报的是版本不兼容，分流见 Vivado 版本不兼容速查），也可能是该 IP 所在的仓库根本没在这台机器上配置；后者明确是板卡板件（board_files）没装——Vivado 只自带官方开发板的板件文件，第三方或自研板要单独安装。

3. git 子模块未拉取——clone 之后目录是空的。

text
ERROR: [Common 17-xxx] ... no such file or directory:
D:/proj/demo/ip_repo/vendor_pkg/hdl/vendor_pkg.v
ERROR: [IP_Flow 19-xxxx] Unable to find IP custom IP referenced by
project 'demo_top': D:/proj/demo/ip_repo/sub_ips/xxx.xci

此时去文件管理器看，ip_repo/sub_ips/ 目录存在但里面什么都没有。这是 git 子模块（submodule）的标志性现象：主仓库只记录了一个指向子仓库的「指针」，普通 git clone 不会把内容拉下来。

4. 私有 IP 源 / 板件仓库路径未配置——别人能找到，你找不到。

bash
WARNING: [IP_Flow 19-xxxx] IP definition 'xxx 1.0' not found in
the IP catalog. Verify the IP repository exists and is accessible.
# 或 build.tcl 里已有配置但没刷新目录：
set_property ip_repo_paths D:/proj/demo/ip_repo [current_project]
# 若没有紧跟 update_ip_catalog，catalog 里仍看不到核

仓库文件在本机存在、Vivado 版本也对，但 ip_repo_paths 这个工程属性没指过去（或指了之后没执行 update_ip_catalog 刷新），IP catalog 就不会扫描它。板件同理，靠 board_repo_paths 指向 board_files 目录。

二、现象 → 病因 → 处置速查表 ​

报错现象缺的是哪一层一判据处置方向
libncurses.so.5/libtinfo.so.5 找不到系统共享库启动前即报，ld.so 抛错装发行版兼容包（Ubuntu 系 libncurses5/ libtinfo5，RHEL 系 ncurses-compat-libs），32 位包一并装
GLIBCXX_3.4.xx not found系统运行时版本机器自带 gcc 比 Vivado 要求旧按 Vivado 版本发行说明升级/补装 libstdc++，勿手工替换系统库
IP not found in IP catalog，版本号更新Vivado 版本/产品库该核由更新版本生成走版本兼容通道，见 Vivado 版本不兼容速查
IP not found，但工程用私有核IP 仓库路径别人工程正常、你本机 catalog 没有set_property ip_repo_paths 指对目录后 update_ip_catalog
Board part 下拉为空 / board part not foundboard_files 板件第三方或自研板，官方库不含向板厂索取板件包，配置 board_repo_paths 后重启 Vivado
ip_repo/xxx/ 目录存在但为空git 子模块git submodule status 行首是 -git submodule update --init --recursive 后重开工程
综合报私有核 .xci 不存在子模块或 IP 生成物仓库里只有空目录或缺 .xci先拉子模块，再 generate_target all 重生成
配置了路径仍找不到核catalog 未刷新Tcl 设了属性没 update执行 update_ip_catalog，GUI 里在 IP Catalog 右键 Refresh
私有核可以加载但综合报授权核依赖付费特性报 license checkout 类信息授权问题另走 Vivado license 取不出来速查
仿真报 xsim.dir 下库缺失编译仿真库切换过 Vivado 版本或工具链用对应版本重编译仿真库，旧产物目录清掉

三、排查决策树 ​

分诊只做两件事：看报错抛出的位置（启动前、开工程时、综合时），再看缺的东西属于四层中的哪一层。下图颜色含义：红=报错入口与命中的根因层，蓝=分诊动作，橙边上的文字=对应修复动作，绿=流程恢复。

d2
direction: down
entry: "Vivado 报依赖缺失\nnot found / cannot open / missing"
classify: "看报错抛出位置与缺失对象\n启动前 / 选器件 / 开工程 / 综合时"
syspkg: "系统共享库缺失\nld.so 在启动前抛 libxxx.so"
verlib: "版本与板件库不满足\nIP catalog 或 board part 找不到"
submod: "git 子模块未拉\nip_repo 目录为空"
repopath: "私有 IP 源未配置\nip_repo_paths / board_repo_paths"
pass: "重开工程并重新生成 target\n综合实现通过"

entry -> classify
classify -> syspkg: "启动前 ld.so 抛错"
classify -> verlib: "选 part/板卡或打开 IP 时"
classify -> submod: "目录存在但内容为空"
classify -> repopath: "文件在本机但 catalog 没有"
syspkg -> pass: "装齐发行版兼容包"
verlib -> pass: "装达标版本或板件包"
submod -> pass: "submodule update --init"
repopath -> pass: "配仓库路径并 update_ip_catalog"

syspkg -> pass.style.stroke: "#E08A1E"
verlib -> pass.style.stroke: "#E08A1E"
submod -> pass.style.stroke: "#E08A1E"
repopath -> pass.style.stroke: "#E08A1E"

entry.style: { fill: "#FDECEC"; stroke: "#D9534F" }
classify.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
syspkg.style: { fill: "#FDECEC"; stroke: "#D9534F" }
verlib.style: { fill: "#FDECEC"; stroke: "#D9534F" }
submod.style: { fill: "#FDECEC"; stroke: "#D9534F" }
repopath.style: { fill: "#FDECEC"; stroke: "#D9534F" }
pass.style: { fill: "#E9F8F0"; stroke: "#2E9E6B" }

读这张图抓住一个分叉：四层根因互不相通——系统库问题在 Vivado 之外解决，apt/yum 装包即可，重装 Vivado 十遍也没用；子模块没拉时配 ip_repo_paths 只是把空目录指给工具；仓库路径没配时去升级 Vivado 版本同样南辕北辙。任何一条橙色修复做完，都要回到绿色节点：重开工程、generate_target all 重生成产物，再跑一次完整综合确认闭环，不要修一半就继续往下走。

四、逐条排查展开 ​

系统共享库：照 Vivado 发行说明装包，不要手工拷 so。 每个 Vivado 版本的安装许可与发行说明（Release Notes 的 Required Environments 一节）列了支持的发行版与依赖包清单，新机器上先照单装齐再启动。Ubuntu 系高发的是 libncurses5、libtinfo5 及其 32 位变体，RHEL/CentOS 系是 ncurses-compat-libs、libstdc++ 等；报 GLIBCXX 版本不够，说明系统 libstdc++ 旧于该 Vivado 的编译基线，按发行版升级工具链运行时包。切忌从网上单独下载 .so 文件扔进系统库目录——会污染动态链接环境，后续引发更难查的崩溃。排查时 ldd <报错的可执行或 so> 可以列出它到底找不到哪一个库。

版本与板件库：先确认 IP 是「版本不够」还是「仓库没配」。 报 IP not found 时先在 IP Sources 视图看该核来源：核名属于 Vivado 自带目录（如 fifo_generator、blk_mem_gen）却找不到，是安装或版本问题，按 Vivado 版本不兼容速查 分流；核名是团队自定义的，则进下面的仓库通道。板卡侧，Vivado 只内置官方开发板的 board_files，第三方与自研板要把板厂提供的板件包解压到本地，在 Settings→Board Repository 或 Tcl 里配置 board_repo_paths，重启后下拉框才会出现该板。管脚约束的背景见 板级约束落地。

git 子模块：一条命令补齐，递归不能漏。 私有 IP 以子模块形式分发时，正确的拉取方式是：

bash
# 首次克隆一条命令到位：
git clone --recurse-submodules <repo-url> D:/proj/demo
# 已经 clone 完才发现空目录，事后补齐：
cd D:/proj/demo
git submodule update --init --recursive
git submodule status        # 行首是空格或 + 才算已检出，行首 - 仍是空

子模块还嵌套子模块时必须带 --recursive，否则只补齐第一层。拉完后重开工程，让 Vivado 重新解析 .xci；若核是以 RTL 形式提供的封装 IP，还需在仓库目录上执行一次 update_ip_catalog。自己封装核的组织方式见 FPGA IP 核封装，工程与 IP 如何进 git 的长期纪律见 FPGA 进阶 41：工程与 IP 版本管理。

私有 IP 源：路径配对、目录刷新、Block Design 重新校验。 Tcl 建工程的标准写法是把仓库路径显式写进脚本，而不是依赖每台机器的 GUI 设置：

tcl
set_property ip_repo_paths [list D:/proj/demo/ip_repo] [current_project]
update_ip_catalog
# 板件仓库同理：
set_param board.repoPaths [list D:/proj/demo/board_files]

路径支持多个目录（用 list 给出），CI 机器上注意用相对工程根的路径或环境变量拼接，避免硬编码某人的盘符。设完属性不刷新目录是最常见的半截操作；Block Design 工程在仓库补齐后还要打开 BD 做一次 validate 并重新生成 HDL wrapper，背景见 FPGA 进阶 24：块设计 IP Integrator。注意区分：核能加载但综合/实现报 checkout failed 是授权缺失，不是仓库问题，走 Vivado license 取不出来速查。

五、预防与纪律 ​

  • 新机器先过环境清单：把 Vivado 发行说明的依赖包写成团队初始化脚本，装完用 ldd 抽查 Vivado 自带库再交机器。
  • 私有依赖一律子模块或制品库分发：ip_repo、board_files 不允许靠聊天工具传压缩包；.gitmodules 随主仓库提交，README 写明 --recurse-submodules。
  • 建工程脚本自带仓库配置：ip_repo_paths、board.repoPaths 写进 build.tcl 并紧跟 update_ip_catalog，任何人 clone 后一条脚本重建。
  • CI 镜像预装板件与兼容包：构建日志开头打印 Vivado 完整版本串与 report_ip_status，缺失在构建第一步就暴露，而不是半夜死在综合阶段。
  • 分清四个层次再动手：系统包、Vivado 版本、git 子模块、仓库路径各自独立，重装工具永远是最后选项而非第一反应。

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

本篇是 FPGA 工具报错排错簇中「依赖缺失」的分流页：缺的东西属于工具版本或 IP 版本时看 Vivado 版本不兼容速查；缺的东西被授权拦住时看 Vivado license 取不出来速查；文件路径写法本身有误看 Vivado 路径/文件不存在速查；依赖补齐后结果仍旧可能是缓存陈旧，对照 Vivado 构建缓存陈旧速查。IP 使用与封装的正向知识见 FPGA 入门 29：IP 核怎么调 与 FPGA IP 核封装，git 与 IP 的长期管理纪律见 FPGA 进阶 41：工程与 IP 版本管理。

一句话总结 ​

Vivado 依赖缺失先按报错抛出位置把缺失物分四层：启动前 libncurses/GLIBCXX 报错是系统共享库缺失，照发行说明装兼容包、不手工拷 so；选器件或板卡时 not found 是 Vivado 版本或 board_files 板件不满足，装达标版本与板厂板件包；ip_repo 目录为空是 git 子模块没拉，git submodule update --init --recursive 补齐；私有 IP 本机存在却 catalog 找不到是仓库路径没配，ip_repo_paths/board.repoPaths 配对后必须 update_ip_catalog 并重开工程重新生成 target；根治靠环境清单脚本、子模块分发与 build.tcl 内置仓库配置三件套。