本文记录使用命令 OHOS_ARCH=aarch64 OHOS_ABI=arm64-v8a sh ./create-hnp.sh 构建 Tmux 3.5a 的完整过程，包括环境、构建链路、关键日志、常见问题与解决方案。

📖 Tmux 简介

Tmux（Terminal Multiplexer）是一个终端复用器，允许用户在一个终端窗口中创建和管理多个终端会话。Tmux 提供了会话管理、窗口分割、窗格管理等功能，是系统管理员和开发者的强大工具。

🎯 Tmux 的作用与重要性

Tmux 是终端会话管理的核心工具，提供了：

• 会话管理：创建、分离、附加终端会话，即使断开连接也能保持会话运行
• 窗口管理：在一个终端中创建多个窗口，每个窗口可以运行不同的程序
• 窗格分割：将窗口分割成多个窗格，同时查看多个终端
• 远程工作：非常适合 SSH 远程连接，即使网络断开也能保持会话
• 多任务处理：高效管理多个任务和项目
• 协作功能：支持多用户同时访问同一个会话

🔧 Tmux 核心特性

1. 会话管理

• 创建会话：tmux new -s session_name - 创建命名会话
• 分离会话：Ctrl+b d - 分离当前会话，会话继续在后台运行
• 附加会话：tmux attach -t session_name - 重新连接到会话
• 列出会话：tmux ls - 列出所有会话
• 杀死会话：tmux kill-session -t session_name - 终止指定会话

2. 窗口管理

• 创建窗口：Ctrl+b c - 创建新窗口
• 切换窗口：Ctrl+b n / Ctrl+b p - 下一个/上一个窗口
• 选择窗口：Ctrl+b 0-9 - 直接切换到指定窗口
• 重命名窗口：Ctrl+b , - 重命名当前窗口
• 关闭窗口：Ctrl+b & - 关闭当前窗口

3. 窗格管理

• 垂直分割：Ctrl+b % - 垂直分割窗格
• 水平分割：Ctrl+b " - 水平分割窗格
• 切换窗格：Ctrl+b o - 切换到下一个窗格
• 调整大小：Ctrl+b Ctrl+方向键 - 调整窗格大小
• 关闭窗格：Ctrl+b x - 关闭当前窗格

4. 复制模式

• 进入复制模式：Ctrl+b [ - 进入复制模式
• 选择文本：使用方向键选择文本
• 复制文本：Space 开始选择，Enter 复制
• 粘贴文本：Ctrl+b ] - 粘贴复制的文本

5. 配置与定制

• 配置文件：~/.tmux.conf - 用户配置文件
• 重新加载配置：Ctrl+b :source-file ~/.tmux.conf - 重新加载配置
• 主题定制：支持丰富的主题和状态栏定制
• 键绑定：可以自定义所有快捷键

🚀 构建入口与环境

• 📝 执行命令：OHOS_ARCH=aarch64 OHOS_ABI=arm64-v8a sh ./create-hnp.sh
• 🔧 入口脚本：create-hnp.sh
  • 检查必需的环境变量 OHOS_ARCH 和 OHOS_ABI
  • 导出 LC_CTYPE、TOOL_HOME、OHOS_SDK_HOME
  • 执行 make -C build-hnp
• 📦 顶层构建：build-hnp/Makefile
  • PKGS 变量定义需要构建的包列表（包含 tmux）
  • 通过 check-pkgs 机制自动检测 PKGS 变化并触发重新构建
  • 自动合并 external-hnp 目录下的外部 HNP 包
  • base.hnp 依赖所有包的 .stamp 和外部 HNP 包
  • 总目标 all: copy，打包 base.hnp 并拷贝到 entry/hnp/$(OHOS_ABI)

⚙️ Tmux 包的构建配置

• 📁 包目录：build-hnp/tmux/Makefile
  • 继承通用规则：include ../utils/Makefrag
  • 源地址：https://github.com/tmux/tmux/releases/download/3.5a/tmux-3.5a.tar.gz
  • 版本：3.5a
• 🔧 补丁应用：
  • 将源码中的 TCSANOW 替换为 TCSADRAIN
  • 规避在 OHOS 环境下终端属性立即生效可能导致的异常
  • 确保更安全的刷新策略
  • 通过 sed -i.bak 对所有 .c 文件进行就地替换
• ⚙️ Autotools 配置参数：
  • --prefix=$(PREFIX) - 安装前缀（/data/app/base.org/base_1.0）
  • --host $(OHOS_ARCH)-unknown-linux-musl - 目标平台
  • CFLAGS="-I $(shell pwd)/../sysroot/include -I $(shell pwd)/../sysroot/include/ncursesw" - 包含头文件路径
    • 注入 sysroot/include 与 sysroot/include/ncursesw，保证 terminfo/ncurses 解析
• 🔨 构建流程：
  1. 下载源码包（从 GitHub releases）
  2. 解包并进入 temp/tmux-3.5a 目录
  3. 应用补丁（替换 TCSANOW 为 TCSADRAIN）
  4. 运行 ./configure 配置构建系统
  5. 使用 make -j $(nproc) 并行编译
  6. 使用 make install 安装
  7. 复制到 ../sysroot 并 strip ELF 文件
• 🔧 通用工具链与路径：build-hnp/utils/Makefrag
  • CC/CXX/LD/AR/RANLIB/... 均指向 OHOS SDK 的 LLVM 工具链
  • 下载支持多镜像回退：wget → curl，主镜像失败时自动尝试备用镜像

📋 关键日志与过程节点

• 📥 下载与解包：
  • 从 GitHub Releases 下载 tmux-3.5a.tar.gz
  • 完成解包并进入 temp/tmux-3.5a 目录
  • 下载规则支持多镜像回退：wget → curl 兜底
• 🔧 补丁应用：
  • 查找所有 .c 文件
  • 使用 sed 将 TCSANOW, 替换为 TCSADRAIN,
  • 创建备份文件（.bak 扩展名）
• ⚙️ 配置阶段：
  • host=aarch64-unknown-linux-musl，交叉构建启用
  • 编译器与链接器：检测 clang/ld.lld 成功
  • 头文件路径：正确设置 sysroot/include 和 sysroot/include/ncursesw
  • ncurses 库检测：成功检测到 ncursesw 库
• 🔨 编译与安装：
  • 生成 tmux 二进制文件
  • 安装到 sysroot/bin
  • 使用 llvm-strip 剥离符号，减小文件大小
• 📦 打包：
  • 完成 base.hnp 重打包，拷贝产物到 entry/hnp/arm64-v8a/
  • Tmux 工具已成功打包到 base.hnp 中

✅ 产物验证

📦 检查打包文件

ls build-hnp/base.hnp  # 应存在
ls entry/hnp/arm64-v8a/*.hnp  # 应包含 base.hnp 与 base-public.hnp

🔍 检查二进制文件

# 检查 Tmux 可执行文件
ls -lh build-hnp/sysroot/bin/tmux
file build-hnp/sysroot/bin/tmux

✅ 构建验证结果：

• ✅ Tmux 可执行文件已安装：
  • tmux (850K) - 终端复用器主程序
• ✅ 文件类型：ELF 64-bit LSB pie executable, ARM aarch64
• ✅ 动态链接：dynamically linked, interpreter /lib/ld-musl-aarch64.so.1
• ✅ 已剥离符号：stripped
• ✅ terminfo 文件（位于 build-hnp/sysroot/lib/terminfo/）：
  • 74/tmux、74/tmux-256color、74/tmux-direct、78/xterm+tmux2
• ✅ 已打包到 base.hnp 中

🐛 构建过程遇到的问题及解决方法

❌ 问题 1：终端属性设置问题（TCSANOW）

• 🔍 症状：在 OHOS 环境下终端属性立即生效可能导致异常
• 🔎 原因：TCSANOW 在 OHOS 环境下行为不一致
• ✅ 解决方法：
  • 应用补丁将所有 TCSANOW, 替换为 TCSADRAIN,
  • 使用更安全的刷新策略
  • 通过 sed -i.bak 对所有 .c 文件进行就地替换
  • 位置：build-hnp/tmux/Makefile:7

❌ 问题 2：GitHub 下载失败

• 🔍 症状：无法从 GitHub 下载源码包
• 🔎 原因：网络问题或 GitHub 访问受限
• ✅ 解决方法：
  • 手动下载源码包放置到 build-hnp/tmux/download/ 目录
  • 使用代理或镜像站点下载
  • 通用下载规则支持 curl 兜底
  • 位置：build-hnp/tmux/Makefile:3-5

❌ 问题 3：ncurses 头文件路径错误

• 🔍 症状：编译时找不到 ncurses 头文件
• 🔎 原因：头文件路径未正确设置
• ✅ 解决方法：
  • 在 CFLAGS 中注入 sysroot/include 和 sysroot/include/ncursesw
  • 确保 ncurses 已正确安装到 sysroot
  • 位置：build-hnp/tmux/Makefile:8

❌ 问题 4：terminfo 数据库缺失

• 🔍 症状：tmux 无法正确显示或终端兼容性问题
• 🔎 原因：terminfo 数据库未安装或路径不正确
• ✅ 解决方法：
  • 确保 ncurses 的 terminfo 数据库已安装
  • 设置 TERMINFO 环境变量指向正确的路径
  • 检查 sysroot/lib/terminfo/ 目录

❌ 问题 5：交叉编译配置失败

• 🔍 症状：configure 脚本无法检测到交叉编译器
• 🔎 原因：环境变量未正确设置或工具链路径不正确
• ✅ 解决方法：
  • 确保通过 create-hnp.sh 触发构建以获得完整环境变量
  • 检查 OHOS_SDK_HOME 是否正确设置
  • 确保交叉编译器路径正确
  • 位置：build-hnp/utils/Makefrag:10

❌ 问题 6：终端兼容性问题

• 🔍 症状：会话切换或键位异常
• 🔎 原因：设备 TERM 与 ncursesw 的兼容性问题
• ✅ 解决方法：
  • 检查设备的 TERM 环境变量
  • 确保补丁已生效（TCSANOW→TCSADRAIN）
  • 使用兼容的 terminfo 条目（如 tmux-256color）

❌ 问题 7：链接错误

• 🔍 症状：链接时出现未定义符号错误
• 🔎 原因：CFLAGS 注入路径不正确或 pkg-config 路径错误
• ✅ 解决方法：
  • 确认 CFLAGS 注入路径正确
  • 确保 pkg-config 指向 sysroot
  • 检查依赖库是否正确安装
  • 位置：build-hnp/utils/Makefrag:6

❌ 问题 8：架构不支持

• 🔍 症状：Unsupported OHOS_ARCH=
• 🔎 原因：传入的架构不在支持列表中
• ✅ 解决方法：
  • 确保传入支持架构（aarch64 或 x86_64）
  • 位置：build-hnp/Makefile:1-49

🔄 重建与扩展

• 🔧 重建单包：

  make -C build-hnp rebuild-tmux  # 触发子包重新编译并刷新 .stamp
  

• 🧹 清理：

  make -C build-hnp clean  # 清理 sysroot、所有 .stamp 和 PKGS_MARKER
  

• 📦 扩展：Tmux 是终端会话管理的核心工具，被广泛用于远程工作和多任务管理

• 🔄 自动重建机制：

  • 修改 PKGS 后，check-pkgs 会自动检测变化并触发重新构建
  • 新增外部 HNP 包到 external-hnp 目录后，会自动合并到 base.hnp

💡 实践建议

• 🔧 构建配置：确保补丁正确应用，特别是 TCSANOW→TCSADRAIN 替换
• 🚀 性能优化：Tmux 提供了高效的终端会话管理能力
• 📦 依赖管理：确保 ncurses 和 libevent 正确安装
• 🔗 配置定制：根据需求定制 .tmux.conf 配置文件
• 🌐 远程工作：Tmux 非常适合 SSH 远程连接和长时间运行的任务

📝 结论与建议

• ✅ 本次已在 aarch64 环境下完成 Tmux 3.5a 的交叉编译与打包，可执行文件已安装到 sysroot 并纳入 HNP 包。
• 💡 为保证构建稳定：
  • 使用 Autotools 构建系统，配置灵活
  • 应用补丁修复 OHOS 环境下的终端属性问题
  • 确保通过 create-hnp.sh 触发构建以获得完整环境变量
  • 利用 check-pkgs 机制自动检测包列表变化，无需手动清理
  • Tmux 为终端会话管理提供了强大的工具支持
  • 常见陷阱包括终端属性设置问题、ncurses 头文件路径错误、终端兼容性问题；当前已通过补丁和配置参数处理
  • 建议根据需求定制 .tmux.conf 配置文件，充分利用 Tmux 的强大功能
  • HNP 流水线下，补丁与交叉参数设置到位，tmux 可稳定编译、安装与打包分发
  • 产物开箱即用，支持在设备上高效进行终端会话管理与多任务工作流

---

📚 以上为 Tmux 构建的深度解读与实践记录。