Skip to main content

开发环境

TOS 7 采用与 Ubuntu 22.04 LTS (Jammy Jellyfish) 兼容的根文件系统。为确保二进制兼容性和依赖库版本一致，开发者必须基于 Ubuntu 22.04 构建开发环境。

系统基础​

推荐的开发环境选项：

选项说明适用场景
Ubuntu 22.04 物理机 / 虚拟机（arm64）原生 ARM64 环境；直接编译运行，无需交叉编译拥有 ARM 硬件或愿意使用 ARM 虚拟机的开发者
Docker 容器（arm64v8/ubuntu:22.04）通过 QEMU 模拟在 x86 主机上运行 ARM64 容器偏好容器化工作流的 x86 开发者
x86 主机 + 交叉编译在 x86 开发机上安装交叉编译工具链，交叉编译产出面向 TNAS 平台的二进制文件x86 开发者最常见的配置
核心原则

无论采用哪种方式，开发环境中使用的 APT 软件源和软件包版本都必须与 TOS 7 的根文件系统（Ubuntu 22.04 兼容）保持一致，以避免因 glibc、OpenSSL 等核心库版本不匹配导致的运行时错误。

支持的目标架构​

TNAS 提供 arm64 和 amd64 两种硬件架构。应用必须为每种目标架构提供单独构建。多架构支持需为每个目标分别提交。

架构构建目标三元组Deb 架构字段典型 TNAS 型号
ARM 64 位（aarch64）aarch64-linux-gnuarm64基于 ARM 的 TNAS 型号
x86 64 位（x86_64）x86_64-pc-linux-gnuamd64基于 x86 的 TNAS 型号

配置 Ubuntu 22.04 APT 软件源​

TOS 7 的 Ubuntu 22.04 兼容根文件系统使用 Ubuntu ports.ubuntu.com（ARM 架构专用镜像）。开发环境必须配置相同的软件源，以确保软件包版本对齐。

TOS 7 当前 APT 源配置（/etc/apt/sources.list）：

deb http://ports.ubuntu.com/ubuntu-ports/ jammy main restricted
deb http://ports.ubuntu.com/ubuntu-ports/ jammy-updates main restricted
deb http://ports.ubuntu.com/ubuntu-ports/ jammy universe
deb http://ports.ubuntu.com/ubuntu-ports/ jammy-updates universe
deb http://ports.ubuntu.com/ubuntu-ports/ jammy multiverse
deb http://ports.ubuntu.com/ubuntu-ports/ jammy-updates multiverse
deb http://ports.ubuntu.com/ubuntu-ports/ jammy-backports main restricted universe multiverse
deb http://ports.ubuntu.com/ubuntu-ports/ jammy-security main restricted
deb http://ports.ubuntu.com/ubuntu-ports/ jammy-security universe
deb http://ports.ubuntu.com/ubuntu-ports/ jammy-security multiverse
适用于 x86 开发机

将 ports.ubuntu.com/ubuntu-ports 替换为 archive.ubuntu.com/ubuntu，但保持 jammy 发行版代号不变，以确保软件包版本对齐。

基础构建工具链​

开发者应在 Ubuntu 22.04 开发环境中安装以下工具，以确保构建产物与 TOS 7 二进制兼容：

工具Ubuntu 22.04 来源用途
build-essentialjammy/main包含 gcc-11/g++-11、make 等基础编译工具
makejammy/mainGNU Make 构建自动化
cmakejammy/main跨平台构建系统
gitjammy/main版本控制
pkg-configjammy/main库依赖查询工具
# 在开发机上安装
apt install -y build-essential make cmake git pkg-config

交叉编译环境​

当开发者本地机器架构与目标 TNAS 架构不同时，需要配置交叉编译工具链。

架构匹配指南：

开发机架构目标 TNAS 架构交叉编译方式
x86_64（amd64）aarch64（arm64）安装 crossbuild-essential-arm64
x86_64（amd64）x86_64（amd64）本机编译，无需交叉编译
aarch64（arm64）x86_64（amd64）安装 crossbuild-essential-amd64
aarch64（arm64）aarch64（arm64）本机编译，无需交叉编译
# 示例：在 x86_64 主机上配置 arm64 交叉编译
dpkg --add-architecture arm64
apt update
apt install -y crossbuild-essential-arm64

语言运行时指南​

TOS 7 提供了特定的预装运行时。开发者必须了解哪些运行时在系统中原生可用，并据此规划依赖策略。

1.Python（已预装）​

TOS 7 预装了 Python 3.10.12，以及以下系统模块：

模块用途
python3-certifiSSL 证书验证
python3-cffi-backendC 扩展接口
python3-cryptography加密算法库
python3-dbusD-Bus 进程间通信
python3-dnspythonDNS 工具包
python3-giGObject 内省绑定
python3-gpgGnuPG 加密接口
python3-ldbLDAP 数据库绑定
python3-markdownMarkdown 转 HTML
python3-django-pyscssDjango SCSS 支持

开发指南：

  • Deb 应用可通过在 DEBIAN/control 中声明 Depends: python3 直接依赖 Python 3.10
  • 对于上述未列出的其他第三方库，请将其打包进 Deb 包中，或使用 pip install --target 安装到私有目录
  • 有关处理非预装依赖的通用指导，请参阅第 2 章 · 架构策略

2.Java（未预装）​

TOS 7 未预装 Java 运行时。部署 Java 应用的开发者有两种选择：

方案一：依赖 TOS 应用中心的 Java 运行时

TOS 应用中心提供了独立的 Java 运行时应用。第三方应用可在其包清单中声明对此运行时的依赖。当用户安装应用时，系统会自动检查并提示优先安装 Java 运行时。

请参阅第 4 章 · 包规范了解具体的依赖声明字段。

方案二：将 Java 运行时与应用一同打包

开发者可以将 OpenJDK 构建版本与应用包一起分发。应用直接使用打包的 java 二进制文件启动，无需用户额外安装。

3.Go（未预装——交叉编译部署）​

Go 原生支持交叉编译。开发者在本机编译目标平台的二进制文件并部署到 TNAS：

# 为 arm64 编译静态二进制文件
GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -o appname-arm64 main.go

# 为 amd64 编译静态二进制文件
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o appname-amd64 main.go
建议：
  • 使用 CGO_ENABLED=0 生成无系统库依赖的静态链接二进制文件
  • 对于核心逻辑无法用 Python 实现或需要高性能的应用，推荐使用 Go 语言

4.C / C++（标准开发）​

C/C++ 应用遵循标准开发实践——开发者在本机编译目标架构的二进制文件并部署到 TNAS。

关键注意事项
  • 链接 glibc 2.35（Ubuntu 22.04 兼容根文件系统提供的版本）以确保二进制兼容性
  • 当开发机架构与目标架构不同时，使用交叉编译工具链
  • 请参阅第 5 节 · 交叉编译环境了解架构匹配指导

5.PHP（未预装）​

TOS 7 未预装 PHP。部署 PHP 应用的开发者有两种选择：

方案一：依赖 TOS 应用中心的 PHP 运行时

TOS 应用中心提供了 PHP 8.0 运行时应用。在包清单中声明对此运行时的依赖。当用户安装应用时，系统会自动检查并提示优先安装 PHP 运行时。

请参阅第 4 章 · 包规范了解具体的依赖声明字段。

方案二：将 PHP 运行时与应用一同打包

将 PHP 二进制文件与应用包一起分发。应用直接使用打包的 PHP 解释器启动，无需用户额外安装。

注意： PHP 是解释型语言。源代码可直接部署，无需交叉编译即可在 arm64 和 amd64 两种架构上运行。

打包与验证工具​

Deb 应用工具：

工具用途
dpkg-devDebian 包构建工具（dpkg-deb、dpkg-source）
debhelperDebian 打包辅助脚本
lintianDebian 包合规检查器
systemd服务管理和单元文件测试
apt install -y dpkg-dev debhelper lintian

Docker 应用工具：

工具最低版本用途
Docker Engine20.10+容器运行时
Docker Composev2+容器编排
trivy / docker scout最新版漏洞扫描

构建验证命令：

# Deb 包：检查合规性
lintian <appid>_<version>_amd64.deb

# Deb 包：验证包元数据
dpkg-deb --info <appid>_<version>_amd64.deb

# Docker：扫描镜像已知漏洞
trivy image <image>:<tag>

测试环境选项​

最终验证需要使用运行 TOS 7.0（当前稳定版/测试版） 的 TNAS 设备。后续 TOS 7.x 小版本预计保持兼容性，但建议在正式提交前在目标版本上进行回归测试。

无 TNAS 硬件的开发者测试方案：

序号方案说明推荐用途
1Ubuntu 22.04 虚拟机在 Ubuntu 22.04 虚拟机上对 Deb 应用进行基础功能测试早期开发和 CI/CD
2Docker Desktop（Windows/macOS/Linux）模拟 TOS 7.0 Docker 环境进行容器应用测试Docker 应用开发
3Open TOS 本地部署Open TOS 与 TNAS TOS 7.0 系统完全一致，可在普通电脑或虚拟机上安装，镜像从铁威马官网下载最接近实体设备的替代方案；提交前最终测试
4远程体验机通过官方论坛申请铁威马官方 TOS 7.0 远程体验机。无需自备硬件即可完成完整测试缺少硬件和本地虚拟机资源的开发者
建议

日常开发和 CI/CD 使用方案 1–2。全面的提交前验证使用方案 3（Open TOS）或方案 4（远程体验机）。

详细的测试流程请参阅第 13 章 · 本地测试与调试。

补充：Linux 内核模块开发​

对于需要为 TOS 7 构建树外（out-of-tree）Linux 内核模块（如自定义网络驱动）的开发者，系统通过 linux-headers-<version>.deb 提供内核头文件，与标准 Ubuntu 发行版行为一致。

快速参考：

# 安装构建工具
apt install -y build-essential

# 解压驱动源码
tar -xzf driver-source.tar.gz
cd driver-source

# 构建内核模块
make

# 安装并加载
make install
depmod -a
modprobe <module_name>

# 验证
lsmod | grep <module_name>
dmesg | tail -10
注意

内核模块开发要求构建环境的内核版本与 TOS 7 内核版本一致。请联系铁威马开发者支持获取与目标 TOS 版本对应的具体内核头文件包。