本文記錄在 aarch64 目標下使用命令 OHOS_ARCH=aarch64 OHOS_ABI=arm64-v8a sh ./create-hnp.sh 構建 libusb 1.0.29 的完整過程，涵蓋鏡像獲取與回退、Autotools 構建鏈路、產物驗證與常見問題處理，便於復現與維護。

歡迎加入開源鴻蒙PC社區：

📖 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 設備通信和開發