本文记录在 aarch64 目标下使用命令 OHOS_ARCH=aarch64 OHOS_ABI=arm64-v8a sh ./create-hnp.sh 构建 libusb 1.0.29 的完整过程，涵盖镜像获取与回退、Autotools 构建链路、产物验证与常见问题处理，便于复现与维护。

📖 Libusb 简介

libusb 是一个用 C 语言编写的、跨平台的用户空间 USB 设备访问库。它提供了一个统一的 API 来访问 USB 设备，无需编写内核驱动程序。libusb 支持 Linux、macOS、Windows、Android 等多种操作系统，被广泛用于 USB 设备通信、固件更新、设备调试等场景。libusb 1.0.29 是稳定版本，提供了可靠的 USB 设备访问能力。

🎯 Libusb 的作用与重要性

libusb 是 USB 设备访问的核心库，提供了：

  • 用户空间访问：无需编写内核驱动程序即可访问 USB 设备
  • 跨平台支持：统一的 API 支持多种操作系统
  • 设备枚举：枚举和发现 USB 设备
  • 数据传输：支持控制传输、批量传输、中断传输、等时传输
  • 设备控制：打开/关闭设备、配置接口、声明接口
  • 热插拔支持：支持 USB 设备的热插拔检测
  • 广泛使用：被众多 USB 工具和应用程序使用（如 usbutils、hdc、Android ADB 等）
  • 开发友好：简洁的 API 设计，易于集成到应用程序中

🔧 Libusb 核心特性

1. 设备管理
  • 设备枚举：枚举系统中所有 USB 设备
  • 设备描述符：获取设备、配置、接口、端点描述符
  • 设备打开/关闭：打开和关闭 USB 设备句柄
  • 设备查找：根据 VID/PID 查找特定设备
2. 数据传输
  • 控制传输：USB 控制传输（用于设备配置和状态查询）
  • 批量传输：USB 批量传输（用于大量数据传输）
  • 中断传输：USB 中断传输（用于实时数据传输）
  • 等时传输：USB 等时传输（用于流媒体传输）
3. 接口管理
  • 接口声明：声明和释放接口
  • 接口配置：设置和获取接口配置
  • 端点管理：管理端点的数据传输
4. 平台支持
  • Linux：使用 usbfs 或 libudev 后端
  • macOS：使用 IOKit 后端
  • Windows：使用 WinUSB 后端
  • Android：支持 Android USB 主机模式
5. 高级功能
  • 热插拔回调：注册热插拔事件回调
  • 超时控制：设置数据传输超时
  • 错误处理：详细的错误码和错误信息
  • 线程安全：支持多线程访问（需要额外配置）
6. 应用场景
  • USB 设备通信：与 USB 设备进行数据通信
  • 固件更新：更新 USB 设备的固件
  • 设备调试：调试和测试 USB 设备
  • USB 工具开发：开发 USB 相关的工具和应用程序
  • 嵌入式开发：在嵌入式系统中访问 USB 设备

🚀 构建入口与顶层组织

  • 📝 执行命令：OHOS_ARCH=aarch64 OHOS_ABI=arm64-v8a sh ./create-hnp.sh
  • 🔧 入口脚本：create-hnp.sh 导出 SDK 路径并触发顶层构建
  • 顶层 Makefile：build-hnp/Makefile 已将 libusb 纳入 PKGS，base.hnp 依赖所有包完成标记 STAMP 并完成打包与拷贝到 entry/hnp/$(OHOS_ABI)

⚙️ 包配置与工具链

  • 包 Makefile：build-hnp/libusb/Makefile
    • 源地址：https://github.com/libusb/libusb/releases/download/v1.0.29/libusb-1.0.29.tar.bz2
    • 下载策略：使用通用下载规则，支持镜像回退（wget → curl）
    • 配置参数：
      • --prefix=$(PREFIX)：安装前缀
      • --disable-static：禁用静态库
      • --enable-shared：启用共享库
      • --disable-udev：禁用 udev 支持（目标环境精简，无 libudev）
      • --host $(OHOS_ARCH)-unknown-linux-musl：交叉编译目标
    • 安装后处理：为兼容依赖 libusb 头路径的项目（如 hdc），添加符号链接 include/libusb -> include/libusb-1.0
    • 使用通用 Autotools 宏构建（下载→解包→configure→make→install→strip→复制至 ../sysroot）
  • 工具链：aarch64-unknown-linux-ohos-clang 与 LLVM ar/ranlib/strip
  • 依赖：无特殊依赖（使用 usbfs 后端，无需 udev）

📋 关键执行与日志

  • 下载与解包：
    • 从 GitHub Releases 获取归档，解包至 temp/libusb-1.0.29 并创建 build 目录
  • 配置与编译：
    • 使用 Autotools 配置系统，配置交叉编译参数
    • 禁用 udev 支持，使用纯 usbfs 后端
    • 编译 libusb 共享库
  • 安装与复制：
    • 安装到临时前缀 build/data/app/base.org/base_1.0 后 strip 二进制文件
    • 创建符号链接 include/libusb -> include/libusb-1.0 以兼容 hdc 等工具
    • 复制到 ../sysroot 并记录文件列表（file.lst）

✅ 产物验证

📦 检查打包文件

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

🔍 检查 Libusb 库和头文件

# 检查共享库
ls -lh build-hnp/sysroot/lib/libusb*
file build-hnp/sysroot/lib/libusb-1.0.so.0

# 检查头文件
ls -lh build-hnp/sysroot/include/libusb*
ls -lh build-hnp/sysroot/include/libusb-1.0/

# 检查 pkg-config 文件
ls -lh build-hnp/sysroot/lib/pkgconfig/libusb-1.0.pc
cat build-hnp/sysroot/lib/pkgconfig/libusb-1.0.pc

✅ 构建验证结果：

  • ✅ Libusb 共享库已安装：
    • libusb-1.0.so.0.5.0 (104K) - 主共享库
    • libusb-1.0.so.0 - 版本符号链接
    • libusb-1.0.so - 开发符号链接
  • ✅ 文件类型：ELF 64-bit LSB shared object, ARM aarch64
  • ✅ 动态链接：dynamically linked
  • ✅ 已剥离符号：stripped
  • ✅ 头文件已安装：
    • include/libusb-1.0/libusb.h (85K) - 主头文件
    • include/libusb - 符号链接到 libusb-1.0（兼容 hdc 等工具）
  • ✅ pkg-config 文件已安装：
    • libusb-1.0.pc - pkg-config 配置文件
  • ✅ HNP 包产物：entry/hnp/arm64-v8a/base.hnp 与 base-public.hnp
  • ✅ 已打包到 base.hnp 中

🐛 常见问题与处理

❌ 问题 1：GitHub Releases 下载超时

  • 🔍 症状：连接 github.com 超时或读取失败
  • 🔎 原因：GitHub 访问不稳定或网络问题
  • ✅ 解决方法：
    • 使用通用下载规则，支持镜像回退（wget → curl）
    • 延长超时时间
    • 清理坏归档后重试
    • 位置：build-hnp/libusb/Makefile:3（使用通用下载规则）

❌ 问题 2：交叉工具链问题

  • 🔍 症状：configure 或编译时出现工具链错误
  • 🔎 原因：交叉工具链配置不正确或环境变量未设置
  • ✅ 解决方法：
    • 使用 OHOS SDK 的 LLVM，确保 --host 与三元组一致（aarch64-unknown-linux-musl）
    • 确保通过 create-hnp.sh 触发构建以获得完整环境变量
    • 位置：build-hnp/libusb/Makefile:6

❌ 问题 3：udev 依赖问题

  • 🔍 症状：configure 时提示找不到 udev 或 libudev
  • 🔎 原因：目标环境精简，无 libudev
  • ✅ 解决方法：
    • 使用 --disable-udev 禁用 udev 支持
    • 使用纯 usbfs 后端（适用于 Linux 系统）
    • 位置：build-hnp/libusb/Makefile:6

❌ 问题 4：头文件路径问题

  • 🔍 症状：编译时提示找不到 libusb.h，或 hdc 等工具无法找到头文件
  • 🔎 原因：头文件路径不匹配（某些工具期望 include/libusb 而不是 include/libusb-1.0）
  • ✅ 解决方法：
    • 创建符号链接 include/libusb -> include/libusb-1.0
    • 使用 AFTER_INSTALL 钩子在安装后创建符号链接
    • 位置：build-hnp/libusb/Makefile:7

❌ 问题 5：权限问题

  • 🔍 症状：运行时提示权限不足，无法访问 USB 设备
  • 🔎 原因：Linux 系统需要适当的权限才能访问 USB 设备
  • ✅ 解决方法：
    • 确保程序以 root 权限运行（不推荐）
    • 配置 udev 规则（如果使用 udev 后端）
    • 使用 usbfs 后端时，确保 /proc/bus/usb 可访问
    • 在 OpenHarmony 中可能需要特殊权限配置

❌ 问题 6：设备未找到

  • 🔍 症状：libusb_open_device_with_vid_pid 返回 NULL
  • 🔎 原因：设备未连接、VID/PID 错误、或设备被其他程序占用
  • ✅ 解决方法：
    • 检查设备是否已连接
    • 使用 libusb_get_device_list 枚举设备，确认 VID/PID
    • 检查是否有其他程序占用设备
    • 确保设备驱动未加载（libusb 需要独占访问）

❌ 问题 7：接口声明失败

  • 🔍 症状：libusb_claim_interface 返回错误
  • 🔎 原因：接口已被其他程序占用、接口号错误、或设备不支持该接口
  • ✅ 解决方法：
    • 检查接口号是否正确
    • 确保没有其他程序占用接口
    • 使用 libusb_get_config_descriptor 检查可用接口
    • 尝试使用 LIBUSB_CLAIM_INTERFACE_BIND_KERNEL_DRIVER 标志

❌ 问题 8：传输超时

  • 🔍 症状：数据传输操作超时
  • 🔎 原因：设备未响应、端点地址错误、或超时时间设置过短
  • ✅ 解决方法：
    • 检查端点地址是否正确
    • 增加超时时间
    • 检查设备是否正常工作
    • 使用 libusb_get_endpoint_descriptor 检查端点配置

❌ 问题 9：热插拔不支持

  • 🔍 症状：libusb_has_capability(LIBUSB_CAP_HAS_HOTPLUG) 返回 0
  • 🔎 原因：平台不支持热插拔或后端不支持
  • ✅ 解决方法：
    • 检查平台是否支持热插拔
    • 使用轮询方式检测设备插拔
    • 使用 libusb_get_device_list 定期检查设备列表变化

❌ 问题 10：符号链接问题

  • 🔍 症状：hdc 等工具无法找到 libusb.h
  • 🔎 原因：符号链接未正确创建或指向错误
  • ✅ 解决方法：
    • 检查符号链接：ls -l /data/app/base.org/base_1.0/include/libusb
    • 确保符号链接指向 libusb-1.0
    • 重新创建符号链接：ln -sf libusb-1.0 /data/app/base.org/base_1.0/include/libusb
    • 位置：build-hnp/libusb/Makefile:7

🔄 重建与清理

  • 🔧 重建单包：

    rm -rf build-hnp/libusb/temp build-hnp/libusb/build build-hnp/libusb/.stamp
OHOS_ARCH=aarch64 OHOS_ABI=arm64-v8a make -C build-hnp/libusb

  • 🧹 清理：

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

  • 📦 扩展：libusb 是 USB 设备访问的核心库，适合用于 USB 设备通信、固件更新、设备调试等场景

  • 🔄 自动重建机制：

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

💡 实践建议

  • 🔧 构建配置：使用 Autotools 构建系统，配置清晰，依赖明确
  • 🚀 使用场景：libusb 适合用于 USB 设备通信、固件更新、设备调试、USB 工具开发等场景
  • 📦 依赖管理：libusb 无特殊依赖（使用 usbfs 后端，无需 udev）
  • 🔗 开发建议：使用 pkg-config 获取编译和链接标志，简化构建过程
  • 🌐 平台建议：在 OpenHarmony 中使用 usbfs 后端，无需 udev 支持
  • 🔒 安全建议：注意 USB 设备访问权限，避免未授权访问

📝 结论与建议

  • ✅ libusb 1.0.29 在 aarch64 目标下完成交叉构建，库与头文件安装到 sysroot 并纳入 HNP 打包。
  • 💡 为保证构建稳定：
    • 使用 Autotools 构建系统，配置清晰
    • 无特殊依赖，构建过程简单
    • 使用多镜像回退策略确保下载成功
    • 确保通过 create-hnp.sh 触发构建以获得完整环境变量
    • 禁用 udev 支持，使用纯 usbfs 后端适配精简环境
    • 创建符号链接 include/libusb -> include/libusb-1.0 以兼容 hdc 等工具
    • 利用 check-pkgs 机制自动检测包列表变化，无需手动清理
    • libusb 为 USB 设备访问提供了统一的跨平台 API
    • 常见陷阱包括 GitHub 下载超时、交叉工具链问题、udev 依赖问题、头文件路径问题；当前已通过构建配置处理
    • 建议与 hdc、usbutils 一同使用，完善 USB 工具生态
    • 构建过程简洁，Autotools 交叉参数清晰，产物安装路径明确
    • 产物开箱即用，适合在设备上进行 USB 设备通信和开发

📚 以上为 libusb 构建的深度解读与实践记录。libusb 是 USB 设备访问的核心库，被广泛用于 USB 设备通信、固件更新、设备调试等场景，为开发者提供了统一的跨平台 USB 设备访问能力。

# 开源 # 鸿蒙
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

cover

小白3天精通跨平台React Native鸿蒙开发：解决Button不能自定义样式的问题（使用TouchableOpacity组件)

avatar 人工智能6S服务平台
cover

KMP 实现鸿蒙跨端：Kotlin 集合操作和数据处理指南

avatar 人工智能6S服务平台
cover

KMP 实现鸿蒙跨端：Kotlin 小游戏 - 翻牌记忆游戏

avatar 人工智能6S服务平台