本文记录使用命令 OHOS_ARCH=aarch64 OHOS_ABI=arm64-v8a sh ./create-hnp.sh 构建 Kbd 2.8.0 的完整过程，包括环境、构建链路、关键日志、常见问题与解决方案、产物验证与重建方法，便于复现与运维。

📖 Kbd 简介

Kbd（Keyboard Utilities）是 Linux 键盘工具集，提供了一系列用于管理键盘映射、控制台字体和虚拟终端的基础工具。它包含了 dumpkeys、loadkeys、setfont 等工具，是 Linux 系统中键盘和终端管理的重要组成部分。

🎯 Kbd 的作用与重要性

Kbd 是键盘和终端管理的核心工具集，提供了：

  • 键盘映射管理：转储和加载键盘映射表
  • 字体管理：设置和控制台字体
  • 虚拟终端管理：切换和管理虚拟终端
  • 键盘模式设置：设置键盘工作模式
  • 键盘信息查询：查询键盘配置信息

🔧 Kbd 核心特性

1. 键盘映射工具
  • dumpkeys：转储当前键盘映射表
  • loadkeys：加载键盘映射表
  • 键盘布局：支持多种键盘布局
  • 键映射：支持自定义键映射
2. 字体管理工具
  • setfont：设置控制台字体
  • 字体加载：加载和控制台字体
  • 字体信息：查询字体信息
3. 虚拟终端工具
  • chvt：切换虚拟终端
  • deallocvt：释放虚拟终端
  • 终端管理：管理虚拟终端资源
4. 键盘信息工具
  • kbdinfo：显示键盘信息
  • kbd_mode：设置键盘模式
  • kbdrate：设置键盘重复速率
5. 应用场景
  • 键盘布局配置：配置系统键盘布局
  • 多语言支持：支持多语言键盘布局
  • 终端字体设置：设置终端显示字体
  • 虚拟终端管理：管理系统虚拟终端
  • 键盘故障排查：排查键盘相关问题

🚀 构建入口与环境

  • 📝 执行命令：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 变量定义需要构建的包列表（包含 kbd）
    • 通过 check-pkgs 机制自动检测 PKGS 变化并触发重新构建
    • 自动合并 external-hnp 目录下的外部 HNP 包
    • base.hnp 依赖所有包的 .stamp 和外部 HNP 包
    • 总目标 all: copy，打包 base.hnp 并拷贝到 entry/hnp/$(OHOS_ABI)

⚙️ Kbd 包的构建配置

  • 📁 包目录：build-hnp/kbd/Makefile
    • 继承通用规则：include ../utils/Makefrag
    • 源地址：https://www.kernel.org/pub/linux/utils/kbd/kbd-2.8.0.tar.xz
    • 版本：2.8.0
  • 🔧 补丁处理：
    • x86_64.diff：适配架构差异
    • 位置：build-hnp/kbd/Makefile:7
  • ⚙️ Autotools 配置参数：
    • --host $(OHOS_ARCH)-unknown-linux-musl - 目标平台
    • --disable-vlock - 禁用 vlock（虚拟终端锁定工具）
    • ac_cv_func_malloc_0_nonnull=yes - 确保 malloc(0) 返回非空指针
    • ac_cv_func_realloc_0_nonnull=yes - 确保 realloc(0) 返回非空指针
    • PKG_CONFIG=/usr/bin/true - 避免主机 pkg-config 干扰
  • 🔨 构建流程：
    1. 下载源码包（从 kernel.org）
    2. 解包并进入 temp/kbd-2.8.0 目录
    3. 应用补丁 x86_64.diff
    4. 运行 ./configure 配置构建系统
    5. 向 config.h 追加 program_invocation_short_name 定义
    6. 使用 make -j $(nproc) 并行编译
    7. 使用 make install 安装
    8. 复制到 ../sysroot
  • 🔧 通用工具链与路径：build-hnp/utils/Makefrag
    • CC/CXX/LD/AR/RANLIB/... 均指向 OHOS SDK 的 LLVM 工具链
    • 下载支持多镜像回退：wget → curl，主镜像失败时自动尝试备用镜像

📋 关键日志与过程节点

  • 📥 下载与解包：
    • 从 kernel.org 获取 kbd-2.8.0.tar.xz
    • 完成解包并进入 temp/kbd-2.8.0 目录
    • 下载规则支持多镜像回退：wget → curl 兜底
  • 🔧 补丁应用：
    • 应用补丁 x86_64.diff 适配架构差异
  • ⚙️ 配置阶段：
    • 运行 ./configure --host=aarch64-unknown-linux-musl --disable-vlock ...
    • 工具链与链接器探测成功（clang/ld.lld）
    • 配置成功，生成 Makefile 和构建配置
    • 向 config.h 追加 program_invocation_short_name 定义
  • 🔨 编译与安装：
    • 使用 make -j $(nproc) 并行编译
    • 成功编译生成 dumpkeys、loadkeys、setfont 等工具
    • 使用 make install 安装到临时前缀
    • 复制到 ../sysroot
  • 📦 打包：
    • 完成 base.hnp 重打包，拷贝产物到 entry/hnp/arm64-v8a/
    • Kbd 工具集已成功打包到 base.hnp 中

✅ 产物验证

📦 检查打包文件

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

🔍 检查二进制文件

# 检查主要工具
ls -lh build-hnp/sysroot/bin/dumpkeys build-hnp/sysroot/bin/loadkeys build-hnp/sysroot/bin/setfont
file build-hnp/sysroot/bin/dumpkeys build-hnp/sysroot/bin/loadkeys build-hnp/sysroot/bin/setfont

# 检查其他工具
ls -lh build-hnp/sysroot/bin/chvt build-hnp/sysroot/bin/deallocvt build-hnp/sysroot/bin/kbd_mode build-hnp/sysroot/bin/kbdinfo build-hnp/sysroot/bin/kbdrate

image-20251126143858563

✅ 构建验证结果：

  • ✅ Kbd 工具已安装：
    • dumpkeys (180K) - 转储键盘映射表
    • loadkeys (220K) - 加载键盘映射表
    • setfont (64K) - 设置控制台字体
    • chvt (21K) - 切换虚拟终端
    • deallocvt (20K) - 释放虚拟终端
    • kbd_mode (22K) - 设置键盘模式
    • kbdinfo (21K) - 显示键盘信息
    • kbdrate (22K) - 设置键盘重复速率
  • ✅ 文件类型：ELF 64-bit LSB pie executable, ARM aarch64
  • ✅ 动态链接：interpreter /lib/ld-musl-aarch64.so.1
  • ✅ 包含调试信息：with debug_info, not stripped
  • ✅ 已打包到 base.hnp 中

💻 终端中执行的示例命令

⌨️ Dumpkeys - 转储键盘映射表

1. 基本使用
# 转储当前键盘映射表
dumpkeys

# 转储到文件
dumpkeys > keymap.txt

# 转储特定格式
dumpkeys --long-info

# 转储简短格式
dumpkeys --short-info

# 转储功能键映射
dumpkeys --funcs-only

# 转储修饰键映射
dumpkeys --compose-only

# 转储字符串映射
dumpkeys --strings-only

# 转储键码映射
dumpkeys --keys-only

image-20251126144204564

⌨️ Loadkeys - 加载键盘映射表

2. 基本使用
# 加载键盘映射表文件
loadkeys keymap.txt

# 加载默认键盘映射
loadkeys default

# 加载特定布局
loadkeys us

# 加载特定键盘映射
loadkeys /usr/share/kbd/keymaps/i386/qwerty/us.map.gz

# 清除当前映射
loadkeys --clearcompose

# 清除所有映射
loadkeys --clear

# 显示加载的映射
loadkeys --verbose

image-20251126145052778

⌨️ Setfont - 设置控制台字体

3. 基本使用
# 设置字体
setfont lat9w-16

# 设置字体并指定大小
setfont -16

# 设置字体文件
setfont /usr/share/kbd/consolefonts/lat9w-16.psf.gz

# 显示可用字体
setfont --list

# 显示当前字体
setfont --show

# 恢复默认字体
setfont default

# 设置字体并保持
setfont --keep-vc-resize lat9w-16

image-20251126145126478

⌨️ 其他工具

7. chvt - 切换虚拟终端
# 切换到虚拟终端 1
chvt 1

# 切换到虚拟终端 2
chvt 2

# 切换到虚拟终端 3
chvt 3

# 显示当前虚拟终端
chvt --current

# 列出所有虚拟终端
chvt --list
8. kbd_mode - 设置键盘模式
# 设置为 ASCII 模式
kbd_mode -a

# 设置为 XLATE 模式
kbd_mode -x

# 设置为 UNICODE 模式
kbd_mode -u

# 设置为 RAW 模式
kbd_mode -r

# 显示当前模式
kbd_mode
9. kbdinfo - 显示键盘信息
# 显示键盘信息
kbdinfo

# 显示详细键盘信息
kbdinfo --verbose

# 显示键盘设备信息
kbdinfo --device /dev/tty0

# 显示键盘映射信息
kbdinfo --keymap

# 显示键盘功能信息
kbdinfo --funcs
10. kbdrate - 设置键盘重复速率
# 设置键盘重复速率（延迟毫秒，速率字符/秒）
kbdrate -d 250 -r 30

# 设置快速重复速率
kbdrate -d 200 -r 40

# 设置慢速重复速率
kbdrate -d 500 -r 10

# 显示当前设置
kbdrate

# 禁用键盘重复
kbdrate -r 0

# 设置默认速率
kbdrate -d 250 -r 11

image-20251126145332080

🧪 实际应用示例

# 备份当前键盘映射
dumpkeys > backup_keymap.txt

# 加载自定义键盘映射
loadkeys custom_keymap.txt

# 设置控制台字体
setfont lat9w-16

# 切换到虚拟终端并设置字体
chvt 2
setfont lat9w-16

# 配置键盘为 Unicode 模式
kbd_mode -u

# 设置键盘重复速率
kbdrate -d 250 -r 30

# 查看键盘信息
kbdinfo

# 创建自定义键盘映射
dumpkeys > my_keymap.txt
# 编辑 my_keymap.txt
loadkeys my_keymap.txt

# 切换键盘布局（US 到 UK）
loadkeys uk
# 切换回 US
loadkeys us

# 设置大字体
setfont lat9w-32

# 设置小字体
setfont lat9w-08

# 在脚本中使用
#!/bin/bash
# 备份键盘映射
dumpkeys > /tmp/keymap_backup.txt
# 加载新映射
loadkeys new_keymap.txt
# 恢复原映射
loadkeys /tmp/keymap_backup.txt

# 批量设置多个虚拟终端
for i in {1..6}; do
    chvt $i
    setfont lat9w-16
done

# 监控键盘映射变化
watch -n 1 'dumpkeys | head -20'

# 对比两个键盘映射
dumpkeys > keymap1.txt
# 修改配置后
dumpkeys > keymap2.txt
diff keymap1.txt keymap2.txt

🧪 功能验证脚本

#!/bin/bash
# Kbd 工具验证脚本

KBD_BIN="build-hnp/sysroot/bin"

echo "=== Kbd 工具验证 ==="

# 检查主要工具
echo ""
echo "=== 主要工具验证 ==="
for tool in dumpkeys loadkeys setfont; do
    if [ -f "$KBD_BIN/$tool" ]; then
        echo "✓ $tool: 存在"
        file "$KBD_BIN/$tool"
        echo "  文件大小: $(ls -lh "$KBD_BIN/$tool" | awk '{print $5}')"
    else
        echo "✗ $tool: 缺失"
    fi
done

# 检查其他工具
echo ""
echo "=== 其他工具验证 ==="
for tool in chvt deallocvt kbd_mode kbdinfo kbdrate; do
    if [ -f "$KBD_BIN/$tool" ]; then
        echo "✓ $tool: 存在"
        file "$KBD_BIN/$tool"
        echo "  文件大小: $(ls -lh "$KBD_BIN/$tool" | awk '{print $5}')"
    else
        echo "✗ $tool: 缺失"
    fi
done

# 测试基本功能（在目标设备上）
echo ""
echo "=== 功能测试（需要在目标设备上运行）==="
echo "测试 dumpkeys:"
echo "  $KBD_BIN/dumpkeys | head -20"
echo ""
echo "测试 loadkeys:"
echo "  $KBD_BIN/loadkeys --help"
echo ""
echo "测试 setfont:"
echo "  $KBD_BIN/setfont --list"
echo ""
echo "测试 chvt:"
echo "  $KBD_BIN/chvt 1"
echo ""
echo "测试 kbd_mode:"
echo "  $KBD_BIN/kbd_mode"
echo ""
echo "测试 kbdinfo:"
echo "  $KBD_BIN/kbdinfo"
echo ""
echo "测试 kbdrate:"
echo "  $KBD_BIN/kbdrate"

🐛 常见问题与处理

❌ 问题 1：pkg-config 干扰

  • 🔍 症状：配置失败，依赖解析错误
  • 🔎 原因：主机 pkg-config 干扰交叉编译依赖解析
  • ✅ 解决方法：
    • 构建阶段显式设置 PKG_CONFIG=/usr/bin/true
    • 避免主机 pkg-config 干扰交叉编译
    • 位置：build-hnp/kbd/Makefile:8

❌ 问题 2：运行期权限与设备文件

  • 🔍 症状：loadkeys/setfont 无法访问设备节点
  • 🔎 原因：目标设备缺少 /dev/console 或相关接口，或权限不足
  • ✅ 解决方法：
    • 确保目标设备具备 /dev/console 或相关接口
    • 使用 sudo 运行工具（如果需要）
    • 检查设备文件权限
    • 位置：运行时

❌ 问题 3：program_invocation_short_name 未定义

  • 🔍 症状：编译错误，program_invocation_short_name 未定义
  • 🔎 原因：目标环境缺少该符号定义
  • ✅ 解决方法：
    • 向 config.h 追加 program_invocation_short_name 定义
    • 位置：build-hnp/kbd/Makefile:9

❌ 问题 4：kernel.org 下载失败

  • 🔍 症状：无法从 kernel.org 下载源码包
  • 🔎 原因：网络问题或镜像站点不可用
  • ✅ 解决方法：
    • 手动下载源码包放置到 build-hnp/kbd/download/kbd-2.8.0.tar.xz
    • 使用代理或镜像站点下载
    • 通用下载规则支持 curl 兜底
    • 位置：build-hnp/kbd/Makefile:16

❌ 问题 5：架构差异问题

  • 🔍 症状：编译错误，架构相关代码不兼容
  • 🔎 原因：x86_64 特定代码在 ARM 架构上不兼容
  • ✅ 解决方法：
    • 应用补丁 x86_64.diff 适配架构差异
    • 位置：build-hnp/kbd/Makefile:7

❌ 问题 6：malloc/realloc 检查失败

  • 🔍 症状：配置失败，malloc/realloc 检查失败
  • 🔎 原因：交叉编译环境检查失败
  • ✅ 解决方法：
    • 显式设置 ac_cv_func_malloc_0_nonnull=yes 和 ac_cv_func_realloc_0_nonnull=yes
    • 位置：build-hnp/kbd/Makefile:8

❌ 问题 7：vlock 构建失败

  • 🔍 症状：vlock 工具构建失败
  • 🔎 原因：vlock 依赖某些系统特性不可用
  • ✅ 解决方法：
    • 禁用 vlock：--disable-vlock
    • 位置：build-hnp/kbd/Makefile:8

❌ 问题 8：架构不支持

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

🔄 重建与扩展

  • 🔧 重建单包：

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

  • 🧹 清理：

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

  • 📦 扩展：Kbd 是键盘和终端管理的基础工具集，被广泛用于键盘映射和字体管理

  • 🔄 自动重建机制：

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

💡 实践建议

  • 🔧 构建配置：根据目标环境调整补丁以适配架构差异
  • 🚀 依赖管理：确保通过 PKG_CONFIG=/usr/bin/true 避免主机工具干扰
  • 📦 键盘管理：Kbd 为键盘映射和字体管理提供了强大的工具支持
  • 🔗 设备权限：确保目标设备具备必要的设备文件和权限
  • 🌐 多语言支持：使用 loadkeys 支持多语言键盘布局

📝 结论与建议

  • ✅ 本次已在 aarch64 环境下完成 Kbd 2.8.0 的交叉编译与打包，工具集已安装到 sysroot 并纳入 HNP 包。
  • 💡 为保证构建稳定：
    • 使用补丁修正架构差异问题
    • 使用 Autotools 构建系统，配置灵活
    • 确保通过 create-hnp.sh 触发构建以获得完整环境变量
    • 利用 check-pkgs 机制自动检测包列表变化，无需手动清理
    • Kbd 为键盘映射和字体管理提供了强大的工具支持
    • 常见陷阱包括 pkg-config 干扰、运行期权限问题、架构差异；当前已通过构建配置和补丁处理
    • 建议确保目标设备具备必要的设备文件和权限，并根据需要配置键盘布局和字体
    • 已完成 aarch64 目标下 Kbd 的交叉编译与打包，工具集进入 sysroot 并纳入 HNP 包

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

# 开源 # 鸿蒙
Logo
开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

cover

Flutter for OpenHarmony 实战：Hydrated BLoC — 赋予状态长久记忆的能力

avatar 开源鸿蒙跨平台开发者社区
cover

Flutter for OpenHarmony 实战：ObjectBox — 突破极限的毫秒级持久化引擎

avatar 开源鸿蒙跨平台开发者社区
cover

Flutter for OpenHarmony 实战：Lint — 守护鸿蒙项目的代码“红线”

avatar 开源鸿蒙跨平台开发者社区