Skip to content

README.md

Latest commit

 

History

History
332 lines (237 loc) · 7.55 KB

README.md

File metadata and controls

332 lines (237 loc) · 7.55 KB

IMX-Forge Docker 开发环境

基于 Docker 的 i.MX6ULL 嵌入式 Linux 开发环境，预装所有必需的工具链和依赖。

特性

  • ✅ Ubuntu 24.04 基础镜像
  • ✅ ARM GNU Toolchain 15.2.rel1 交叉编译工具链
  • ✅ 多阶段构建 优化镜像大小
  • ✅ 非 root 用户 运行（安全）
  • ✅ 预装所有依赖 开箱即用

快速开始

方式一：直接拉取预构建镜像（推荐）

我们会为正式 release 提供预构建 Docker 镜像，可以直接拉取使用。正式版本标签从 v0.1.0 开始；如果尚未发布对应标签，请使用本地构建方式。

# 拉取最新版本
docker pull ghcr.io/awesome-embedded-learning-studio/imx-forge:latest

# 启动开发环境
cd imx-forge
docker run -it --rm -v $(pwd):/workspace ghcr.io/awesome-embedded-learning-studio/imx-forge:latest

使用特定版本：

docker pull ghcr.io/awesome-embedded-learning-studio/imx-forge:v0.1.0

方式二：本地构建

如需自定义或使用国内镜像优化版，可以本地构建：

0. 国内用户加速（推荐）

如果你在中国大陆，建议使用国内镜像源版本：

cd docker

# 方法 1：配置 Docker 镜像加速器（推荐）
sudo mkdir -p /etc/docker
sudo cp daemon.json /etc/docker/daemon.json
sudo systemctl daemon-reload
sudo systemctl restart docker

# 方法 2：使用国内优化的 Dockerfile
DOCKER_BUILDKIT=1 sudo docker build -f Dockerfile.cn -t imx-forge:latest .

1. 构建镜像

cd docker

# 使用 BuildKit 构建（推荐）
DOCKER_BUILDKIT=1 docker build -t imx-forge:latest .

# 或使用传统方式
docker build -t imx-forge:latest .

构建时间：约 5-10 分钟（取决于网络速度）

2. 运行容器

基本用法

docker run -it --rm \
    -v $(pwd)/..:/workspace \
    imx-forge:latest

挂载项目目录

docker run -it --rm \
    -v /path/to/imx-forge:/workspace \
    -v /path/to/output:/workspace/out \
    imx-forge:latest

使用 USB 设备（烧录）

docker run -it --rm \
    --privileged \
    -v /dev:/dev \
    -v $(pwd)/..:/workspace \
    imx-forge:latest

3. 编译项目

进入容器后，可以使用以下命令：

./scripts/build_helper/build-uboot.sh      # 编译 U-Boot
./scripts/build_helper/build-linux.sh      # 编译 Linux 内核
./scripts/build_helper/build-busybox.sh    # 编译 BusyBox
./scripts/release-all.sh                   # 一键构建所有组件

镜像信息

大小

  • 最终镜像大小：约 2GB（截至文档更新时，实际大小可能存在波动）
  • 构建阶段镜像：约 2.5GB（仅构建时使用）

包含的工具

工具 版本/说明
ARM GNU Toolchain 15.2.rel1
build-essential GCC, Make 等
device-tree-compiler 设备树编译器
u-boot-tools U-Boot 工具
python3-pyelftools Python ELF 工具
其他依赖 bc, bison, flex, swig 等

高级用法

自定义用户 ID

如果你的宿主机用户 ID 不是 1000，可以自定义：

docker build \
    --build-arg USER_ID=$(id -u) \
    --build-arg GROUP_ID=$(id -g) \
    -t imx-forge:latest \
    .

使用特定工具链版本

docker build \
    --build-arg TOOLCHAIN_VERSION=15.2.rel1 \
    -t imx-forge:latest \
    .

控制构建输出详细程度

VERBOSE 和 Docker 的进度输出是两层不同的开关：

  • --build-arg VERBOSE=1：让 Dockerfile 里的 wget 使用详细输出
  • --progress=plain：让 BuildKit 不使用动态刷新界面，按普通日志逐行输出
# 默认模式（显示进度条）
docker build -t imx-forge:latest .

# 详细输出模式（推荐用于调试下载问题）
docker build --progress=plain --build-arg VERBOSE=1 -t imx-forge:latest .

# 如果从项目根目录构建，请显式指定 Dockerfile 路径
docker build --progress=plain --build-arg VERBOSE=1 -f docker/Dockerfile -t imx-forge:latest .

# 国内镜像源版本
docker build --progress=plain --build-arg VERBOSE=1 -f docker/Dockerfile.cn -t imx-forge:latest .

参数说明：

参数 控制对象 效果
VERBOSE=0 或未设置 Dockerfile 内部命令 使用默认下载输出
VERBOSE=1 Dockerfile 内部命令 wget 使用详细输出
--progress=plain Docker BuildKit 输出界面 禁用动态刷新，按普通日志逐行输出

注意：如果只设置 --build-arg VERBOSE=1，BuildKit 仍可能使用动态进度界面重绘终端，看起来像日志被覆盖。调试时优先使用 --progress=plain，通常不需要禁用 BuildKit。

持久化容器

创建一个持久化的开发容器：

docker run -dit \
    --name imx-dev \
    -v $(pwd)/..:/workspace \
    imx-forge:latest

docker exec -it imx-dev bash

Docker Compose

创建 docker-compose.yml：

version: '3'
services:
  imx-forge:
    build: .
    image: imx-forge:latest
    volumes:
      - ..:/workspace
      - ./out:/workspace/out
    stdin_open: true
    tty: true
    privileged: true
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0

运行：

docker-compose run imx-forge

验收测试

测试工具链

arm-none-linux-gnueabihf-gcc --version

预期输出：

arm-none-linux-gnueabihf-gcc (Arm GNU Toolchain 15.2.Rel1 (Build arm-15.86)) 15.2.1 20251203

测试 U-Boot 编译

cd /workspace
./scripts/build_helper/build-uboot.sh

测试 Linux 内核编译

cd /workspace
./scripts/build_helper/build-linux.sh

测试 BusyBox 编译

cd /workspace
./scripts/build_helper/build-busybox.sh

常见问题

Q: 镜像构建失败，提示网络错误？

A: 工具链下载需要访问 ARM 官网，可能需要配置代理：

docker build \
    --build-arg http_proxy=http://proxy:port \
    --build-arg https_proxy=http://proxy:port \
    -t imx-forge:latest \
    .

Q: 容器内无法访问 USB 设备？

A: 需要使用 --privileged 参数或将设备挂载到容器：

docker run -it --rm \
    --privileged \
    -v /dev:/dev \
    imx-forge:latest

Q: 编译产物权限问题？

A: 使用与宿主机相同的用户 ID 构建：

docker build \
    --build-arg USER_ID=$(id -u) \
    --build-arg GROUP_ID=$(id -g) \
    -t imx-forge:latest \
    .

Q: 国内用户 ghcr.io 拉取镜像慢怎么办？

A: 可以配置 Docker 镜像加速器。以下是国内常用的镜像加速源：

sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

注意: 大部分国内镜像加速器主要针对 Docker Hub，对 ghcr.io 的加速效果有限。如果仍然较慢，建议使用本地构建方式（Dockerfile.cn）。

Q: 如何清理构建缓存？

A: Docker 构建会占用磁盘空间，可以定期清理：

docker system prune -a

开发建议

  1. 使用卷挂载：将 out 目录单独挂载，避免编译产物占用容器空间
  2. 定期更新：定期重新构建镜像以获取最新工具链和依赖
  3. CI/CD 集成：可以在 CI/CD 流水线中使用此镜像进行自动化构建

许可证

MIT License

相关链接