OpenTina 构建说明（`build/`）

本目录为固件与镜像构建入口：源码在 sources/，产物在 output/<BOARD_NAME>/，板级配置在 configs/。

前置条件

宿主机（默认）

最小依赖（Debian / Ubuntu，与 docker/Dockerfile 对齐，外加 U-Boot pylibfdt 需要的 swig）：

sudo apt install -y \
    bc bison build-essential ca-certificates chrpath cpio device-tree-compiler \
    diffstat dosfstools flex g++-aarch64-linux-gnu gcc-aarch64-linux-gnu \
    genimage git libgnutls28-dev libssl-dev make mtools patch perl \
    python3 python3-cryptography python3-pyelftools python3-setuptools \
    rpcsvc-proto rsync swig texinfo u-boot-tools wget xz-utils

其中 chrpath、diffstat、texinfo（makeinfo）、rpcsvc-proto（rpcgen）为 Yocto/BitBake HOSTTOOLS 所需。若未装系统包，sources/meta-opentina/opentina-build.sh 会尝试把部分工具解压到 ~/.local/bin。

Ubuntu 24.04+ / Yocto： AppArmor 默认限制无特权 user namespace，BitBake 会报 User namespaces are not usable。一次性放开：

echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/99-bitbake-userns.conf
sudo sysctl -p /etc/sysctl.d/99-bitbake-userns.conf

opentina-build.sh 也会在缺少该能力时尝试用 Docker/sudo -n 自动写入上述 sysctl。

若整机构建包在 proxychains4 下跑：sysctl 已是 0 时一般没问题；不要用 CLI unshare 自行探测（LD_PRELOAD 多线程会导致误报）。网络代理更建议只包下载步骤，而不是整个 bitbake。

如果不走 Docker 而直接在宿主跑 debian / ubuntu rootfs（设 OPENTINA_DEBIAN_USE_DOCKER=0 或 OPENTINA_UBUNTU_USE_DOCKER=0），再补：

sudo apt install -y debootstrap qemu-user-static binfmt-support

其余：

AArch64 交叉工具链（默认 aarch64-linux-gnu-gcc，板级 OPENTINA_CROSS_COMPILE 可覆盖）。
已克隆的源码树（见下文 ./build.sh init）。

可选：Docker 构建环境

安装 Docker，用于 OPENTINA_DOCKER=1 或 --docker 时在 Ubuntu 24.04 镜像内构建（镜像内已含 gcc-aarch64-linux-gnu、genimage 等，见 docker/Dockerfile）。

快速开始

cd /path/to/build    # 本 README 所在目录

# 1. 拉取源码（默认 manifest，可换路径）
./build.sh init

# 2. 查看支持的板子与 rootfs 类型
./build.sh targets

# 3. 编译（将 BOARD_NAME 换成 targets 里列出的名字）
./build.sh <BOARD_NAME> build

产物示例：output/radxa_a7a/sdcard.img、rootfs.ext2、Image.gz、dtb、u-boot.fex、（开启 OP-TEE 时还有）tee.bin 等。

OP-TEE 为整项目可选（默认开）。开启时启动链：BROM → boot0 → SPL FIT（BL31 + BL32/OP-TEE + U-Boot）→ TF-A → OP-TEE → U-Boot → Linux。关闭时（--no-optee / OPENTINA_OPTEE=0）：BROM → boot0 → SPL FIT（BL31 + U-Boot）→ TF-A → U-Boot → Linux。

整链 build 默认断点续编：仅当 output/<BOARD>/.done.<组件> 里记录的源码/配置指纹与当前一致时才跳过。改了 sources/ 或相关 config/fragment 会自动重编该组件，并清掉下游（例如改 linux → 重编 bootfs / rootfs / image）。组件内部仍走各自的增量 make。换 rootfs / profile / OP-TEE 时也会清掉 .done.*。

增量编译与断点续编

方式	行为
`./build.sh <BOARD> build`	整链；默认 resume：跳过指纹仍匹配的组件
`./build.sh --force <BOARD> build`	强制重编所选组件（忽略 `.done.*`）
`./build.sh --no-resume <BOARD> build`	同「不跳过」语义（整链）
`./build.sh <BOARD> build linux bootfs image`	显式组件默认重编这些组件（不跳过）
`./build.sh --resume <BOARD> build linux`	显式组件也按指纹决定是否跳过
`./build.sh <BOARD> status`	查看各组件 current / stale / pending

.done.<comp> 内是指纹（不是空文件），覆盖：sources/ 对应树、板级/common 配置与补丁，以及本仓库的 scripts/recipes.sh 等配方脚本。改 build 仓配方或相关 configs/common/* 也会使组件变 stale。.build-meta 记录 rootfs / profile / optee。ATF 仅在 SPD（opteed ↔ none）变化时 clean，同 SPD 下保持增量链接。

OP-TEE（整项目可选，默认开）

一条开关同时控制 BL32、ATF dispatcher、U-Boot SPL FIT、内核驱动、Buildroot 用户态和各 rootfs 的 TA 安装。

方式	说明
`./build.sh --optee <BOARD> build`	显式开启（与默认相同）
`./build.sh --no-optee <BOARD> build`	关闭：不编 `optee`，ATF `SPD=none`，U-Boot `SUNXI_BL32_BASE=0`，不合并 `linux-optee.fragment`，Buildroot 去掉 `OPTEE_*` 包
`OPENTINA_OPTEE=0 ./build.sh <BOARD> build`	与 `--no-optee` 相同
板级 `configs/*/config` 里 `OPENTINA_OPTEE="${OPENTINA_OPTEE:-1}"`	板级默认；命令行 / 环境变量优先

优先级：--optee / --no-optee 与已导出的 OPENTINA_OPTEE > 板级默认 > 1。
从开切到关（或反过来）后需要重编 atf + uboot（以及 linux / rootfs），否则会留下旧的 SPD=opteed / FIT BL32。
关闭 OP-TEE 时，build_linux 会从板级 DTB 删掉 TZDRAM/SHM reserved-memory 和 firmware/optee，避免内核 Image 落在 0x40000000 的 32 MiB no-map 里并报 failed to reserve memory for node 'optee@40000000'。

Buildroot（组件 `br2`）

配方位置：scripts/recipes.sh 中的 build_br2 / clean_br2（组件名用 br2，避免与命令行 OPENTINA_ROOTFS=buildroot 混淆）。
profile：./build.sh --profile lite|hmi <BOARD> build（默认 lite）。hmi 在板级 defconfig 上合并 configs/common/br2-hmi.fragment。等价环境变量 OPENTINA_BR2_PROFILE；命令行优先。
板级变量：configs/<板>/config 里 BUILDROOT_DEFCONFIG（默认 br2_opentina.defconfig，与 config 同目录）。
defconfig 模板：configs/*/br2_opentina.defconfig — AArch64 + Bootlin 外部工具链 + 无内核（内核由本仓库 linux 组件构建）+ ext2 rootfs；busybox init（无 systemd），带 openssh / curl / python3 等调试工具，root 密码 root（configs/common/br2-post-build.sh 放开 SSH root 密码登录）。OP-TEE 开启时再编用户态 4.6.0（BR2_PACKAGE_OPTEE_CLIENT / OPTEE_TEST / OPTEE_EXAMPLES；libteec、tee-supplicant，SysV S30tee-supplicant；xtest / optee_example_* 的 TA 由 buildroot 自己的 TA devkit 编——devkit 只能由 BR2_TARGET_OPTEE_OS 产出，故该项开启但 _CORE=n，只出 devkit、不产与 optee 组件竞争的 tee.bin；_SERVICES=n 让 avb / pkcs11 等 in-tree service TA 不进 rootfs。optee_os 用 _CUSTOM_TARBALL pin 到 manifest 同一 commit，client / test / examples pin 到 4.6.0 tarball，hash 放在 configs/common/br2-global-patches/——不 pin 的话 buildroot 默认拉 4.9.0，与 4.6.0 的安全核错配）。BL32 仍由 optee 组件构建。关闭 OP-TEE 时配方会连 BR2_TARGET_OPTEE_OS 一起关掉。
TA（仅 OP-TEE 开启）：br2-post-build.sh（以及 ubuntu/debian/yocto/openwrt 的镜像 overlay）把 output/<BOARD>/optee 里 export-ta_*/ta/*.ta 装到 /lib/optee_armtz；xtest / optee-examples 的 TA 由对应 BR 包自己产出并装进同一目录，不需要先编 optee。安全存储目录 /data/tee。改过 TA 后要重编对应 rootfs 并重烧 root 分区，只烧 u-boot.fex 不会更新它们。
板上验证（仅 OP-TEE 开启）：xtest（回归；首次建议 xtest -l 看用例），以及 optee_example_hello_world 等。
仅构建 rootfs：./build.sh <BOARD> build br2（需已 init 克隆 sources/buildroot）。
分区：configs/*/partitions.cfg 中 partition root 使用镜像 rootfs.ext2，起始偏移 148M（紧接 128 MiB 的 boot 分区之后）。若板卡上块设备节点与 mmcblk0p4 不一致，请同步修改板级 EXTLINUX_ROOT（见下节）。

Ubuntu rootfs（组件 `ubuntu`）

源码：manifest 中的 openaw/ubuntu → sources/ubuntu（revision=master）。
配方：scripts/recipes.sh 中的 build_ubuntu / clean_ubuntu；命令行使用 OPENTINA_ROOTFS=ubuntu 时，默认组件链里的 rootfs 步骤为 ubuntu 而非 br2。
构建：优先 sources/ubuntu/docker/build-rootfs-buildx.sh（需本机 Docker buildx；./build.sh --docker 会把宿主机 Docker socket/CLI 挂进容器）。原生 arm64 可设 OPENTINA_UBUNTU_USE_DOCKER=0 后直接跑 mk-base-ubuntu.sh / mk-ubuntu-rootfs.sh。
环境变量（可选，可在板级 config 中 export）：UBUNTU_RELEASE（默认 24.04）、UBUNTU_ARCH（默认 arm64）、OPENTINA_MOTD_BANNER_FILE（自定义登录 ASCII/文本，见 sources/ubuntu/readme.md）。
profile：./build.sh --profile lite|desktop <BOARD> ubuntu build（默认 lite）。desktop 只走 buildx。等价环境变量 OPENTINA_UBUNTU_PROFILE；命令行优先。
产物：仓库内 ubuntu-rootfs.ext4 拷贝为 output/<BOARD>/rootfs.ext2，与 Buildroot 共用 partitions.cfg 的 root 分区。若已构建 linux，会把 .staging-linux-modules 中的 *.ko 叠进该镜像。
示例：./build.sh <BOARD> ubuntu build；仅 rootfs：./build.sh <BOARD> ubuntu build ubuntu。
内核：OPENTINA_ROOTFS=ubuntu 构建 linux 时会在 LINUX_CONFIG（如 a733_minimal_defconfig）之上合并 configs/common/linux-systemd.fragment（CONFIG_TMPFS、CONFIG_UNIX 等）。精简 defconfig 单独用于 systemd 会出现 tmpfs: Unknown parameter 'mode'、Failed to find module 'unix' 并卡在 Failed to mount API filesystems。可用环境变量 LINUX_SYSTEMD_FRAGMENT 覆盖片段路径。

Debian rootfs（组件 `debian`）

源码：manifest 中的 openaw/debian → sources/debian（revision=master）。
配方：scripts/recipes.sh 中的 build_debian / clean_debian；OPENTINA_ROOTFS=debian 时默认组件链使用 debian 替代 br2。
构建：优先 sources/debian/docker/build-rootfs-buildx.sh（需本机 Docker buildx；./build.sh --docker 同样挂宿主机 Docker）；原生 arm64 可 OPENTINA_DEBIAN_USE_DOCKER=0 后执行 mk-lite-rootfs.sh。
环境变量（可选）：DEBIAN_RELEASE（默认 trixie，亦可用 bookworm）、DEBIAN_ARCH（默认 arm64）、ROOTFS_EXT4_MB、DEBIAN_MIRROR 等（见 sources/debian/readme.md）。
profile：./build.sh --profile lite|desktop <BOARD> debian build（默认 lite）。desktop 只走 buildx。等价环境变量 OPENTINA_DEBIAN_PROFILE；命令行优先。
产物：sources/debian/out/debian-*-lite-*.ext4（取最新）拷贝为 output/<BOARD>/rootfs.ext2。若已构建 linux，同样叠入 staged *.ko。
示例：./build.sh <BOARD> debian build；仅 rootfs：./build.sh <BOARD> debian build debian。
内核：与 Ubuntu 相同，debian 构建 linux 时合并 linux-systemd.fragment。
启动参数：build_bootfs 会在 extlinux 的 append 中追加 systemd.gpt_auto=0，避免 systemd 自动挂载不存在的 /boot（GPT 上 FAT 启动区由 U-Boot 使用，不在 rootfs 内挂载）。

OEM 注入（客户扩展安装包与 overlay）

让客户在不 fork 本仓库的前提下，把私有 .deb、文件 overlay、收尾脚本注入到 Debian/Ubuntu rootfs。

适用范围：OPENTINA_ROOTFS=debian 或 ubuntu，且走 buildx 路径（默认）；非 buildx 的 fallback（build-rootfs.sh debootstrap、mk-lite-rootfs.sh 等）若检测到 OEM 请求会直接报错——避免客户资产被静默丢弃。

目录约定：

<OEM_DIR>/
  packages/            *.deb — 由 apt-get install ./packages/*.deb 安装
  rootfs-overlay/      cp -a 到 / （文件树合并）
  post.sh              chroot 内执行（chmod +x；可选）

路径选择优先级：环境变量 OPENTINA_OEM_DIR > 板级 configs/<板>/oem/ > 无（no-op）。
依赖策略：不使用 apt-get -f install——packages/*.deb 的依赖必须由 base apt 源（trixie/noble main）或同目录下的其它 .deb 共同满足；不能满足时 docker build 直接失败，立即暴露缺失依赖，避免镜像被 apt 隐式修复弄脏。
与 EXTRA_DEBS 的区别：EXTRA_DEBS 用于从上游 apt 源拉额外公开包；OEM 用于客户私有 / 闭源 / 自编译产物。两者可并存。

示例：

OPENTINA_OEM_DIR=/path/to/oem ./build.sh <BOARD> debian build debian

回归测试：tests/oem/build-test-debs.sh 生成两套样例 bundle（good/ 依赖可解；broken/ 故意 Depends: nonexistent-…），用于验证 happy-path 安装 + fail-fast 行为。详见 sources/debian/readme.md 与 sources/ubuntu/readme.md 中对应章节。

Yocto rootfs（组件 `yocto`）

源码：manifest 中的 openaw/meta-opentina → sources/meta-opentina（revision=master）。首次构建会由 opentina-build.sh 自动执行 yocto-init.sh，在 sources/yocto/ 下拉取 Poky / meta-openembedded（体积大，见 layer 内 README.md）。
配方：build_yocto / clean_yocto 调用 sources/meta-opentina/opentina-build.sh；OPENTINA_ROOTFS=yocto 时默认组件链使用 yocto 替代 br2。
配置（可选，板级 config 或环境变量）：
- profile：./build.sh --profile minimal|qt|hmi <BOARD> yocto build（默认 minimal，opentina-image-minimal；qt 为 opentina-image-qt，需 yocto-init.sh --qt；hmi 为 opentina-image-hmi）。等价环境变量 OPENTINA_YOCTO_PROFILE；命令行优先。
- YOCTO_MACHINE / OPENTINA_YOCTO_MACHINE：默认 a733-aiot（layer 当前机器名；与 OpenTina 板级 BOARD_NAME 独立，内核仍由本仓库 linux 组件构建）
- OPENTINA_YOCTO_DIR：Yocto 工作区，默认 sources/yocto
产物：sources/yocto/build-opentina/tmp/deploy/images/<MACHINE>/opentina-image-*-<MACHINE>.ext4 → output/<BOARD>/rootfs.ext2。若已构建 linux，叠入 staged *.ko。
示例：./build.sh <BOARD> yocto build yocto（仅 rootfs，耗时长）；完整镜像：./build.sh <BOARD> yocto build
内核：与 Ubuntu/Debian 相同，yocto 构建 linux 时合并 linux-systemd.fragment（CONFIG_NET、CONFIG_UNIX、CONFIG_TMPFS 等）。未合并时 sysvinit/udev/dbus 会报 Function not implemented、/var/volatile 失败。
默认登录：root / root，opentina / opentina（conf/include/opentina-default-users.inc，镜像构建后处理写入 shadow）。可在 local.conf 覆盖 OPENTINA_ROOT_PASSWORD 等。SSH 已启用 allow-root-login。
注意：不要用 root 跑 bitbake；OPENTINA_DOCKER=1 的 OpenTina 镜像未预装完整 Yocto 宿主机依赖，建议在宿主机编 yocto 组件。Layer 阶段为 rootfs-only（linux-dummy），与 linux / uboot / atf（以及可选的 optee）组件并行不冲突。
若报 meta-openembedded/meta-oe 不存在：说明只拉了 poky、未拉 meta-oe。在 sources/meta-opentina 执行 ./yocto-init.sh 后重试；或 ./build.sh … yocto build yocto（会自动补跑 init）。

OpenWrt rootfs（组件 `openwrt`）

源码：manifest 中的 openwrt/openwrt → sources/openwrt（pin 在 openwrt-25.12 稳定分支，clone-depth=1）。也可设环境变量 OPENTINA_OPENWRT_DIR 指向本地已有的 OpenWrt 树（如已预热 build_dir/ 的 fork），跳过 manifest 克隆。
配方：scripts/recipes.sh 中的 build_openwrt / clean_openwrt；OPENTINA_ROOTFS=openwrt 时默认组件链使用 openwrt 替代 br2。OpenWrt 只有一份板级 config，--profile 会直接报错。
定位：OpenWrt 只作为 rootfs 供应商——boot 链（ATF / U-Boot / 内核 / dtb，以及可选的 OP-TEE）全部复用本仓库组件；OpenWrt 自产的内核、kmod 与 per-device 镜像全部丢弃，只消费 target 级 openwrt-*-rootfs.tar.gz。
OpenWrt 补丁：先应用 configs/common/openwrt-patches/*.patch，再应用 configs/<board>/openwrt-patches/*.patch；每组内按字典序 git apply 到 OpenWrt 树（应用前先把补丁涉及文件 reset 回 HEAD，保证可重复执行）。
配置（板级 config）：
- OPENWRT_CONFIG：板级目录下的 .config 种子（如 openwrt.config），拷贝后经 make defconfig 归一化
- OPENWRT_TARGET / OPENWRT_SUBTARGET：默认 sunxi / armv8
- OPENWRT_ROOTFS_MB：mkfs.ext4 镜像大小，默认 2048（与 partitions.cfg root 分区一致）
- OPENWRT_JOBS：覆盖 OpenWrt make 并行数（默认 JOBS）
产物：bin/targets/<TGT>/<SUBTGT>/openwrt-*-rootfs.tar.gz 解包后 mkfs.ext4 -d 生成 output/<BOARD>/rootfs.ext2。解包时会删除 OpenWrt 自带的 lib/modules/（kmod 按它自己的内核 ABI 编译，如 6.12.x，与 sources/linux 不匹配），再拷入 linux 组件 staged 的 *.ko。
内核：OPENTINA_ROOTFS=openwrt 构建 linux 时合并 configs/common/linux-openwrt.fragment（tmpfs / unix socket / 板载 GMAC DWMAC_SUN55I + REALTEK_PHY / bridge / nftables 等 builtin，供 procd / netifd / firewall4 使用；kmod 已丢弃，缺特性只能往 fragment 加 builtin）。可用 LINUX_OPENWRT_FRAGMENT 覆盖路径。
rootfs overlay：打包 ext4 时把 configs/common/openwrt-files/ 叠进镜像——79_move_config 改挂 p3 FAT boot（不再误挂 raw p1 boot0），并用静默 fw_printenv 去掉 Failed to find NVMEM device；02_network_opentina 把 eth0 设为 LAN。
示例：./build.sh <BOARD> openwrt build；仅 rootfs：./build.sh <BOARD> openwrt build openwrt。首次构建会 bootstrap OpenWrt 自带工具链，耗时较长。
注意：OpenWrt rootfs 已在 A7A 真机完成启动验证；armv8 subtarget 与两个 A733 设备定义位于 configs/common/openwrt-patches/，设备仍为 rootfs-only 占位（IMAGES :=，不产 per-device 镜像）。

extlinux 与 U-Boot cmdline

build_bootfs 生成的 extlinux/extlinux.conf 里，append 由板级 EXTLINUX_ROOT 与 EXTLINUX_CONSOLE 拼接（默认 root=/dev/mmcblk0p4 rw rootwait + console=ttyS0,115200 loglevel=9）。
使用 U-Boot distroboot / extlinux 时，内核实际拿到的 cmdline 主要来自这里的 append；请与 U-Boot defconfig 里可能存在的 CONFIG_BOOTARGS / bootcmd 保持一致，避免 root / console 冲突。若需要更早串口输出，可在 EXTLINUX_CONSOLE 中加入 SoC 对应的 earlycon=...（需查阅 UART 基址与驱动）。

`./build.sh` 命令总览

所有子命令前可重复加 --docker（等价于本次执行启用容器），或单独使用 --docker-shell（见下文「Docker」）。
--optee / --no-optee、--profile <NAME>、--force / --resume / --no-resume 同样写在子命令之前。OpenWrt 没有 profile。
这些前缀必须出现在子命令之前（解析后会被剥掉，再按下面语法处理）。--docker 会把 --profile / resume 相关旗标原样传进容器。

用法	说明
`./build.sh`	无参数：列出板子与 rootfs 类型，并提示常用命令。
`./build.sh targets` 或 `./build.sh list`	同上列表，仅打印后退出。
`./build.sh init [MANIFEST_XML]`	按 XML 清单克隆/跳过已有仓库到 `sources/`（默认 `scripts/opentina-manifest.xml`）。
`./build.sh update [MANIFEST_XML]`	当前分支与清单 `revision` 相同的仓库快进到 GitHub 上该分支最新提交；分支不同（含游离 HEAD）的仓库只打印、不改动。
`./build.sh <BOARD_NAME> build [COMPONENT…]`	构建；未写 `COMPONENT` 时整链并默认 resume。
`./build.sh <BOARD_NAME> clean [COMPONENT…]`	清理对应组件及 `.done` 标记。
`./build.sh <BOARD_NAME> status`	查看 `.done.*`、指纹与镜像路径。
`./build.sh <BOARD_NAME> <ROOTFS> build …`	显式指定 rootfs 后再 `build` / `clean` / `status`（见下表）。
`./build.sh --profile <NAME> <BOARD_NAME> [ROOTFS] build …`	选择该 rootfs 的 profile。
`./build.sh --force <BOARD_NAME> build`	忽略 `.done.*`，强制重编。

--profile 与各 rootfs

ROOTFS	`--profile`	默认	写入
`buildroot`（可省略）	`lite`、`hmi`	`lite`	`OPENTINA_BR2_PROFILE`
`ubuntu`	`lite`、`desktop`	`lite`	`OPENTINA_UBUNTU_PROFILE`
`debian`	`lite`、`desktop`	`lite`	`OPENTINA_DEBIAN_PROFILE`
`yocto`	`minimal`、`qt`、`hmi`	`minimal`	`OPENTINA_YOCTO_PROFILE`
`openwrt`	不支持	—	—

已导出的同名环境变量在未写 --profile 时仍然生效；写了 --profile 时以命令行为准。

第一参数 BOARD_NAME

必须与 configs/*/config 中的 BOARD_NAME=... 一致（不是仅目录名；脚本会扫描所有板级配置）。

ROOTFS（可选）

ROOTFS	行为
（省略）	等价于 `buildroot`，即 `./build.sh BOARD build` 与 `./build.sh BOARD buildroot build` 相同。
`buildroot`	命令行里的「发行版槽位」：当前与省略相同，会跑完整组件链（含 `br2` Buildroot 根文件系统）。
`ubuntu`	在 `sources/ubuntu` 中构建 lite rootfs，拷贝为 `output/<BOARD>/rootfs.ext2`（组件名 `ubuntu`）。
`debian`	在 `sources/debian` 中构建 lite rootfs，拷贝为 `output/<BOARD>/rootfs.ext2`（组件名 `debian`）。
`yocto`	在 `sources/meta-opentina` + `sources/yocto` 中 bitbake rootfs，拷贝为 `output/<BOARD>/rootfs.ext2`（组件名 `yocto`）。
`openwrt`	在 `sources/openwrt`（或 `OPENTINA_OPENWRT_DIR`）中构建 rootfs tar，`mkfs.ext4 -d` 转为 `output/<BOARD>/rootfs.ext2`（组件名 `openwrt`）。

COMPONENT（可选，可多个，空格分隔）

默认依次构建全部；指定时只处理列出的组件（顺序即执行顺序）：

组件	含义
`optee`	OP-TEE OS（BL32，`tee.bin` 加载到 DRAM `0x40000000`）。仅 `OPENTINA_OPTEE=1` 时出现在默认组件链
`atf`	Trusted Firmware-A（BL31；开启 OP-TEE 时 `SPD=opteed`，关闭时 `SPD=none`）
`uboot`	U-Boot（依赖 `atf`；开启 OP-TEE 时还依赖 `optee`，SPL FIT 含 BL31+BL32+U-Boot，否则只有 BL31+U-Boot）
`linux`	Linux 内核与 dtb（开启 OP-TEE 时合并 `linux-optee.fragment`）
`br2`	Buildroot：在 `sources/buildroot` 中按板级 `BUILDROOT_DEFCONFIG` 生成 `rootfs.ext2`（开启 OP-TEE 时含 `tee-supplicant` / `libteec` / `xtest` / `optee_example_*`），拷贝到 `output/<BOARD>/rootfs.ext2`
`ubuntu`	Ubuntu rootfs：在 `sources/ubuntu` 中生成 `ubuntu-rootfs.ext4` 并拷贝为 `rootfs.ext2`（`OPENTINA_ROOTFS=ubuntu` 时替代 `br2`）
`debian`	Debian rootfs：在 `sources/debian/out/` 中取最新 `.ext4` 并拷贝为 `rootfs.ext2`（`OPENTINA_ROOTFS=debian` 时替代 `br2`）
`yocto`	Yocto rootfs：bitbake `opentina-image-minimal` / `-qt`，ext4 拷贝为 `rootfs.ext2`（`OPENTINA_ROOTFS=yocto` 时替代 `br2`）
`openwrt`	OpenWrt rootfs：取 `bin/targets/…/openwrt-*-rootfs.tar.gz` 经 `mkfs.ext4 -d` 转为 `rootfs.ext2`（`OPENTINA_ROOTFS=openwrt` 时替代 `br2`）
`bootfs`	启动用 FAT 目录树（依赖 `linux`）
`image`	`genimage` 生成 `sdcard.img`（依赖 `bootfs`、`uboot`，以及 `br2` / `ubuntu` / `debian` / `yocto` / `openwrt`）

依赖不满足时会报错退出（要求 output/<BOARD>/.done.<依赖组件> 存在）。Resume 跳过某组件时仍要求其依赖的 .done.* 已存在。

并行数

环境变量 JOBS：未设置时使用 nproc，并写入 MAKEFLAGS=-j$JOBS。

Docker（Ubuntu 24.04）

默认在宿主机执行；需要与 Dockerfile 一致的环境时，任选其一进入容器再跑同一套参数：

# 单次命令在容器内执行
./build.sh --docker radxa_a7a build

# 整个 shell 会话都在容器里构建
export OPENTINA_DOCKER=1
./build.sh radxa_a7a clean
./build.sh radxa_a7a build

# 只打开容器里的交互 shell（仓库已 bind-mount 到相同路径）
./build.sh --docker-shell

变量 / 参数	说明
`OPENTINA_DOCKER=1`	本次进程在宿主机上时，若存在 `docker` 命令则 `exec` 进默认镜像再执行 `build.sh`。设为 `0` 可关闭（在曾 `export OPENTINA_DOCKER=1` 的 shell 里恢复宿主机构建）。
`--docker`	与上类似，仅作用于当前命令（可写多次，效果同开）。
`--optee` / `--no-optee`	打开 / 关闭整项目 OP-TEE（须写在子命令前；会传入 Docker）。
`--docker-shell`	不进 `build.sh` 子命令，直接进入镜像内 `bash -il`。
`OPENTINA_SKIP_DOCKER=1`	强制宿主机：即使环境里带了 `OPENTINA_DOCKER=1` 也不进容器。
`OPENTINA_DOCKER_IMAGE`	默认 `opentina-buildenv:24.04`；镜像不存在或 `docker/Dockerfile` 更新后，由 `scripts/docker-exec.sh` 执行 `docker build`。
`OPENTINA_DOCKER_HOSTNAME`	容器主机名（提示符里 `@` 之后），默认 `opentina`。

容器内会设置 OPENTINA_IN_DOCKER=1，避免 build.sh 再套一层容器。若宿主机有 /var/run/docker.sock，docker-exec.sh 会把它和宿主机 docker CLI / buildx 插件挂进容器，这样 ubuntu / debian rootfs 仍可走宿主机 Docker buildx（仓库以相同路径 bind-mount，buildx 输出路径才能对上）。容器默认加上 --security-opt seccomp=unconfined，否则 BitBake 的 unshare(CLONE_NEWUSER) 会被 Docker seccomp 拦掉（即使宿主机 apparmor_restrict_unprivileged_userns=0）。
需要 git@ 克隆时，宿主机上建议配置 SSH agent 或挂载密钥；docker-exec.sh 会尝试传递 SSH_AUTH_SOCK 与只读挂载 ~/.ssh。

`./build.sh init` 与清单 XML

实际调用：scripts/repo_clone.sh --gitclone <manifest>。
默认清单：scripts/opentina-manifest.xml（<remote>、<default revision>、<project>）。
clone-depth：可在 <manifest> 或单个 <project> 上写正整数做浅克隆；不写或写 full / 0 等为完整历史（详见 manifest 注释）。
环境变量 OPENTINA_REMOTE_FETCH：若设置，覆盖 manifest 里所有 <remote fetch="...">（便于切换 HTTPS / SSH 基地址）。
OPENTINA_SOURCES_DIR：检出根目录，默认 $OPENTINA_BUILD_ROOT/sources。
OPENTINA_BUILD_ROOT：构建仓库根，一般无需改。

同步已存在仓库（非 init）：可直接执行：

./scripts/repo_clone.sh --sync ./scripts/opentina-manifest.xml

按清单分支更新已有检出（不切换分支）：

./build.sh update
# 等价于 ./scripts/repo_clone.sh --update ./scripts/opentina-manifest.xml

本地当前分支与清单 revision 相同：git fetch 后 git merge --ff-only origin/<revision>，更新到 GitHub 该分支最新提交。不能快进（本地有分叉提交或工作区挡住合并）时跳过并记为失败，不改历史。
本地在其他分支，或游离 HEAD：不 fetch、不 checkout，结束时按 path / local / manifest 列出来。

文档（`sources/docs`）

源码：manifest 中的 opentina-org/docs → sources/docs（revision=main）。
由 ./build.sh init 一并拉取；不是构建组件，不参与 build / clean。
项目概览、启动链、仓库地图与板级说明见该仓库 README（中文 / English）。构建细节仍以本文为准。
远端若尚无 main 分支（空仓库），init 会克隆空目录并跳过 --branch，避免整次 init 失败。

目录与产物

路径	说明
`sources/`	`trusted-firmware-a`、`u-boot`、`linux`、`buildroot`、`ubuntu`、`debian`、`meta-opentina`、`yocto/`（Yocto 工作区，由 init 生成）、`awbin`、`docs` 等（由 manifest 决定；根目录 `.gitignore` 已忽略）
`output/<BOARD_NAME>/`	内核、dtb、`rootfs.ext2`、`u-boot.fex`、`boot.img`、`sdcard.img`、`.done.*`、`.build-meta` 等
`configs/<板级目录>/`	`config`、`partitions.cfg`（`BOARD_NAME` 可与目录名不同）
`scripts/`	`recipes.sh`、`repo_clone.sh`、`docker-exec.sh`、`opentina-boards.sh` 等
`docker/Dockerfile`	默认构建环境镜像定义

板级 `configs/*/config` 常用变量

在对应板子的 config 中可设置（示例见 configs/radxa_a7a/config）：

变量	说明
`BOARD_NAME`	与命令行第一个参数一致，用于 awbin 路径、`output/` 子目录名等
`PRETTY_NAME`	仅用于 `./build.sh targets` 展示
`OPENTINA_CROSS_COMPILE`	默认 `aarch64-linux-gnu-`；TF-A、U-Boot、Linux 共用此前缀（与 `docker` 镜像内工具链一致）
`FDT_NAME`	拷贝到 `output/` 的设备树文件名
`UBOOT_CONFIG`	`make …_defconfig` 名
`LINUX_CONFIG`	内核 defconfig 名
`PARTITION_CONFIG`	`genimage` 配置文件路径（一般为 `$OPENTINA_BUILD_ROOT/configs/<目录>/partitions.cfg`）
`BUILDROOT_DEFCONFIG`	Buildroot 片段 defconfig 文件名（位于同一板级目录，默认 `br2_opentina.defconfig`）
`EXTLINUX_ROOT`	写入 `extlinux.conf` 的 root= 等（默认 `root=/dev/mmcblk0p4 rw rootwait`，需与 GPT 根分区序号一致）
`EXTLINUX_CONSOLE`	写入 `extlinux.conf` 的 console / loglevel / earlycon 等
`OPENTINA_OPTEE`	`1`（默认）编 OP-TEE 全链；`0` 关闭。也可在命令行用 `--optee` / `--no-optee`

GitHub Actions（CI 镜像）

工作流 .github/workflows/images.yml：

触发	行为
pull request → `tina-dev`	7 个 job：`demo_aiot_a733_v3` 的 buildroot / yocto / ubuntu / debian / openwrt（optee）+ demo buildroot / no-optee + `radxa_a7a` buildroot / optee。仅改 `*.md` / `LICENSE` / `.gitignore` 的 PR 不触发。产物在该次 run 的 Artifacts（保留 14 天），不发 Release
workflow_dispatch	完整矩阵；也可选只跑上述 PR 子集
push 新 tag	完整矩阵，成功项打成 `xz` 后发布同名 GitHub Release

git tag v1.0.0
git push origin v1.0.0

Release 页文件名例如 demo_aiot_a733_v3-buildroot-optee-sdcard.img.xz（单附件上限约 2 GiB）。解压：xz -d <file>-sdcard.img.xz。

完整矩阵：demo_aiot_a733_v3、radxa_a7a × buildroot、ubuntu、debian、openwrt、yocto × optee、no-optee。某组失败不影响其它组。tag Release 会挂上已成功的镜像；若有组合缺失，Release notes 会列出缺失项，并标成 prerelease。Yocto / OpenWrt 的 job timeout 分别为 360 / 240 分钟。

ccache 只给 buildroot / openwrt / yocto（max-size: 1G），避开 GitHub 每仓库 10 GB 缓存上限把 20 个 2 G 条目互相挤掉。Ubuntu / Debian 走 Docker buildx，宿主 ccache 收益低，不开。

CI 在 Ubuntu 24.04 runner 上装与 docker/Dockerfile 对齐的宿主依赖（scripts/ci-install-deps.sh），不再套一层 ./build.sh --docker，以便 Ubuntu/Debian rootfs 走宿主机 Docker buildx。Yocto job 会放开 kernel.apparmor_restrict_unprivileged_userns，并尽量把工作区放到 /mnt（回收 runner 的 swapfile）。默认 opentina-image-minimal 余量够用；若以后接 HMI/qt（mesa + llvm），需要更大 runner。

./build.sh init 要拉 opentina-org 下的 linux / u-boot 等仓。若这些仓是私有的，在仓库 Secrets 里加 OPENTINA_GH_TOKEN（能读对应 project 的 PAT）；公开仓用默认 GITHUB_TOKEN 即可。

固件 / rootfs 仓的 PR 不编完整 sdcard。各仓 .github/workflows/opentina-firmware.yml 复用本仓 firmware-component.yml（对齐 build PR 子集，只跑该组件）：

仓库	PR 构建（不对镜像 `dd`）
linux	每种 kconfig 先 demo 再 a7a（同一 Image、不同 DTB）：buildroot±OP-TEE、ubuntu（systemd）、openwrt fragment
u-boot	demo+OP-TEE、a7a+OP-TEE、demo+no-OP-TEE（会编 ATF/OP-TEE/awbin）
awbin	检查 boot0 / header，再编 demo+OP-TEE、a7a+OP-TEE、demo+no-OP-TEE 的 uboot 打包（会编 ATF/OP-TEE）
trusted-firmware-a	demo：`SPD=opteed` / `SPD=none`
optee_os	demo：OP-TEE + AArch64 TA
buildroot	demo+OP-TEE、a7a+OP-TEE、demo+no-OP-TEE 的 br2
ubuntu / debian	demo 与 a7a、OP-TEE 下的对应 rootfs
openwrt	demo 与 a7a、OP-TEE 下的 openwrt rootfs
meta-opentina	demo 与 a7a、OP-TEE 下的 yocto rootfs

私有仓配 OPENTINA_GH_TOKEN 以便 checkout build（以及 U-Boot / awbin job 拉 ATF/OP-TEE/u-boot）。

获取帮助

./build.sh this-is-not-a-board
# 或省略必填参数，触发 usage

会打印内置用法摘要（与本文对应；以脚本为准）。

许可

以仓库上层或本目录已有 LICENSE / 说明为准；厂商二进制（如 awbin）适用其自带条款。

Navigation Menu

Repository navigation

About

Repository files navigation

OpenTina 构建说明（`build/`）

前置条件

快速开始

增量编译与断点续编

OP-TEE（整项目可选，默认开）

Buildroot（组件 `br2`）

Ubuntu rootfs（组件 `ubuntu`）

Debian rootfs（组件 `debian`）

OEM 注入（客户扩展安装包与 overlay）

Yocto rootfs（组件 `yocto`）

OpenWrt rootfs（组件 `openwrt`）

extlinux 与 U-Boot cmdline

`./build.sh` 命令总览

Docker（Ubuntu 24.04）

`./build.sh init` 与清单 XML

文档（`sources/docs`）

目录与产物

板级 `configs/*/config` 常用变量

GitHub Actions（CI 镜像）

获取帮助

许可

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
configs		configs
docker		docker
scripts		scripts
tests/oem		tests/oem
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
build.sh		build.sh

Latest commit

History

Folders and files

Repository files navigation

OpenTina 构建说明（build/）

前置条件

快速开始

增量编译与断点续编

OP-TEE（整项目可选，默认开）

Buildroot（组件 br2）

Ubuntu rootfs（组件 ubuntu）

Debian rootfs（组件 debian）

OEM 注入（客户扩展安装包与 overlay）

Yocto rootfs（组件 yocto）

OpenWrt rootfs（组件 openwrt）

extlinux 与 U-Boot cmdline

./build.sh 命令总览

Docker（Ubuntu 24.04）

./build.sh init 与清单 XML

文档（sources/docs）

目录与产物

板级 configs/*/config 常用变量

GitHub Actions（CI 镜像）

获取帮助

许可

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

OpenTina 构建说明（`build/`）

Buildroot（组件 `br2`）

Ubuntu rootfs（组件 `ubuntu`）

Debian rootfs（组件 `debian`）

Yocto rootfs（组件 `yocto`）

OpenWrt rootfs（组件 `openwrt`）

`./build.sh` 命令总览

`./build.sh init` 与清单 XML

文档（`sources/docs`）

板级 `configs/*/config` 常用变量