# docker-peatlinux-v2022.2

**Repository Path**: kjfb/docker-peatlinux-v2022.2

## Basic Information

- **Project Name**: docker-peatlinux-v2022.2
- **Description**: peatlinux-v2022.2 docker 环境
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-15
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PetaLinux 2022.2 Docker 开发环境（基于 Ubuntu 20.04）

基于官方依赖清单与安装包，构建一个**开箱即用**的 PetaLinux 2022.2 开发环境镜像。
镜像构建阶段完成全部依赖安装与 PetaLinux 工具的无人值守安装，容器内以非 root 用户
`petalinux`（UID/GID = 1000，与宿主对齐）运行，登录即自动激活 `settings.sh`。

- 依赖来源：`sourcefile/2022.2_PetaLinux_Package_List.xlsx`（AMD 官方清单）
- 安装包：`sourcefile/petalinux-v2022.2-10141622-installer.run`（约 2.6 GB）
- 基础镜像：`ubuntu:20.04`
- 安装目录：`/opt/pkg/petalinux/2022.2`

---

## 1. 文件说明

| 文件 | 说明 |
|---|---|
| `Dockerfile` | 多阶段构建定义：`base`（依赖环境）/ `builder`（安装 PetaLinux）/ `final`（开箱即用） |
| `build.sh` | 一键构建脚本（校验环境、参数可覆盖、启用 BuildKit） |
| `run.sh` | 一键运行脚本（挂载工程目录、进入交互 shell、命令透传） |
| `export.sh` | 一键导出脚本（把镜像压缩打包到 `dist/`，供离线分发；可选分卷） |
| `.dockerignore` | 构建上下文白名单（仅保留 `Dockerfile` 与 `sourcefile/*.run`） |
| `sourcefile/` | 原始素材：官方包清单 + PetaLinux 安装包 |
| `dist/` | `export.sh` 的产物目录（导出的镜像包 + 导入脚本 + 配套文件） |

---

## 2. 前置条件

- 已安装 Docker（建议 23+，默认启用 BuildKit）。当前宿主 **未安装 docker**，需先安装。
  非 root 用户需加入 `docker` 组或使用 `sudo`。
- 磁盘空间：建议宿主预留 **≥ 40 GB**（构建缓存 + 最终镜像，镜像约 10~15 GB）。
- 内存：建议 **≥ 8 GB**（apt 与安装解压阶段内存占用较高）。
- 构建上下文需包含约 2.6 GB 的 `.run` 文件，首次构建需将其传输给 Docker daemon，属正常现象。

Ubuntu 20.04 下安装 Docker（使用阿里云镜像，无需访问被墙的 `get.docker.com`）：

```bash
# 1) 卸载 Ubuntu 仓库里同名的“托盘”程序
#    注意：apt 的 docker 包（1.5-2）不是 Docker 引擎，必须移除
sudo apt-get remove -y docker wmdocker

# 2) 依赖 + Docker 官方 GPG key（阿里云镜像）
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
sudo rm -f /etc/apt/keyrings/docker.gpg
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 3) 添加 docker-ce 仓库（focal = Ubuntu 20.04）
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu focal stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list

# 4) 安装 Docker Engine（含 BuildKit/buildx）
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 5) 配置国内镜像加速器（拉取 ubuntu:20.04 等基础镜像用）
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json >/dev/null <<'EOF'
{
  "registry-mirrors": [
    "https://docker.1panel.live",
    "https://docker.m.daocloud.io",
    "https://docker.1ms.run"
  ]
}
EOF

# 6) 启动 / 重启服务
#    注意：apt 安装时 docker 通常已被自动拉起，
#    写入 daemon.json 后必须 restart 才会加载配置。
sudo systemctl enable --now docker
sudo systemctl restart docker

# 7) 加入 docker 组（重新登录后生效）
sudo usermod -aG docker $USER
sudo chmod 666 /var/run/docker.sock
sudo systemctl restart docker

# 8) 验证
docker --version
docker run --rm hello-world
```

---

## 3. 构建

```bash
cd /home/lemon/01_petalinux_workspace/ZU19EG/docker
./build.sh
```

自定义构建（环境变量覆盖）：

```bash
# 仅安装 aarch64（ZynqMP/Versal）源码，显著减小镜像体积、缩短构建时间
PETALINUX_PLATFORM=aarch64 ./build.sh

# 自定义镜像名与 tag、apt 源
IMAGE_NAME=my-peta IMAGE_TAG=2022.2-zu19eg APT_MIRROR=mirrors.tuna.tsinghua.edu.cn ./build.sh
```

可覆盖参数（详见 `./build.sh -h`）：

| 变量 | 默认值 | 说明 |
|---|---|---|
| `IMAGE_NAME` | `petalinux` | 镜像名 |
| `IMAGE_TAG` | `2022.2` | 镜像标签 |
| `UBUNTU_VERSION` | `20.04` | 基础镜像版本 |
| `APT_MIRROR` | `mirrors.aliyun.com` | apt 国内镜像域名 |
| `USER_UID` / `USER_GID` | 宿主 `id -u` / `id -g` | 容器内 `petalinux` 用户 UID/GID |
| `PETALINUX_VER` | `2022.2` | PetaLinux 版本（安装子目录名） |
| `PETALINUX_PLATFORM` | 空（全部） | 仅安装指定架构源码：`aarch64`/`arm`/`microblaze`/`aarch64_dt` |
| `SOURCEFILE_DIR` | `<脚本目录>/sourcefile` | 安装包所在目录 |

> 提示：ZU19EG 属于 Zynq UltraScale+ MPSoC（aarch64），使用
> `PETALINUX_PLATFORM=aarch64 ./build.sh` 可只装 ZynqMP/Versal 源码。

---

## 4. 运行

```bash
cd /home/lemon/01_petalinux_workspace/ZU19EG/docker

./run.sh                              # 挂载上一级工程目录，进入交互式 shell
./run.sh -w /path/to/your/project     # 指定要挂载的工程目录（容器内挂载点为 /workspace）
./run.sh -c "petalinux-create --help"   # 执行单条命令后退出
./run.sh --network host               # 使用宿主网络（TFTP/NFS 等场景）
```

容器行为：

- 用户：`petalinux`（UID/GID 与宿主一致），`HOME=/home/petalinux`
- 工作目录：`/workspace`（映射到宿主工程目录）
- 登录即自动 `source /opt/pkg/petalinux/2022.2/settings.sh`
- `--rm`：容器退出后自动删除

进入容器后即可在 `/workspace` 下执行 `petalinux-create`、`petalinux-config`、`petalinux-build` 等命令。

---

## 5. 验证

```bash
IMAGE=petalinux:2022.2

# 5.1 用户与环境变量 / 工具可用性
#     注意：health check 用 `petalinux-create --help`（退出码 0）。
#     不要用 `petalinux-util --version`：该工具无此选项，会打印用法并返回 255，
#     看似失败实则正常。
docker run --rm $IMAGE bash -lc 'whoami && echo $PETALINUX && petalinux-create --help >/dev/null && echo "petalinux-create OK"'

# 5.2 依赖验证：i386 架构、gcc、python
docker run --rm $IMAGE bash -lc 'dpkg --print-foreign-architectures; gcc --version | head -1; python3 --version'

# 5.3 /bin/sh 已指向 bash、locale 生效
docker run --rm $IMAGE bash -lc 'ls -l /bin/sh; locale | head -3'

# 5.4 工程级验证（在容器内 /workspace 下）
./run.sh -c 'cd /workspace && petalinux-build 2>&1 | head -20'
```

---

## 6. 发布 / 分发给他人

将已构建好的镜像交付给同事使用，有三种方式：

### 方式 A：`export.sh` 离线打包（推荐，内网 / U 盘 / scp）

```bash
cd /home/lemon/01_petalinux_workspace/ZU19EG/docker
./export.sh                    # 导出镜像压缩包到 dist/
SPLIT_SIZE=4g ./export.sh      # 可选：按 4GB 分卷（便于 FAT32 U 盘拷贝）
```

产物（`dist/` 目录，整体拷给对方即可）：

| 文件 | 说明 |
|---|---|
| `petalinux-2022.2-image.tar.gz`（或 `.part` 分卷） | 镜像压缩包（12 GB 镜像约压至 5~7 GB） |
| `SHA256SUMS` | 校验和 |
| `import.sh` | 接收方一键导入脚本 |
| `run.sh` / `build.sh` / `Dockerfile` / `README.md` | 运行所需配套文件 |

接收方（只需安装好 Docker，**无需 2.6GB 安装包、无需重新构建**）：

```bash
cd dist/
sha256sum -c SHA256SUMS    # 1) 校验完整性
./import.sh                # 2) 导入镜像（自动合并分卷并 docker load）
./run.sh                   # 3) 启动容器
```

### 方式 B：推送镜像仓库（团队长期更新用）

```bash
# 以阿里云个人版为例（免费，国内速度快）：先在控制台创建命名空间与仓库
docker login registry.cn-hangzhou.aliyuncs.com
docker tag petalinux:2022.2 registry.cn-hangzhou.aliyuncs.com/<你的命名空间>/petalinux:2022.2
docker push registry.cn-hangzhou.aliyuncs.com/<你的命名空间>/petalinux:2022.2

# 接收方
docker pull registry.cn-hangzhou.aliyuncs.com/<你的命名空间>/petalinux:2022.2
```

> 注意：12 GB 镜像首次推送耗时长，且个人版有存储配额；适合多人频繁拉取的场景。

### 方式 C：分发源目录（需可复现 / 自定义时）

把整个 `docker/` 目录（含 `sourcefile/` 的 2.6 GB 安装包）打包给对方，
对方自行执行 `./build.sh`（需预留 40 GB 磁盘，构建约 15 分钟）。透明可复现，但门槛最高。

---

## 7. 设计说明

### 7.1 三阶段构建

```
ubuntu:20.04
   │
   ├─ base    依赖环境（apt 国内源 + i386 + 依赖 + locale + petalinux 用户 + 免密 sudo）
   │
   ├─ builder 以 petalinux 用户执行 .run，安装到 /opt/pkg/petalinux/2022.2，随后删除安装包与日志
   │
   └─ final   COPY --from=builder 仅复制安装树 → 注入 PETALINUX 环境变量 + 自动 source settings.sh
```

采用多阶段的关键原因：安装包约 2.6 GB，若在单阶段中安装后 `rm`，该文件仍会残留在
镜像分层中无法回收；多阶段构建的最终镜像**不含安装包本体**。

### 7.2 关键处理

- **i386 多架构**：清单要求 `zlib1g:i386`，先 `dpkg --add-architecture i386` 再安装 32 位库。
- **包名按 20.04 修正**：`tftp-server → tftpd-hpa`、`SDL-devel → libsdl1.2-dev`、
  `glib2-devel → libglib2.0-dev`；`python → python-is-python3`（20.04 已无 `python` 包）；
  补充 `libtinfo5`、`libncurses5` 等工具链关键依赖。
- **`/bin/sh → bash`**：PetaLinux 强制要求，Ubuntu 默认 dash 会导致构建脚本报错。
- **非 root 安装与运行**：安装器检测到 `UID == 0` 会直接退出；容器内以 `petalinux` 用户
  运行以满足 PetaLinux 的 root 限制。
- **免密 sudo**：写入 `/etc/sudoers.d/petalinux`，便于容器内执行需要 root 的操作。
- **locale**：生成 `en_US.UTF-8` 并设为默认，避免 PetaLinux 的 locale 告警。
- **无人值守安装**：使用安装器支持的 `--skip_license`（等价于 `SKIP_LICENSE=y`）+
  `--dir <path>`，并以 `yes |` 兜底。参数已核实自安装器 `--help`。

### 7.3 apt 国内源

仅替换 `archive.ubuntu.com` / `security.ubuntu.com` 为 `APT_MIRROR`，兼容 Ubuntu 20.04
传统 `sources.list` 格式；如需更换镜像站，改 `APT_MIRROR` 即可。

---

## 8. 常见问题（FAQ）

**Q1：构建时提示上下文传输很慢？**
A：因为要传输约 2.6 GB 的 `.run` 文件。可将源码与构建机放在同一台机器，或使用
`docker buildx` 配合本地 daemon。这属正常现象，只需传输一次。

**Q2：安装阶段报 `Please install required packages.`？**
A：安装器会运行 `petalinux-env-check` 校验宿主依赖。本镜像已按官方清单安装全部依赖；
若官方清单更新，请在 `Dockerfile` 的 `base` 阶段补装对应包后重建。

**Q3：apt 安装失败 / 网络超时？**
A：更换 `APT_MIRROR`（如 `mirrors.tuna.tsinghua.edu.cn`、`mirrors.ustc.edu.cn`）。

**Q4：容器内文件属主是 root 或权限报错？**
A：确认构建时 `USER_UID/USER_GID` 与宿主一致（`build.sh` 默认自动取 `id -u`/`id -g`）。
若宿主不是 1000，构建时请显式传入相应值。

**Q5：想减小镜像体积？**
A：构建时加 `PETALINUX_PLATFORM=aarch64`（仅 ZynqMP/Versal 源码）。

**Q6：宿主未安装 docker，能否先生成文件？**
A：可以。本目录仅生成构建所需文件；实际构建/验证需在已安装 Docker 的环境执行。

**Q7：安装已成功打印 `PetaLinux SDK has been installed`，却仍报构建失败？**
A：看紧随其后的报错行。早期版本在安装 RUN 的末尾执行 `rm /tmp/petalinux-installer.run`，
而该文件由 `COPY` 引入、属主为 root，`/tmp` 的 sticky 位使 `petalinux` 用户无权删除，`set -e`
遂判定整层失败（安装成果连同缓存一起被丢弃）。现已通过 `COPY --chown` 修正属主，并把清理
独立成层，此问题不再出现。

**Q8：`petalinux-util --version` 报错并返回 255，是环境坏了吗？**
A：不是。`petalinux-util` / `petalinux-build` 没有 `--version` 选项，传入未识别的参数会打印
用法说明并以 255 退出，属工具自身行为。健康检查请改用 `petalinux-create --help`（退出码 0）。
`petalinux-util --version` 只有在**工程目录内**才会输出构建版本信息，且仍需配合工程使用。

---

## 9. 卸载 / 清理

```bash
docker rmi petalinux:2022.2          # 删除镜像
docker builder prune                 # 清理构建缓存（谨慎操作）
```