锦
锦思新知编辑组
发布时间:2026/11/17 14:07:06
来源:锦思新知
阅读:知识向官网定制

第一次装PetaLinux的时候我以为这不过是个普通的命令行工具下载、解压、跑起来就完事。结果光一个libncurses5就卡了我一整个晚上后来好不容易过了这一关又在/bin/sh指向dash的问题上栽了跟头。那段时间我最大的感受是PetaLinux不是装不上而是大部分人根本没意识到装它之前需要先把宿主系统调教到它满意的状态。这篇内容我不打算把官方手册翻译一遍而是把我自己从零开始安装PetaLinux和配套SDK工具的完整过程、踩过的坑、以及排查思路写出来。给正在准备入坑嵌入式Linux开发、尤其是要做Zynq系列或者其它FPGAARM平台的朋友一个可以直接照着操作的路径。先说结论PetaLinux和SDK的安装难度不在安装本身而在版本匹配、系统依赖、磁盘规划和Shell环境这几件事上。这些前置条件没做好后面每一步都会莫名其妙报错。1. 动手之前先理清PetaLinux、SDK和Vivado三者的角色边界很多人第一次接触这个领域会被一堆工具名字绕晕。PetaLinux、SDK、Vivado、Vitis、BSP、XSA文件……我当初刚接触时候也是一脸懵为了搞清楚哪个是干嘛的没少做无用功。所以在讲安装步骤之前我先把这三个东西的分工捋清楚——想明白之后你就知道该装什么、不该装什么了。1.1 PetaLinux到底在替你干什么PetaLinux本质上是一套嵌入式Linux开发工具链它的底层基于Yocto项目做了大量定制和封装目的是把“为特定FPGA芯片构建可启动Linux系统镜像”这件事变得不那么痛苦。具体来说PetaLinux负责以下几件事配置和编译Linux内核petalinux-config/petalinux-build -c kernel生成U-Boot引导程序-c u-boot构建根文件系统rootfs-c rootfs根据Vivado导出的硬件描述文件生成设备树把上述所有组件打包成可用于SD卡启动或QSPI Flash启动的镜像文件比如BOOT.BIN、image.ub你可以把它理解成一个“Linux系统组装车间”。原来在普通PC上装Linux你要自己分区、拷内核、配引导、整rootfs到了嵌入式平台上这套流程更繁琐而且每个板子的硬件都不一样必须针对具体芯片生成对应的设备树。PetaLinux就把这一整套流水线串起来给你几个命令去控制。1.2 SDK和Vitis是同一个东西吗这可能是新手最容易混淆的地方。在Vivado 2020.1之前FPGA厂商提供了一款名为SDK的独立工具全称是Software Development Kit专门用来开发运行在ARM处理器上的裸机程序或者Linux应用程序。你可以用它在Vivado生成的硬件平台基础上创建BSP板级支持包也可以用交叉编译器写Linux应用程序和驱动。但是从2020.1之后SDK正式并入了Vitis统一开发环境。也就是说你现在去下载新版本的工具安装包里见到的是“Vitis”而不是“SDK”。Vitis里仍然包含了完整的嵌入式开发功能本质上就是原来的SDK换了件外套。所以当你看到网上老教程说“安装SDK”在2020.1以上的版本里你要找的其实是Vitis。我建议你在阅读相关资料时先看一眼版本号如果教程讲的是2020.2及以后版本里面出现“SDK”这个词时基本默认指Vitis的嵌入式开发组件。在安装阶段你只需要在统一安装器里勾上Vitis这一项不用单独找什么SDK安装包。1.3 版本错位是90%安装失败的最初源头这是我翻遍了各种报错帖子之后总结出的一个很重要经验。很多人的安装过程本身没有技术问题纯粹是版本没对齐。Vivado、Vitis、PetaLinux这三个工具的版本号必须严格对应。比如你用Vivado 2023.2做硬件工程导出的XSA文件就必须用PetaLinux 2023.2去导入用其它版本很可能直接报错或者构建出来无法启动。原因很简单XSA文件的内部格式、设备树生成的规则、U-Boot版本都会随着版本迭代而改变。这里我列一个常用的版本匹配表方便你规划Vivado/Vitis版本配套PetaLinux版本官方支持的常见Linux发行版2020.22020.2Ubuntu 18.04、Ubuntu 20.042022.22022.2Ubuntu 20.04、Ubuntu 22.042023.22023.2Ubuntu 20.04、Ubuntu 22.04不要觉得“版本旧一点、新一点无所谓”至少在PetaLinux这件事上厂商的对应关系卡得是很严的。你一旦固定了Vivado版本PetaLinux版本就是唯一确定的答案。2. 主机环境准备这些前置条件决定安装成败在正式跑PetaLinux安装器之前宿主系统的环境准备是决定性的一步。我见过太多人跳过这一步直接装结果安装器刚运行就报错然后一脸茫然。实际上PetaLinux安装器本身对系统的要求非常具体而且很多要求看起来跟“Linux系统能用”是两回事。2.1 系统版本、磁盘空间与安装目录规划先说系统版本。PetaLinux没有Windows版本也没有macOS版本它只能跑在Linux主机上。如果你手头是一台Windows电脑通常的做法有两个一个是装虚拟机VirtualBox或VMware都可以另一个是直接装双系统。从我自己的经验看虚拟机里跑PetaLinux完全可行但要注意给虚拟机分配充足的CPU和内存否则后续编译内核时会让你怀疑人生。磁盘空间是另一个容易被低估的点。PetaLinux安装本身不夸张装完之后占用大约8GB左右但真正可怕的是后面的构建过程。我第一次创建一个完整的MPSoC工程并执行petalinux-build下载的源码包、编译中间文件、最终镜像加起来轻轻松松突破了80GB。所以我给你的建议是给PetaLinux至少预留150GB的可用空间如果条件允许200GB会更从容。安装目录上有一个极易踩坑的细节路径中绝对不能有空格、中文、括号这类特殊字符。我见过有人在Windows虚拟机里把安装目录建在“我的文档”下面路径变成/home/username/我的文档/petalinux结果后续工具链在解析路径时不断报一些极其诡异的错误。PetaLinux和它背后的Yocto构建系统对路径的容忍度很低老老实实用/home/用户名/petalinux或者/opt/petalinux这种纯英文路径最稳妥。另外不要用root用户安装PetaLinux。官方明确说不支持在root环境下运行PetaLinux构建流程但很多人没注意到。如果安装到/opt这种系统目录普通用户没有写权限你装完还得手动把目录属主改过来。我通常的做法是直接安装在当前用户的主目录下省事又省心。2.2 Ubuntu依赖包批量安装含22.04的坑安装PetaLinux前需要一堆系统依赖包这是最容易出问题的环节之一。以Ubuntu 20.04 LTS为例官方手册列出的依赖包大概有这些sudo apt update sudo apt install -y gcc-multilib build-essential git chrpath socat \ xvfb xterm gawk automake libtool libncurses5-dev libncursesw5-dev \ zlib1g-dev libssl-dev tofrodos iproute2 python3 python3-pip \ python3-dev texinfo如果你用的是Ubuntu 22.04事情就没这么简单了。重点注意libncurses5-dev和libncursesw5-dev这两个包——它们在22.04的软件源里已经消失因为系统默认升级到了ncurses的第6个大版本。但PetaLinux安装器和后续的交叉编译工具链里有相当一部分二进制是较早前编译的运行时动态链接的是libncurses5的实际库。这就导致你在22.04上直接执行PetaLinux安装器会看到这样的报错error while loading shared libraries: libncursesw.so.5这个问题我当时折腾了挺久后来是在第三方软件包归档站点上找的libncurses5和libtinfo5的deb包手动下载后安装解决的。具体做法下面排查章节会细讲这里先提醒你如果是22.04提前做好手动安装兼容库的心理准备。2.3 把默认Shell切回Bash这是全过程中最不起眼、但影响面最大的一个问题。Ubuntu系统默认把/bin/sh指向了dash而不是bash。dash是一个轻量级的Shell启动速度快适合跑系统初始化脚本所以Ubuntu一直把它作为默认的/bin/sh。问题在于PetaLinux内部有大量构建脚本是用bash语法写的包含$(...)、数组、source等特性这些在dash下要么表现异常要么直接报语法错误。典型的现象是你在安装阶段一切正常但跑到petalinux-build的时候终端里冒出一堆类似/bin/sh: 1: Syntax error: ( unexpected的报错。这时候很多人第一反应是检查自己写的代码却忽略了系统的Shell指错了。修复方法非常简单sudo dpkg-reconfigure dash在弹出的界面里选“No”意思是“不使用dash作为默认的/bin/sh”。改完之后可以验证一下ls -l /bin/sh这时候应该看到输出指向/usr/bin/bash或类似的bash路径。这一个操作能帮你避免后面大量莫名其妙的问题。3. PetaLinux安装全流程从下载到能source准备工作做完现在可以正式进入安装了。PetaLinux的安装包和普通软件不一样它实际上是一个自解压安装器你下载下来的是一个二进制文件运行之后才真正开始解包安装。整个流程很简单但有几个细节值得你注意。3.1 下载installer之前的准备账号、SHA校验与网络PetaLinux的安装包需要在FPGA厂商官网注册账号后才能下载这是很多人一开始会卡住的地方。官方页面提供的安装包通常足够大——我记得自己下载2023.2版本时安装器文件在6GB左右。这个体积和完整Vivado安装包相比不算夸张但网络状况不好时依然很折磨人。我强烈的建议是下载完成后先校验哈希值再运行安装器。官网会在下载页给出对应的MD5或SHA256值用sha256sum命令比对一下sha256sum petalinux-v2023.2-installer.run这一步看起来多余但大文件下载时偶发损坏的概率并不低。我身边就有人因为下载的文件不完整运行安装器时每次都在同一个位置报“解压失败”怎么查都查不出原因最后重新下载一遍就好了。另外提醒一点PetaLinux安装器支持断点续传这把事别指望浏览器自带的下载功能。我当时是用支持分线程续传的下载工具拉下来的节省了不少时间。你根据自己的实际网络环境选择就好。3.2 用--dir参数把安装目录一次指定好下载完成后给安装器添加执行权限并运行chmod x ./petalinux-v2023.2-installer.run ./petalinux-v2023.2-installer.run --dir ~/petalinux/2023.2如果你是直接运行安装器而没有加--dir参数它会在交互界面里让你选择安装路径。我建议在命令行里直接指定这样整个安装流程更可控也避免在TUI界面里操作失误选错目录。在交互过程中有两个必经环节阅读并接受最终用户许可协议EULA确认安装组件列表并等待解包完成整个安装过程大概需要10到20分钟取决于你的磁盘读写速度和CPU性能。这时候别急着关终端安装器会在最后阶段检查一些关键依赖如果前面的系统环境准备不充分报错就会在这个阶段出现。还有一个小点如果你的安装器因为缺少某个动态链接库直接报错退出比如我之前提到的libncursesw.so.5那就说明前置环境还有问题先回第2节把依赖补上再试。3.3 安装后的第一件事source settings.sh并验证很多教程会在“安装完成”这几个字之后戛然而止但实际上还差一步关键的收尾让PetaLinux的环境变量生效。安装完成后安装目录下会出现一个settings.sh脚本它负责设置PETALINUX环境变量并把工具链的路径加入PATH。你需要这样加载它source ~/petalinux/2023.2/settings.sh加载完可以顺手验证一下echo $PETALINUX petalinux-version如果环境变量设置成功第一行会输出PetaLinux的安装根目录路径第二行会显示当前的PetaLinux版本号比如PetaLinux v2023.2。看到这两行输出说明PetaLinux本体已经装好了。这里隐藏着一个很容易踩的坑settings.sh必须在安装目录下调用或者用绝对路径调用不能把它复制出来再source。因为脚本内部会依据自身所在的位置推导安装根目录一旦你把它挪到了别处脚本就会把路径解析错。别问我是怎么知道的问就是那晚的教训。4. SDK/Vitis部分从Uniform Installer勾选到许可证SDK也就是新版Vitis的安装方式和PetaLinux完全不同。它不是独立运行的安装器而是和Vivado一起放在同一个“统一安装器”里。这意味着你装SDK之前必须先找到对应版本的Vivado统一安装包。4.1 新版安装器中Vivado和Vitis的勾选关系从官网下载到的“Vivado / Vitis统一安装器”通常是一个.bin文件体积比PetaLinux大不少完整版本可能有几十GB。运行它之前建议先确认好你要安装到哪个磁盘预留的空间是否够。运行安装器后图形界面会列出几个大块让你选Vivado这是FPGA逻辑设计的主工具做PL端开发必须装Vitis这就是原来SDK的升级版做PS端软件开发、调试、编译Linux应用程序必须要装Vivado Lab Solutions实验室调试用可选如果你既要做FPGA逻辑又要做ARM端嵌入式Linux开发那Vivado和Vitis这两块都要勾。勾选后界面还会让你选择支持的器件系列。这里有个省空间的小技巧如果只针对Zynq-7000系列开发就不必勾选其它诸如高端FPGA系列的器件库能省下不少磁盘空间和时间。安装时间取决于你勾选的组件多少。我只装了Zynq相关的组件加上Vitis全部功能在普通SSD上大概跑了四十多分钟。如果是机械硬盘做好等两三个小时的准备。4.2 安装耗时与磁盘空间实测参考很多人对选择安装组件这件事心里没数我在下面给出一个我实际安装时的大致参考方便你估算时间安装内容大致占用空间磁盘满载耗时SSD仅Vivado包含Zynq-7000器件库80GB左右约半小时Vivado Vitis全功能150GB左右约40到60分钟Vivado Vitis 所有器件系列200GB以上1到3小时空间规划这件事上宁可多预留也不要卡着算因为后续你在Vivado里创建工程、生成IP核、跑综合实现还会产生大量额外文件。我见过有人在250GB的虚拟机硬盘里同时装Vivado、Vitis、PetaLinux最后编译到一半磁盘满了那时候再扩虚拟机硬盘就很痛苦。4.3 许可证问题的零成本方案安装本身不需要输入许可证只有当你用Vivado做综合、实现、生成比特流等操作时许可才真正生效。对大多数学习场景来说厂商提供的免费许可足够用。在装完Vivado后第一次运行工程时我建议选择WebPACK免费许可它覆盖了Zynq-7000系列的大部分功能。如果你实际用的是更高端的器件需要到官网申请Evaluation评估许可这个也是免费的只是有效期有限。身边不少朋友一上来就下载了全功能License文件其实没必要先确认自己的器件在免费许可覆盖范围内往往能省去很多麻烦。5. 环境变量配置让命令行随手可用PetaLinux装好了Vitis也装好了接下来要解决的是“怎么让工具链每次打开终端都能直接用”。如果每次重新打开终端都要手动敲一遍source settings.sh那也太不工程师了。所以环境变量这步值得花几分钟配好。5.1 settings.sh的定位原理先说清楚settings.sh这种东西的运作逻辑你就能理解为什么不能把它随便搬走。settings.sh在执行时会依据脚本存放的实际位置去倒推出PetaLinux的安装根目录然后把这个路径赋值给PETALINUX环境变量同时把$PETALINUX/tools、$PETALINUX/bin等子目录都加入PATH。它内部实现大概类似这样PETALINUX_BASE$(dirname $(readlink -f $BASH_SOURCE)) export PETALINUX$PETALINUX_BASE export PATH$PETALINUX/tools/bin:$PETALINUX/bin:$PATH所以如果你的当前终端工作目录在别处但settings.sh用的是绝对路径source那就没问题。最早的坑在于有人会把脚本复制到自己的工程目录里再source脚本就会把工程目录当成PetaLinux的安装目录后面一跑全乱套。5.2 写入.bashrc的两种方式为了让每次打开终端都自动加载环境变量我习惯把source命令追加到~/.bashrc文件末尾echo source ~/petalinux/2023.2/settings.sh ~/.bashrc这里的路径要写成你实际安装PetaLinux的位置。写完后新开一个终端就能直接用petalinux-create这类命令。另外如果你装了多个PetaLinux版本建议不要一股脑把两个版本都写进.bashrc。更好的做法是先定义一个别名需要哪个版本就手动切哪个版本alias pl2023source ~/petalinux/2023.2/settings.sh需要的时候输入pl2023环境一次性就位。这个方法在多版本并行维护时特别好用我后来维护多个项目时一直这么干。5.3 用petalinux-version和which验证配置完成之后建议做一个完整的验证流程确保所有环节都通了echo $PETALINUX which petalinux petalinux-version正常的输出会依次显示PetaLinux安装根目录路径、petalinux命令的绝对路径、版本号。如果$PETALINUX为空说明shell脚本没加载成功如果which petalinux找不到命令说明PATH里没有正确包含工具目录。到这一步PetaLinux工具链的安装才算真正完成。很多人以为“安装器跑完安装完成”实际上只有当你能在任意目录下正常执行petalinux-version并且拿到版本信息这个工具才算真正可用了。6. 高频报错排查链从根因到修复安装过程中你可能遇到不止一次报错。好消息是绝大多数报错的原因都集中在少数几个方向上而且都有明确的解决方法。这里我把自己实际碰到的、以及帮朋友排查过的高频问题做一个汇总每个都带上我的排查思路你照着走一遍基本能解决。6.1 命令找不到并不可怕可怕的是.sh指向错误现象安装过程没问题但运行petalinux-build时冒出一堆诡异的shell语法错误例如/bin/sh: 1: Syntax error: ( unexpected。排查链路先确认当前Shell是不是bash执行echo $SHELL通常输出/bin/bash。继续排查系统默认的/bin/sh指向哪里执行ls -l /bin/sh。这时候十有八九看到/bin/sh - dash根因找到了。修复sudo dpkg-reconfigure dash在弹出的界面里选择“No”拒绝将dash作为默认的/bin/sh。验证重新执行ls -l /bin/sh确认输出指向bash。然后重新跑一次构建脚本那些语法错误就不见了。这个问题的隐蔽性在于它不影响你平时的日常操作普通脚本在dash下也能跑所以很多人根本不会往这个方向想。6.2 libncurses5消失与Ubuntu 22.04的兼容性补救现象在Ubuntu 22.04上运行PetaLinux安装器直接报error while loading shared libraries: libncursesw.so.5。排查链路用ldconfig -p | grep libncurses查看系统已安装的ncurses相关库。你会发现22.04系统里只有libncurses6没有5系列。PetaLinux安装器以及后续的交叉编译器二进制是链接到libncurses5的版本对不上就会报上述错误。修复需要手动获取并安装libncurses5和libtinfo5的deb包。可以在第三方归档站点搜索对应架构的.deb文件然后本地安装sudo dpkg -i libncurses5_6.3-2_amd64.deb sudo dpkg -i libtinfo5_6.3-2_amd64.deb验证执行ldconfig -p | grep libncursesw能看到libncursesw.so.5出现安装器就能正常运行了。这个坑在20.04上不太会出现所以网上很多安装教程根本没提导致22.04用户反复碰壁。6.3 /tmp空间不足与构建阶段预留容量现象安装器运行到一半报错No space left on device或者PetaLinux构建过程中在临时文件阶段直接失败。排查链路执行df -h /tmp查看/tmp挂载点的可用空间。如果/tmp是独立小分区或者是内存tmpfs空间很容易被占满。PetaLinux安装和解包的过程中会产生大量临时文件都优先往/tmp里写。修复给安装器指定一个更大的临时目录。你可以提前创建一个工作目录并通过环境变量告诉系统mkdir -p ~/petalinux/tmp export TMPDIR~/petalinux/tmp然后再运行安装器。验证重新执行安装器观察解包过程是否顺利通过。另外提醒一句后续petalinux-build阶段同样会用到临时空间建议这个TMPDIR变量也保留在环境配置里。6.4 Python环境错乱导致installer秒退现象安装器双击运行后终端闪一下就没有任何输出了也没有任何安装界面出现。排查链路这种“安静退出”的现象通常是安装器内部调用了某个脚本而脚本的shebang指向#!/usr/bin/env python。在较老的Ubuntu系统上如果默认的python命令指向Python 2或者根本不存在脚本就会静默失败。用which python和python --version检查一下当前默认Python的情况。修复如果发现默认Python不对安装python-is-python3包让/usr/bin/python直接指向Python 3sudo apt install -y python-is-python3验证执行python --version确认输出Python 3版本然后重新运行安装器界面就能正常出现了。说到Python这里再啰嗦一句PetaLinux 2022.x及之后的版本要求Python 3环境如果你同时还需要维护旧版Yocto或其它工具链注意别把系统级Python环境搞得太乱。我一般用虚拟环境工具管理项目级的Python依赖系统Python保持干净这样出现问题的概率会小很多。写到这里PetaLinux和SDK安装过程中我认为最关键、也最容易被忽略的环节都说完了。回头看一遍真正让我耗时最久的从来不是“下一步下一步”的安装过程而是那些藏在前置环境里的细小坑。装了这么多次之后我的习惯是先写好一套环境准备脚本新机器上一次性跑完再动安装器。这样操作下来后面基本都是一路顺畅。希望这篇整理能帮你少走点弯路一次就把环境理顺。
知识建站
内容驱动
阅读友好版式
SEO 精细化
线索转化
这篇内容对您有启发吗?
预约一次免费方案沟通,我们会根据您的行业给出可落地的站点架构建议。
立即预约沟通