开发环境搭建：Vitis安装指南、Xilinx运行时库(XRT)安装、设置环境变量、验证安装、常见安装问题排查

说实话，很多初学者一上来就急着写代码，结果卡在环境搭建上两三天。我见过太多人，明明代码逻辑没问题，就是跑不起来——最后发现是XRT没装对，或者环境变量配错了。这一章，咱们就把这些坑一个个填平。

核心要点：开发环境搭建是Vitis硬件加速的“地基”。地基不稳，楼盖得再高也得塌。我个人习惯把安装流程拆成四步：安装Vitis → 安装XRT → 设置环境变量 → 验证。一步都不能跳。

2.1 Vitis安装指南

Vitis统一平台，说白了就是把原来的SDx、Vivado、HLS这些东西打包在一起了。你装一个Vitis，就等于装了整套工具链。

安装前的准备：

操作系统：Ubuntu 18.04/20.04 或 CentOS 7.4+（我个人推荐Ubuntu 20.04，兼容性最好）
磁盘空间：至少100GB（别问我为什么，装完你就知道了）
内存：建议32GB以上，16GB也能跑，但编译大型工程时会很痛苦
显卡：非必需，但有NVIDIA显卡可以加速仿真

安装步骤：

从Xilinx官网下载Vitis安装包（约20GB，建议用下载工具，别用浏览器直接下）
解压安装包：tar -xzvf Xilinx_Vitis_2023.1_*.tar.gz
运行安装脚本：./xsetup
选择“Vitis”组件，勾选“Vivado”和“Vitis HLS”（这两个是必选项）
选择安装路径，我习惯放在 /tools/Xilinx 下
等待安装完成（约30-60分钟，取决于你的机器性能）

注意：安装路径不要包含中文或空格！我曾经有个同事把路径设成了“D:\Xilinx工具”，结果编译时各种奇葩报错，折腾了两天才发现是路径问题。

2.2 Xilinx运行时库(XRT)安装

XRT是什么？简单说，它是你的FPGA加速卡和主机程序之间的“翻译官”。没有XRT，你的C++代码就没办法跟FPGA硬件通信。

安装XRT：

# 添加XRT的APT源
sudo apt-get update
sudo apt-get install xrt

# 或者手动安装deb包
sudo dpkg -i xrt_202320.2.14.0_amd64.deb

安装完成后，检查一下XRT版本：

xbutil version

如果能看到版本号，说明XRT装上了。如果报错“command not found”，嗯，别急，往下看环境变量那部分。

我的经验：XRT的版本必须跟Vitis版本匹配。比如Vitis 2023.1就要配XRT 2023.1。版本不匹配的话，运行时会出现各种诡异的段错误。我曾经被这个坑过，排查了整整一天。

2.3 设置环境变量

这一步很多人会忽略，或者随便复制粘贴网上的脚本。我建议你理解一下每行在干什么。

创建一个脚本文件 setup_vitis.sh：

#!/bin/bash

# Vitis安装路径
export XILINX_VITIS=/tools/Xilinx/Vitis/2023.1
export XILINX_VIVADO=/tools/Xilinx/Vivado/2023.1
export XILINX_HLS=/tools/Xilinx/Vitis_HLS/2023.1

# XRT路径
export XILINX_XRT=/opt/xilinx/xrt

# 添加工具链到PATH
export PATH=$XILINX_VITIS/bin:$XILINX_VIVADO/bin:$XILINX_HLS/bin:$XILINX_XRT/bin:$PATH

# 添加库文件路径
export LD_LIBRARY_PATH=$XILINX_XRT/lib:$LD_LIBRARY_PATH

# 设置许可证服务器（如果有）
export XILINX_LICENSE_FILE=2100@license_server_ip

每次打开终端时，运行 source setup_vitis.sh。你也可以把它加到 ~/.bashrc 里，省得每次都手动执行。

避坑指南：我曾经把 LD_LIBRARY_PATH 设错了，结果系统自带的库被覆盖，连 ls 命令都报错。所以建议你只在需要时才source这个脚本，不要全局设置。

2.4 验证安装

环境搭好了，怎么知道对不对？跑几个简单的命令验证一下。

验证Vitis：

vitis -version
vivado -version
vitis_hls -version

三个命令都能正常输出版本信息，说明Vitis装好了。

验证XRT：

xbutil examine
xbutil validate

xbutil examine 会列出你机器上的FPGA加速卡。如果显示“No devices found”，别慌——可能是你没有插卡，或者驱动没加载。

验证编译流程：

写一个最简单的HLS代码，编译一下看看能不能通过：

// vector_add.cpp
#include <ap_int.h>

void vector_add(int a[10], int b[10], int c[10]) {
    for (int i = 0; i < 10; i++) {
        c[i] = a[i] + b[i];
    }
}

vitis_hls -f vector_add.cpp -t hls

如果编译成功，恭喜你，环境搭建完成！

2.5 常见安装问题排查

这里列几个我遇到过的典型问题，你碰到了可以直接对照排查。

问题现象	可能原因	解决方法
`vitis: command not found`	环境变量没设置	检查 `PATH` 是否包含Vitis的bin目录
`libxrt_core.so: cannot open shared object file`	`LD_LIBRARY_PATH` 没设对	确认 `$XILINX_XRT/lib` 在库路径中
`ERROR: [XRT] No devices found`	驱动没加载或卡没插好	运行 `sudo xbutil reset` 或重启机器
编译时提示 `license check failed`	许可证没配置	检查 `XILINX_LICENSE_FILE` 是否正确
安装时磁盘空间不足	安装包太大	清理磁盘或换到更大的分区

我的建议：遇到问题先看日志。Vitis的日志在 /tmp/vitis_*.log，XRT的日志在 /var/log/xrt。日志里通常会有明确的错误信息，比你在网上瞎搜强多了。

知识体系总览

下面这张图概括了本章的核心内容，你可以把它当作搭建环境的“路线图”：

环境搭建这部分，说白了就是“一次配置，长期受益”。花点时间把这一步走稳了，后面写代码、跑仿真、做部署都会顺畅很多。我个人觉得，与其在出问题时花两天排查，不如在搭建时多花两小时把每一步都验证清楚。

嗯，如果你严格按照上面的步骤来，应该不会出大问题。万一真遇到了什么奇怪的错误，先看日志，再看表格里的常见问题，基本都能解决。

📚 课程目录

开发环境搭建：Vitis安装指南、Xilinx运行时库(XRT)安装、设置环境变量、验证安装、常见安装问题排查

2.1 Vitis安装指南

2.2 Xilinx运行时库(XRT)安装

2.3 设置环境变量

2.4 验证安装

2.5 常见安装问题排查

知识体系总览