Phoenix-RTOS 构建环境 Docker 镜像文档

1. 镜像概述和主要用途

本镜像为 Phoenix-RTOS（实时操作系统）提供预配置的标准化构建环境，旨在简化开发流程并确保跨平台环境一致性。通过封装Phoenix-RTOS构建所需的工具链、依赖库及配置脚本，开发者可快速部署环境，无需手动安装和配置底层依赖，专注于内核及应用开发。

2. 核心功能和特性

• 预配置工具链：集成Phoenix-RTOS构建必需的交叉编译器（如GCC、Clang）、链接器、汇编器及调试工具（GDB）。
• 多架构支持：默认支持x86、ARM、RISC-V等主流嵌入式架构，可通过参数扩展至其他架构。
• 版本兼容性：内置Phoenix-RTOS官方推荐的依赖版本（如Make 4.3+、CMake 3.20+、Python 3.8+），确保与目标源码版本匹配。
• 环境隔离：基于Docker容器的隔离性，避免宿主环境依赖冲突，支持多版本Phoenix-RTOS并行构建。
• 轻量级设计：基于Alpine或Debian slim镜像构建，最小化镜像体积（约800MB-1.2GB）。

3. 使用场景和适用范围

• 开发阶段：开发者快速构建Phoenix-RTOS内核、驱动或用户态应用。
• 自动化构建：集成至CI/CD流程（如GitHub Actions、GitLab CI），实现源码提交后的自动编译与测试。
• 教学/演示：高校或培训机构用于嵌入式实时系统教学，统一实验环境。
• 版本测试：并行构建不同版本的Phoenix-RTOS源码，验证兼容性或新特性。

4. 使用方法和配置说明

4.1 前置条件

• 宿主环境需安装Docker Engine（20.10+）或Docker Desktop。
• 宿主机需分配至少2GB内存及10GB磁盘空间（用于镜像拉取及构建缓存）。

4.2 获取镜像

从Docker Hub拉取官方镜像（假设镜像名称为phoenixrtos/build-env）：

docker pull phoenixrtos/build-env:latest

如需指定版本（如针对Phoenix-RTOS v1.2.0）：

docker pull phoenixrtos/build-env:v1.2.0

4.3 基本构建流程

4.3.1 挂载源码目录构建

将宿主机的Phoenix-RTOS源码目录（如/path/to/phoenix-rtos-src）挂载至容器内/workspace目录，执行构建命令：

docker run -it --rm \
  -v /path/to/phoenix-rtos-src:/workspace \
  -w /workspace \
  phoenixrtos/build-env:latest \
  make all

• -it：交互式终端，支持实时查看构建日志。
• --rm：构建完成后自动删除容器。
• -v：挂载宿主机源码目录至容器，确保构建产物输出至宿主机。
• -w：指定容器内工作目录为/workspace（源码根目录）。

4.3.2 指定目标架构

通过环境变量TARGET_ARCH指定构建目标架构（如ARM Cortex-M4）：

docker run -it --rm \
  -v /path/to/phoenix-rtos-src:/workspace \
  -w /workspace \
  -e TARGET_ARCH=arm-cortex-m4 \
  phoenixrtos/build-env:latest \
  make all

支持的架构值：x86_64、arm-cortex-m3、arm-cortex-m4、riscv32（可通过docker run --rm phoenixrtos/build-env:latest list-archs查看完整列表）。

4.4 高级配置：环境变量

通过环境变量自定义构建行为，常用参数如下：

4.5 docker-compose 配置示例

通过docker-compose.yml定义构建服务，适合长期开发或多步骤构建流程：

version: '3.8'
services:
  phoenix-build:
    image: phoenixrtos/build-env:latest
    volumes:
      - ./phoenix-rtos-src:/workspace  # 宿主机源码目录（相对路径）
      - ./build-cache:/cache          # 挂载缓存目录（加速重复构建）
    environment:
      - TARGET_ARCH=arm-cortex-m4
      - BUILD_JOBS=8
      - LOG_PATH=/cache/build.log
    working_dir: /workspace
    command: make all  # 构建命令

启动构建：

docker-compose up

5. 注意事项

• 权限问题：宿主机挂载目录的权限需允许容器内用户（默认uid=1000）读写，建议通过-u $(id -u):$(id -g)参数指定宿主机用户ID，避免文件权限冲突：

  docker run -it --rm -u $(id -u):$(id -g) -v /path/to/src:/workspace ...
  

• 构建缓存：重复构建可挂载缓存目录（如/cache），避免重复下载依赖。
• 版本匹配：确保镜像版本与Phoenix-RTOS源码版本兼容（如v1.2.0镜像对应源码v1.2.x分支）。
• 日志查看：构建日志默认输出至LOG_PATH指定路径，或通过docker logs <container-id>查看运行中容器日志。