Ubuntu 20 开发环境与源码准备

本章目标

本章只准备开发主机和源码，不编译固件，也不写入开发板。完成后应具备以下条件：

Ubuntu 20.04 LTS x86_64 运行正常；
Buildroot、Linux、U-Boot 和 OpenixCLI 所需主机工具可用；
Rust 工具链满足 OpenixCLI 最低版本要求；
当前用户能够访问 UART 和 Allwinner FEL USB；
两个功能分支放在约定的兄弟目录中；
主机、源码提交和硬件连接都有可复查记录。

默认环境

项目	默认或建议值
开发主机	Ubuntu 20.04 LTS 64 位
架构	x86_64
CPU	至少 4 核
内存	至少 8 GiB，推荐 16 GiB
可用磁盘	至少 100 GiB
工作区文件系统	ext4 等 Linux 原生文件系统
目标板	100ASK T113S3 Pro SPI NAND 版本
主机连接	OTG/FEL USB + 独立 UART3

构建目录不要放在 NTFS、FAT、VMware Shared Folders、VirtualBox Shared Folders 或网络共享目录中。这些文件系统可能破坏符号链接、权限、大小写或时间戳，导致 Buildroot 出现难以复现的错误。

选择开发主机形式

场景	建议方案	说明
有独立 Linux 电脑	实体机安装 Ubuntu 20.04	编译和 USB 重连最稳定
Windows 主机	VMware 中安装 Ubuntu 20.04	使用方便，但必须处理 USB 直通
VirtualBox 用户	Ubuntu 20.04 虚拟机	可用，同样需要 USB 过滤器
只有 WSL2	不作为本文默认方案	USB FEL、串口和 Linux 文件系统处理更复杂

本文后续命令均在 Ubuntu 终端执行。Windows PowerShell、CMD 和 WSL2 不是默认命令环境。

获取并安装 Ubuntu 20.04

对供应链和可复现性有要求时，建议从 Ubuntu 20.04 LTS 官方发布页下载 AMD64 ISO，自行安装并核对官方公布的校验值。

使用虚拟机时：

在 VMware 或 VirtualBox 中创建 64 位 Ubuntu 虚拟机；
分配至少 4 个 CPU、8 GiB 内存和 120 GiB 虚拟磁盘；
使用 Ubuntu 20.04 AMD64 ISO 完成安装；
网络选择 NAT 或桥接均可，但 Ubuntu 必须能访问 GitHub 和源码下载站；
启用 USB 控制器，确保 Allwinner FEL 和 USB 转串口可以连接到 guest；
安装完成后先创建快照，再开始配置开发环境。

VMware 打开已有虚拟机

如使用已经准备好的 Ubuntu 20.04 VMware 镜像，在 VMware 中选择 文件 > 打开，再选择镜像中的 .vmx 文件。

VMware 中打开虚拟机配置

操作截图来源于 100askTeam/linuxboard-docs。截图只说明 VMware 的“打开”入口；本文要求导入的是 Ubuntu 20.04，而不是旧教程中的 Ubuntu 18.04 镜像。

如果 VMware 询问虚拟机是移动还是复制而来，首次导入副本时选择“我已复制该虚拟机”。进入 Ubuntu 后检查实际磁盘空间，不要只看虚拟磁盘的最大容量。

检查系统和资源

打开 Ubuntu 终端：

uname -m
lsb_release -ds
nproc
free -h
df -h "$HOME"

预期至少满足：

架构：x86_64
系统：Ubuntu 20.04.x LTS
CPU：4 核或更多
内存：8 GiB 或更多
HOME 所在分区：100 GiB 或更多可用空间

补丁版本不同通常不影响构建，但系统大版本不是 20.04 时，应在构建记录中明确写出实际版本，不能继续声称使用默认环境。

安装主机依赖

先更新软件包索引：

sudo apt update

安装主线构建、镜像处理、USB 和串口工具：

sudo apt install -y \
  build-essential gcc g++ make git \
  python3 python3-dev \
  bc bison flex cpio rsync file \
  wget curl unzip tar gzip bzip2 xz-utils zstd patch perl \
  libncurses-dev libssl-dev libelf-dev \
  libusb-1.0-0-dev pkg-config \
  device-tree-compiler picocom usbutils udev

这些软件包分别覆盖 Buildroot 主机构建、Linux/U-Boot 配置、FIT/设备树、UBI 打包、OpenixCLI 的 libusb 依赖以及板卡调试。不要照抄 Tina4/Tina5 教程中的 Python 2、Android 或 32 位兼容包，除非其他独立项目确实需要。

安装完成后执行：

gcc --version
make --version
python3 --version
git --version
dtc --version
pkg-config --modversion libusb-1.0

每条命令都必须成功输出版本号。apt 没有报错不等于工具已经全部可用。

安装 Rust 工具链

OpenixCLI 要求 Rust 1.70 或更新版本。Ubuntu 20.04 软件源中的 Rust 可能过旧，因此本文使用 Rustup 管理当前稳定工具链。

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o /tmp/rustup-init.sh
less /tmp/rustup-init.sh
sh /tmp/rustup-init.sh -y --profile minimal --default-toolchain stable
source "$HOME/.cargo/env"

下载后先查看脚本，再执行安装。检查版本：

rustc --version
cargo --version

新开终端后如果找不到 cargo，执行：

source "$HOME/.cargo/env"

并确认 shell 启动文件中已经加载 Cargo 环境。

配置串口权限

将当前用户加入串口和 USB 常用用户组：

sudo usermod -aG dialout,plugdev "$USER"

注销 Ubuntu 会话并重新登录，然后执行：

id
ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null

id 输出应包含 dialout 和 plugdev。找到实际串口后可先验证 UART3：

picocom -b 115200 --flow n /dev/ttyUSB0

将 /dev/ttyUSB0 替换为实际设备节点。按 Ctrl+A，再按 Ctrl+X 退出。

配置 FEL USB 权限

先创建 Allwinner FEL 的 udev 规则：

sudo tee /etc/udev/rules.d/99-allwinner-fel.rules >/dev/null <<'EOF'
SUBSYSTEM=="usb", ATTR{idVendor}=="1f3a", ATTR{idProduct}=="efe8", MODE="0660", GROUP="plugdev"
EOF

sudo udevadm control --reload-rules
sudo udevadm trigger

让开发板重新进入 BootROM FEL，再检查：

lsusb -d 1f3a:efe8

预期能够看到 Allwinner 设备。虚拟机里设备每次重新枚举后都可能回到宿主机；如果命令突然看不到设备，先检查 VMware/VirtualBox 的 USB 归属，不要立即修改 OpenixCLI。

创建工作目录

mkdir -p "$HOME/workspace/t113-mainline-work"
cd "$HOME/workspace/t113-mainline-work"
pwd

推荐目录如下：

$HOME/workspace/t113-mainline-work/
├── OpenixCLI/
└── DshanPI-T113xMainlineLinux/

两个仓库默认必须互为兄弟目录。不要把其中一个仓库克隆到另一个仓库内部。

软件与源码基线

组件	固定值
主线系统仓库分支	`feat/t113s3pro-mainline`
本文核对提交	`1f28a1ca10d7887560c56350bc87cf56137b1010`
OpenixCLI 分支	`feat/mainline-fel-ram-installer`
OpenixCLI 硬件验证实现	`f10ff48cf938d5a85e45e2a78f241f6602baff06`
Buildroot	`86102dd8279ac6c4c0244f3e490af98dc7460d5e`
Linux	6.18.8
U-Boot	2026.07
libefex revision	`3752e38ff8e69190c53cd43290a8102beab55e73`

Linux 和 U-Boot 源码归档的 SHA-256 保存在主线仓库的 manifests/sources.lock 中。构建脚本会启用 Buildroot 下载哈希检查。

获取两个功能分支

cd "$HOME/workspace/t113-mainline-work"

git clone -b feat/mainline-fel-ram-installer \
  https://github.com/100askTeam/OpenixCLI.git

git clone -b feat/t113s3pro-mainline \
  https://github.com/dshanpi/DshanPI-T113xMainlineLinux.git

记录实际分支、提交和工作区状态：

git -C OpenixCLI status --short --branch
git -C OpenixCLI rev-parse HEAD

git -C DshanPI-T113xMainlineLinux status --short --branch
git -C DshanPI-T113xMainlineLinux rev-parse HEAD

功能分支可能继续产生新提交，因此必须保存实际 HEAD。不要为了匹配文档提交而对已有工作区执行强制 reset。

主线仓库目录职责

DshanPI-T113xMainlineLinux/
├── board/dshanpi/t113s3pro/   # DTS、补丁、FIT、安装器和封装脚本
├── configs/                   # Buildroot 板级 defconfig
├── docs/                      # 英文设计与开发记录
├── logs/                      # 净化后的硬件和任务证据
├── manifests/                 # 固定源码与历史产物哈希
├── scripts/                   # 构建、打包、烧写和验收入口
├── Makefile
└── out/                       # 本地生成，不作为源码提交

环境验收

执行一次集中检查：

for tool in git make gcc python3 cpio zstd rsync cargo; do
  command -v "$tool" || exit 1
done

pkg-config --exists libusb-1.0
test "$(uname -m)" = x86_64
test -f DshanPI-T113xMainlineLinux/manifests/sources.lock
test -f OpenixCLI/Cargo.lock

硬件已连接时再检查：

lsusb -d 1f3a:efe8
ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null

满足以下条件才能进入编译阶段：

Ubuntu 版本、架构、CPU、内存和磁盘空间已经记录；
所有必需命令可执行；
cargo 满足 OpenixCLI 的最低 Rust 版本；
pkg-config 能找到 libusb 1.0；
两个仓库分支正确、状态可解释；
FEL USB 和 UART3 均能由 Ubuntu 访问。

常见问题

现象	处理方法
`cargo: command not found`	重新加载 `$HOME/.cargo/env`，检查 Rustup 是否安装完成
`libusb-1.0 not found`	安装 `libusb-1.0-0-dev` 和 `pkg-config`
Ubuntu 中没有 `1f3a:efe8`	检查 FEL 操作和虚拟机 USB 直通
串口提示 Permission denied	重新登录后确认用户属于 `dialout`
Buildroot 出现符号链接或权限错误	把工作区移到 Ubuntu 内部的 ext4 分区
磁盘在构建中耗尽	扩容文件系统并保留失败日志，不删除源码证据
分支或提交不一致	记录实际提交并判断是否需要重新完成硬件验收

需要保存的证据

Ubuntu 版本：
主机架构：
CPU/内存：
工作区文件系统与剩余空间：
Rust/Cargo 版本：
OpenixCLI commit：
主线系统仓库 commit：
UART 设备节点：
FEL USB 与 libusb 位置：

本章的主机搭建顺序参考 100askTeam/linuxboard-docs 的既有开发环境文档，并按 Ubuntu 20.04、主线 Buildroot 和 OpenixCLI 的实际要求重新整理。环境验收通过后，先阅读主线系统构建与打包总览，建立全局流程，再进入各组件适配章节。

本章目标​

默认环境​

选择开发主机形式​

获取并安装 Ubuntu 20.04​

VMware 打开已有虚拟机​

检查系统和资源​

安装主机依赖​

安装 Rust 工具链​

配置串口权限​

配置 FEL USB 权限​

创建工作目录​

软件与源码基线​

获取两个功能分支​

主线仓库目录职责​

环境验收​

常见问题​

需要保存的证据​