从源码构建 HIDAPISDL 仓库中的构建方式、平台依赖与 CMake/Autotools/手动集成全指南【免费下载链接】SDLSimple DirectMedia Layer项目地址: https://gitcode.com/GitHub_Trending/sd/SDL本篇技术指南以 SDL 仓库内置的 HIDAPI 源码src/hidapi及其官方构建文档BUILD.md为核心系统讲解从源码自行构建 HIDAPI 的四种方式CMake、Autotools、Meson 包装与手动 Makefile并覆盖 Linux、FreeBSD、macOS、Windows 各平台的依赖准备、CMake 变量详解、源码树嵌入方法与交叉编译要点。读完本文你将能够根据自身项目形态选择最合适的构建路径把 HIDAPI 以共享库、静态库、框架或内嵌源码的形式接入你的程序。为什么需要从源码构建 HIDAPIHIDAPI 是一个跨平台的 HID 设备访问库允许应用程序通过统一 API 与 USB、蓝牙、I2C 等 HID 设备交互。大多数情况下你可以直接使用发行版预编译包但出于以下原因你可能需要自己动手从源码构建目标平台没有官方预编译包或需要为交叉编译环境如嵌入式 Linux定制需要控制链接的 HID 后端hidraw 与 libusb 二选一需要静态链接、最小化体积或启用特定的调试/消毒器选项需要把 HIDAPI 直接嵌入你自己的项目源码树而不是引入系统级依赖。在本仓库中HIDAPI 以第三方源码目录的形式内置于 SDL 3位于 src/hidapi仓库同时保留了 HIDAPI 官方构建所需的全部文件CMakeLists.txt、Makefile.am、configure.ac、bootstrap、各后端的Makefile-manual、hidapi.sln等因此既可以独立构建也可以作为 SDL 渲染层的一部分随 SDL 一起编译例如 src/hidapi/SDL_hidapi.c 及其平台头文件即用于 SDL 内部的 joystick 子系统。构建方式总览四条路径怎么选根据 BUILD.md 的说明HIDAPI 可以从源码以四种方式构建构建方式说明推荐程度CMake行业事实标准的构建系统HIDAPI 官方推荐的构建方式首选Autotools历史上第一个成熟的构建系统autoconf/automake/libtool已废弃deprecated仅向后兼容Meson作为 CMake 构建脚本之上的 wrapper 存在依赖 CMake供 Meson 项目使用手动 Makefile各平台目录下提供的示例 Makefile主要用于演示源码嵌入仅作示例参考文档明确指出Autotools 构建脚本对 HIDAPI 而言已经废弃未来将被移除官方团队推荐使用 CMake 构建如果你已经在使用 Autotools 脚本应尽快迁移到 CMake。Meson 包装方式如果你使用 Meson 作为项目构建系统HIDAPI 的 Meson 支持是作为 CMake 模块 的包装器实现的它保证构建走的是官方支持的 CMake 脚本。在 Meson 项目中这样接入hidapi subproject(hidapi) # 通过 hidapi.get_variable(hidapi_dep) 拿到依赖平台/后端相关的依赖变量有hidapi_winapiWindows、hidapi_darwinmacOS、hidapi_hidraw与hidapi_libusbLinux。本仓库的 src/hidapi/subprojects 目录即为 Meson 包装提供了所需的 subproject 文件。构建前的平台依赖准备无论选择哪种构建系统都需要先为对应平台/后端准备开发依赖。这组前提条件来自 BUILD.md 的 Prerequisites 章节。Linux按后端选择依赖Linux 上 HIDAPI 有两套后端二者依赖不同linux/hidraw后端需要libudev开发包libusb后端需要libusb开发包。Debian/Ubuntu 系安装命令# required only by hidraw backend sudo apt install libudev-dev # required only by libusb backend sudo apt install libusb-1.0-0-dev从仓库源码可以印证两套后端的实现形态src/hidapi/linux/hid.c 是基于内核 hidraw 节点的实现src/hidapi/libusb/hid.c 是基于 libusb-1.0 的实现。两者的定位差异在于hidraw 是 Linux 内核原生实现的 HID 协议入口支持 USB、蓝牙、I2C 等多种 HID 设备而 libusb 后端只覆盖 USB HID 设备通常用于需要完全控制 USB 枚举行为的场景。FreeBSDFreeBSD 上需要安装 libiconvpkg_add -r libiconvmacOS需要安装 Xcode 及其 Command Line Tools命令行工具其中包含构建所需的 clang 与 SDK。macOS 上的实现位于 src/hidapi/mac/hid.c底层基于 IOKit 的 HID Manager API。Windows只需要一个可用的编译器。可以根据需要选择Visual Studio官方支持的.sln/.vcxproj工程在 src/hidapi/windows 目录下Cygwin / MinGW可通过 Autotools 或 CMake 构建。Windows 实现位于 src/hidapi/windows/hid.c底层直接调用 Windows HID APIHidD_*系列函数且仅在 Windows 后端提供了单元测试见下文 CMake 变量HIDAPI_WITH_TESTS的说明。方式一CMake 构建官方推荐CMake 构建 HIDAPI 的完整说明见 BUILD.cmake.md它支持两种形态独立包构建与作为更大 CMake 项目的子目录。安装 CMake大多数 *nix 系统通过包管理器安装例如sudo apt install cmakeWindows 上可由 Visual Studio Installer 或 MinGW 安装器提供也可从官方下载安装器macOS 上可用 Homebrew/MacPorts 安装或使用官方安装器。独立包构建HIDAPI 的 CMake 构建与任何标准 CMake 项目一致步骤为创建构建目录建议放在源码目录之外→ 配置 → 编译 → 安装# precondition: create a build dir somewhere on the filesystem cd build dir # configure the build cmake HIDAPI source dir # build it! cmake --build . # install library; by default installs into /usr/local/ cmake --build . --target install # NOTE: 需要 root 权限才能安装到 /usr/local/如果想指定安装前缀例如安装到/usrcmake HIDAPI source dir -DCMAKE_INSTALL_PREFIX/usr如果你偏好 Ninja 生成器大型项目下比 msbuild 快得多cd build dir cmake -GNinja HIDAPI source dir ninja ninja installCMake 构建变量详解构建时可传入三类变量标准 CMake 变量、HIDAPI 专用变量与平台特定变量。下表汇总自 BUILD.cmake.md 并对照仓库 CMakeLists.txt 中的默认值变量默认值说明CMAKE_INSTALL_PREFIX/usr/localinstall目标安装库文件的前缀CMAKE_BUILD_TYPEReleaseHIDAPI 显式默认可选Debug、Release、RelWithDebInfo、MinSizeRelCMakeLists.txt 会在未指定时强制设为ReleaseBUILD_SHARED_LIBSTRUETRUE构建共享库否则静态库CMAKE_FRAMEWORKFALSEmacOSCMake ≥ 3.15设为TRUE时构建为 framework 库CMAKE_OSX_DEPLOYMENT_TARGET当前 Xcode/Toolchain 支持的最高版本macOS/iOS 目标平台最低部署版本HIDAPI_BUILD_HIDTESTDebug 构建下为 TRUE构建小测试程序hidtestHIDAPI_WITH_TESTS仅 Windows 可用Debug 下默认 TRUE构建全部单元测试目前只有 Windows 后端有测试HIDAPI_WITH_HIDRAWTRUELinux构建 hidraw 后端库hidapi-hidrawHIDAPI_WITH_LIBUSBTRUELinux构建 libusb 后端库hidapi-libusb关于 Linux 后端有一个强制约束HIDAPI_WITH_HIDRAW与HIDAPI_WITH_LIBUSB至少一个必须为 TRUE否则无法构成可用的后端。此外仓库 CMake 脚本还提供了HIDAPI_ENABLE_ASAN地址消毒器插桩CMakeLists.txt与HIDAPI_BUILD_PP_DATA_DUMPWindows 控制台辅助工具两个高级选项。想快速浏览全部可用变量最方便的方式是使用cmake-gui工具打开 HIDAPI 源码目录被标记为 cache 变量/option 的项会高亮显示并附有简短描述。MSVC Ninja 组合在 Windows 上用 MSVC 编译器配合 Ninja 构建中型以上项目通常比 msbuild 快得多步骤如下打开cmd.exe设置 MSVC 构建环境变量例如vcvarsall.bat x64。以 MSVC 2019 Community 为例脚本位于C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\其中x64是要构建的目标架构按通用构建步骤执行并将生成器指定为 Ninja-GNinja。在 CMake 项目中消费 HIDAPI作为安装包find_packageHIDAPI 已安装到系统或指定前缀后最简用法project(my_application) add_executable(my_application main.c) find_package(hidapi REQUIRED) target_link_libraries(my_application PRIVATE hidapi::hidapi)如果find_package找不到 HIDAPI推荐用hidapi_ROOT变量显式指定安装前缀-Dhidapi_ROOTpath to HIDAPI installation prefix。注意hidapi_ROOT需要 CMake 3.12 及以上更老的 CMake 请改用CMAKE_PREFIX_PATH。find_package(hidapi)成功后可用的 targetshidapi::hidapi— 大多数情况下的首选目标hidapi::include— 只需包含hidapi.h而不链接库hidapi::winapi— Windows 上等同hidapi::hidapihidapi::darwin— macOS 上等同hidapi::hidapihidapi::libusb— libusb 后端可用时存在hidapi::hidraw— Linux 上 hidraw 后端可用时存在。重要别名规则Linux 上通常两个后端都可用此时hidapi::hidapi是hidapi::hidraw的别名——理由是 hidraw 是 Linux 内核原生的 HID 协议实现支持 USB、蓝牙、I2C 等多种 HID 设备若未构建 hidraw只有hidapi::libusb则hidapi::hidapi退化为hidapi::libusb。如果你开发跨平台应用且确定 Linux 上要用 libusb 后端可这样显式选择if(TARGET hidapi::libusb) target_link_libraries(my_project PRIVATE hidapi::libusb) else() target_link_libraries(my_project PRIVATE hidapi::hidapi) endif()作为子目录add_subdirectoryHIDAPI 可以很方便地嵌入更大的 CMake 项目# root CMakeLists.txt cmake_minimum_required(VERSION 3.4.3...3.25 FATAL_ERROR) add_subdirectory(hidapi) add_subdirectory(my_application) # my_application/CMakeLists.txt project(my_application) add_executable(my_application main.c) # NOTE: 无需 find_packageHIDAPI targets 已在项目树内 target_link_libraries(my_application PRIVATE hidapi::hidapi)子目录构建同样可以使用独立构建章节的全部变量例如set(HIDAPI_WITH_LIBUSB FALSE) # 只在 Linux 上生效 set(BUILD_SHARED_LIBS FALSE) # 全平台静态库 add_subdirectory(hidapi)注意若你的宿主项目把BUILD_SHARED_LIBS声明为全局 CACHE 变量上述普通变量赋值在 CMake 3.13 之前不会生效参见 CMP0077 策略。子目录构建与独立构建有三个关键行为差异变量可见性独立构建会把标准/HIDAPI 变量标记为 cache 变量或 option便于cmake-gui高亮展示子目录构建则不做任何标记由宿主项目决定哪些变量需要暴露默认安装行为子目录构建默认不安装任何 HIDAPI target。如需安装可在add_subdirectory(hidapi)之前设置HIDAPI_INSTALL_TARGETS要求 CMake 3.13或用CMAKE_INSTALL_LIBDIR等 GNUInstallDirs 变量控制安装位置set(HIDAPI_INSTALL_TARGETS ON) set(CMAKE_INSTALL_LIBDIR lib64) add_subdirectory(hidapi)子目录构建默认不打印版本号如需打印可先设HIDAPI_PRINT_VERSION为 TRUE不擅自改动构建行为变量独立构建会显式把CMAKE_BUILD_TYPE默认成Release、BUILD_SHARED_LIBS默认成TRUE子目录构建即使这些变量未设置也保持原样把完全控制权交给宿主项目。子目录构建可用的 targets 与独立构建一致另加几个便于原生引用的名称hidapi_include、hidapi_winapi、hidapi_darwin、hidapi_libusb、hidapi_hidraw、hidapiWindows/macOS 上分别是hidapi_winapi/hidapi_darwin的别名以及为兼容原始库名提供的hidapi-libusb、hidapi-hidraw别名。这些非 alias 目标便于做高级配置例如add_subdirectory(hidapi) if(TARGET hidapi_libusb) # 见 libusb/hid.c 中 NO_ICONV 的用法 target_compile_definitions(hidapi_libusb PRIVATE NO_ICONV) endif()同时构建共享库与静态库Autotools 时代可以通过./configure --enable-static --enable-shared一次生成两种形态的库而 CMake 没有开箱即用的对应选项HIDAPI 也刻意不引入 CMake 层面的 workaround。想复现该行为只需分别构建并安装两次且让两次安装共用同一个CMAKE_INSTALL_PREFIX# Static libraries cmake -S HIDAPI source dir -B build dir/static -DCMAKE_INSTALL_PREFIXyour installation prefix -DBUILD_SHARED_LIBSFALSE cmake --build build dir/static # Shared libraries cmake -S HIDAPI source dir -B build dir/shared -DCMAKE_INSTALL_PREFIXyour installation prefix -DBUILD_SHARED_LIBSTRUE cmake --build build dir/shared # (可选) 修改安装目标位置仅 UNIX 平台支持 DESTDIR export DESTDIR$STAGING_DIR # 安装顺序很重要 - 最后安装 Shared 变体 cmake --install build dir/static cmake --install build dir/shared这样处理后两种形态的二进制都可使用两者共享同一份头文件.pcpkg-config文件会按 Autotools--enable-static --enable-shared的方式生成CMake 包脚本也能正常生成但find_package(hidapi)找到的将是最后安装的那个变体若最后装的是 Shared则解析到共享库二进制。另外值得注意CMake 构建出的 HIDAPI 包同样支持 pkg-config 消费如同用 Autotools 构建的一样。方式二Autotools 构建已废弃HIDAPI 的 Autotools 构建说明见 BUILD.autotools.md。文档开头即声明该构建脚本已废弃官方推荐改用 CMake仍在使用者应尽快迁移。安装 AutotoolsHIDAPI 用到autoconf、automake、libtool三个工具Ubuntusudo apt install autoconf automake libtoolFreeBSDpkg_add -r autotools另外还需 GNU makepkg_add -r gmake。构建命令以共享库形式构建并安装到系统./bootstrap # 生成 configure 脚本 ./configure make # 构建库 make install # 以 root 或 sudo 执行安装 hidapi 到系统./configure的常用选项--enable-testgui # 构建基于 Fox toolkit 的测试 GUI需要预先安装 Fox 工具包 --prefix/usr # 指定头文件与库的安装位置上例把头文件装到 /usr/include、 # 二进制装到 /usr/lib默认安装到 /usr/local --disable-shared # 默认同时构建共享库与静态库本选项禁用共享库仅构建静态库Autotools 交叉编译嵌入式 Linux以下内容适用于通过 Autotools 为嵌入式 Linux 交叉编译 HIDAPI 的场景假设从最原始的环境开始所有依赖都要先交叉编译若使用 OpenEmbedded 或 Buildroot 等构建系统流程会有所不同。先导出两个环境变量可自行修改$ export STAGING$HOME/out $ export HOSTarm-linux准备依赖按后端准备libusblibusb 后端或libudevhidraw 后端。交叉编译 libusb 示例./configure --host$HOST --prefix$STAGING make make installlibudev的交叉编译不在该文档覆盖范围内请参考libudev自身文档。构建 HIDAPIPKG_CONFIG_DIR \ PKG_CONFIG_LIBDIR$STAGING/lib/pkgconfig:$STAGING/share/pkgconfig \ PKG_CONFIG_SYSROOT_DIR$STAGING \ ./configure --host$HOST --prefix$STAGING # make / make install - 与常规构建相同这里通过PKG_CONFIG_LIBDIR与PKG_CONFIG_SYSROOT_DIR让 pkg-config 在交叉编译根目录staging中查找依赖避免误用宿主机上的包。方式三Unix 平台手动 Makefile 构建HIDAPI 的 BUILD.md 强调手动 Makefile 的主要目的是让开发者了解把 HIDAPI 直接嵌入自己程序需要哪些依赖应仅作为示例参考要构建系统级共享库请使用前述构建系统。构建方法很直接进入对应平台的目录并运行 make。例如 Linuxcd linux/ make -f Makefile-manual以 src/hidapi/linux/Makefile-manual 为例可以清晰看到 hidraw 后端的真实依赖链目标hidtest-hidraw与libhidapi-hidraw.so都由hid.o后端实现与../hidtest/test.o测试程序链接而成链接参数取自pkg-config libudev --libs外加-lrt印证了 hidraw 后端依赖 libudev编译包含路径为-I../hidapi即公共头文件目录 src/hidapi/hidapi内含hidapi.h与pkg-config libusb-1.0 --cflags即使 hidraw 后端也保留 libusb 的 include 路径便于共享测试代码。make clean可清理产物。各平台的手动 Makefile 均位于对应后端目录下如 linux/Makefile-manual、libusb/Makefile-manual、windows/Makefile-manual、mac/Makefile-manual是理解各后端编译期依赖的速查参考。方式四Windows 上的构建Windows 构建路径汇总自 BUILD.mdVisual Studio 构建 DLL直接构建 src/hidapi/windows 目录下的hidapi.sln解决方案文件仓库同时提供hidapi.vcxproj与旧式hidapi.vcproj以及配套的hidtest.vcxproj测试工程MinGW / Cygwin 构建使用 Autotools 通用流程见 BUILD.autotools.md任意 Windows 工具链MSVC 或 MinGW/Cygwin都可用 CMake 方式 构建这也是推荐路径。关于 DDK 构建文档明确指出HIDAPI 的 DDK 构建已经损坏一段时间相关支持文件现已过时不应再使用。将 HIDAPI 直接嵌入你的源码树如果上面的构建系统都不适用你还可以把 HIDAPI 源码直接并入自己的构建系统。需要做两件事详见 BUILD.md根据平台与后端只引入一个单源文件到你的构建系统windows/hid.cWindowslinux/hid.cLinux hidrawlibusb/hid.clibusb 后端mac/hid.cmacOS。把 hidapi 目录 加入编译hid.c时的 include path其中是公共头文件 hidapi.h编译/链接时提供平台/后端对应的依赖即上文 Prerequisites 中列出的 libudev、libusb、libiconv 等。注意文档给出的边界上述做法并不能保证有backend/hid.c加一份hidapi/hidapi.h就一定能构建成功——唯一能保证的是每个backend/hid.c都是自包含的单文件实现编译这一个文件所需的全部源码都已包含在内。具体每个后端还有哪些依赖请以对应目录下的手动 Makefile 为参考。值得一提的是本 SDL 仓库正是把 HIDAPI 嵌入更大项目的实例src/hidapi 作为第三方目录随 SDL 一起维护SDL 通过 SDL_hidapi.c 及各平台适配头文件如 SDL_hidapi_linux.h、SDL_hidapi_windows.h、SDL_hidapi_steamxbox.h把 HIDAPI 能力封装进 SDL 的 joystick/gamepad 子系统这正是源码树嵌入模式的典型应用。构建后的验证与进一步探索构建完成后可以借助 HIDAPI 自带的测试程序验证安装是否正常hidtest随构建生成的小型控制台测试程序对应 src/hidapi/hidtest 目录枚举并操作连接的 HID 设备由HIDAPI_BUILD_HIDTEST变量控制是否构建Windows 单元测试由HIDAPI_WITH_TESTS控制仅 Windows 后端有测试源码位于 src/hidapi/windows/test。对于进一步深入公共 API 定义在 src/hidapi/hidapi/hidapi.h测试 GUI 的 Fox 依赖说明见仓库 README.md若想为特定平台新增或修改后端行为可从对应后端的hid.c入手各后端目录中还附有平台专用头文件如 linux、libusb、windows、mac这些是理解 HIDAPI 后端抽象与移植新平台的起点。【免费下载链接】SDLSimple DirectMedia Layer项目地址: https://gitcode.com/GitHub_Trending/sd/SDL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从源码构建 HIDAPI：SDL 仓库中的构建方式、平台依赖与 CMake/Autotools/手动集成全指南
从源码构建 HIDAPISDL 仓库中的构建方式、平台依赖与 CMake/Autotools/手动集成全指南【免费下载链接】SDLSimple DirectMedia Layer项目地址: https://gitcode.com/GitHub_Trending/sd/SDL本篇技术指南以 SDL 仓库内置的 HIDAPI 源码src/hidapi及其官方构建文档BUILD.md为核心系统讲解从源码自行构建 HIDAPI 的四种方式CMake、Autotools、Meson 包装与手动 Makefile并覆盖 Linux、FreeBSD、macOS、Windows 各平台的依赖准备、CMake 变量详解、源码树嵌入方法与交叉编译要点。读完本文你将能够根据自身项目形态选择最合适的构建路径把 HIDAPI 以共享库、静态库、框架或内嵌源码的形式接入你的程序。为什么需要从源码构建 HIDAPIHIDAPI 是一个跨平台的 HID 设备访问库允许应用程序通过统一 API 与 USB、蓝牙、I2C 等 HID 设备交互。大多数情况下你可以直接使用发行版预编译包但出于以下原因你可能需要自己动手从源码构建目标平台没有官方预编译包或需要为交叉编译环境如嵌入式 Linux定制需要控制链接的 HID 后端hidraw 与 libusb 二选一需要静态链接、最小化体积或启用特定的调试/消毒器选项需要把 HIDAPI 直接嵌入你自己的项目源码树而不是引入系统级依赖。在本仓库中HIDAPI 以第三方源码目录的形式内置于 SDL 3位于 src/hidapi仓库同时保留了 HIDAPI 官方构建所需的全部文件CMakeLists.txt、Makefile.am、configure.ac、bootstrap、各后端的Makefile-manual、hidapi.sln等因此既可以独立构建也可以作为 SDL 渲染层的一部分随 SDL 一起编译例如 src/hidapi/SDL_hidapi.c 及其平台头文件即用于 SDL 内部的 joystick 子系统。构建方式总览四条路径怎么选根据 BUILD.md 的说明HIDAPI 可以从源码以四种方式构建构建方式说明推荐程度CMake行业事实标准的构建系统HIDAPI 官方推荐的构建方式首选Autotools历史上第一个成熟的构建系统autoconf/automake/libtool已废弃deprecated仅向后兼容Meson作为 CMake 构建脚本之上的 wrapper 存在依赖 CMake供 Meson 项目使用手动 Makefile各平台目录下提供的示例 Makefile主要用于演示源码嵌入仅作示例参考文档明确指出Autotools 构建脚本对 HIDAPI 而言已经废弃未来将被移除官方团队推荐使用 CMake 构建如果你已经在使用 Autotools 脚本应尽快迁移到 CMake。Meson 包装方式如果你使用 Meson 作为项目构建系统HIDAPI 的 Meson 支持是作为 CMake 模块 的包装器实现的它保证构建走的是官方支持的 CMake 脚本。在 Meson 项目中这样接入hidapi subproject(hidapi) # 通过 hidapi.get_variable(hidapi_dep) 拿到依赖平台/后端相关的依赖变量有hidapi_winapiWindows、hidapi_darwinmacOS、hidapi_hidraw与hidapi_libusbLinux。本仓库的 src/hidapi/subprojects 目录即为 Meson 包装提供了所需的 subproject 文件。构建前的平台依赖准备无论选择哪种构建系统都需要先为对应平台/后端准备开发依赖。这组前提条件来自 BUILD.md 的 Prerequisites 章节。Linux按后端选择依赖Linux 上 HIDAPI 有两套后端二者依赖不同linux/hidraw后端需要libudev开发包libusb后端需要libusb开发包。Debian/Ubuntu 系安装命令# required only by hidraw backend sudo apt install libudev-dev # required only by libusb backend sudo apt install libusb-1.0-0-dev从仓库源码可以印证两套后端的实现形态src/hidapi/linux/hid.c 是基于内核 hidraw 节点的实现src/hidapi/libusb/hid.c 是基于 libusb-1.0 的实现。两者的定位差异在于hidraw 是 Linux 内核原生实现的 HID 协议入口支持 USB、蓝牙、I2C 等多种 HID 设备而 libusb 后端只覆盖 USB HID 设备通常用于需要完全控制 USB 枚举行为的场景。FreeBSDFreeBSD 上需要安装 libiconvpkg_add -r libiconvmacOS需要安装 Xcode 及其 Command Line Tools命令行工具其中包含构建所需的 clang 与 SDK。macOS 上的实现位于 src/hidapi/mac/hid.c底层基于 IOKit 的 HID Manager API。Windows只需要一个可用的编译器。可以根据需要选择Visual Studio官方支持的.sln/.vcxproj工程在 src/hidapi/windows 目录下Cygwin / MinGW可通过 Autotools 或 CMake 构建。Windows 实现位于 src/hidapi/windows/hid.c底层直接调用 Windows HID APIHidD_*系列函数且仅在 Windows 后端提供了单元测试见下文 CMake 变量HIDAPI_WITH_TESTS的说明。方式一CMake 构建官方推荐CMake 构建 HIDAPI 的完整说明见 BUILD.cmake.md它支持两种形态独立包构建与作为更大 CMake 项目的子目录。安装 CMake大多数 *nix 系统通过包管理器安装例如sudo apt install cmakeWindows 上可由 Visual Studio Installer 或 MinGW 安装器提供也可从官方下载安装器macOS 上可用 Homebrew/MacPorts 安装或使用官方安装器。独立包构建HIDAPI 的 CMake 构建与任何标准 CMake 项目一致步骤为创建构建目录建议放在源码目录之外→ 配置 → 编译 → 安装# precondition: create a build dir somewhere on the filesystem cd build dir # configure the build cmake HIDAPI source dir # build it! cmake --build . # install library; by default installs into /usr/local/ cmake --build . --target install # NOTE: 需要 root 权限才能安装到 /usr/local/如果想指定安装前缀例如安装到/usrcmake HIDAPI source dir -DCMAKE_INSTALL_PREFIX/usr如果你偏好 Ninja 生成器大型项目下比 msbuild 快得多cd build dir cmake -GNinja HIDAPI source dir ninja ninja installCMake 构建变量详解构建时可传入三类变量标准 CMake 变量、HIDAPI 专用变量与平台特定变量。下表汇总自 BUILD.cmake.md 并对照仓库 CMakeLists.txt 中的默认值变量默认值说明CMAKE_INSTALL_PREFIX/usr/localinstall目标安装库文件的前缀CMAKE_BUILD_TYPEReleaseHIDAPI 显式默认可选Debug、Release、RelWithDebInfo、MinSizeRelCMakeLists.txt 会在未指定时强制设为ReleaseBUILD_SHARED_LIBSTRUETRUE构建共享库否则静态库CMAKE_FRAMEWORKFALSEmacOSCMake ≥ 3.15设为TRUE时构建为 framework 库CMAKE_OSX_DEPLOYMENT_TARGET当前 Xcode/Toolchain 支持的最高版本macOS/iOS 目标平台最低部署版本HIDAPI_BUILD_HIDTESTDebug 构建下为 TRUE构建小测试程序hidtestHIDAPI_WITH_TESTS仅 Windows 可用Debug 下默认 TRUE构建全部单元测试目前只有 Windows 后端有测试HIDAPI_WITH_HIDRAWTRUELinux构建 hidraw 后端库hidapi-hidrawHIDAPI_WITH_LIBUSBTRUELinux构建 libusb 后端库hidapi-libusb关于 Linux 后端有一个强制约束HIDAPI_WITH_HIDRAW与HIDAPI_WITH_LIBUSB至少一个必须为 TRUE否则无法构成可用的后端。此外仓库 CMake 脚本还提供了HIDAPI_ENABLE_ASAN地址消毒器插桩CMakeLists.txt与HIDAPI_BUILD_PP_DATA_DUMPWindows 控制台辅助工具两个高级选项。想快速浏览全部可用变量最方便的方式是使用cmake-gui工具打开 HIDAPI 源码目录被标记为 cache 变量/option 的项会高亮显示并附有简短描述。MSVC Ninja 组合在 Windows 上用 MSVC 编译器配合 Ninja 构建中型以上项目通常比 msbuild 快得多步骤如下打开cmd.exe设置 MSVC 构建环境变量例如vcvarsall.bat x64。以 MSVC 2019 Community 为例脚本位于C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\其中x64是要构建的目标架构按通用构建步骤执行并将生成器指定为 Ninja-GNinja。在 CMake 项目中消费 HIDAPI作为安装包find_packageHIDAPI 已安装到系统或指定前缀后最简用法project(my_application) add_executable(my_application main.c) find_package(hidapi REQUIRED) target_link_libraries(my_application PRIVATE hidapi::hidapi)如果find_package找不到 HIDAPI推荐用hidapi_ROOT变量显式指定安装前缀-Dhidapi_ROOTpath to HIDAPI installation prefix。注意hidapi_ROOT需要 CMake 3.12 及以上更老的 CMake 请改用CMAKE_PREFIX_PATH。find_package(hidapi)成功后可用的 targetshidapi::hidapi— 大多数情况下的首选目标hidapi::include— 只需包含hidapi.h而不链接库hidapi::winapi— Windows 上等同hidapi::hidapihidapi::darwin— macOS 上等同hidapi::hidapihidapi::libusb— libusb 后端可用时存在hidapi::hidraw— Linux 上 hidraw 后端可用时存在。重要别名规则Linux 上通常两个后端都可用此时hidapi::hidapi是hidapi::hidraw的别名——理由是 hidraw 是 Linux 内核原生的 HID 协议实现支持 USB、蓝牙、I2C 等多种 HID 设备若未构建 hidraw只有hidapi::libusb则hidapi::hidapi退化为hidapi::libusb。如果你开发跨平台应用且确定 Linux 上要用 libusb 后端可这样显式选择if(TARGET hidapi::libusb) target_link_libraries(my_project PRIVATE hidapi::libusb) else() target_link_libraries(my_project PRIVATE hidapi::hidapi) endif()作为子目录add_subdirectoryHIDAPI 可以很方便地嵌入更大的 CMake 项目# root CMakeLists.txt cmake_minimum_required(VERSION 3.4.3...3.25 FATAL_ERROR) add_subdirectory(hidapi) add_subdirectory(my_application) # my_application/CMakeLists.txt project(my_application) add_executable(my_application main.c) # NOTE: 无需 find_packageHIDAPI targets 已在项目树内 target_link_libraries(my_application PRIVATE hidapi::hidapi)子目录构建同样可以使用独立构建章节的全部变量例如set(HIDAPI_WITH_LIBUSB FALSE) # 只在 Linux 上生效 set(BUILD_SHARED_LIBS FALSE) # 全平台静态库 add_subdirectory(hidapi)注意若你的宿主项目把BUILD_SHARED_LIBS声明为全局 CACHE 变量上述普通变量赋值在 CMake 3.13 之前不会生效参见 CMP0077 策略。子目录构建与独立构建有三个关键行为差异变量可见性独立构建会把标准/HIDAPI 变量标记为 cache 变量或 option便于cmake-gui高亮展示子目录构建则不做任何标记由宿主项目决定哪些变量需要暴露默认安装行为子目录构建默认不安装任何 HIDAPI target。如需安装可在add_subdirectory(hidapi)之前设置HIDAPI_INSTALL_TARGETS要求 CMake 3.13或用CMAKE_INSTALL_LIBDIR等 GNUInstallDirs 变量控制安装位置set(HIDAPI_INSTALL_TARGETS ON) set(CMAKE_INSTALL_LIBDIR lib64) add_subdirectory(hidapi)子目录构建默认不打印版本号如需打印可先设HIDAPI_PRINT_VERSION为 TRUE不擅自改动构建行为变量独立构建会显式把CMAKE_BUILD_TYPE默认成Release、BUILD_SHARED_LIBS默认成TRUE子目录构建即使这些变量未设置也保持原样把完全控制权交给宿主项目。子目录构建可用的 targets 与独立构建一致另加几个便于原生引用的名称hidapi_include、hidapi_winapi、hidapi_darwin、hidapi_libusb、hidapi_hidraw、hidapiWindows/macOS 上分别是hidapi_winapi/hidapi_darwin的别名以及为兼容原始库名提供的hidapi-libusb、hidapi-hidraw别名。这些非 alias 目标便于做高级配置例如add_subdirectory(hidapi) if(TARGET hidapi_libusb) # 见 libusb/hid.c 中 NO_ICONV 的用法 target_compile_definitions(hidapi_libusb PRIVATE NO_ICONV) endif()同时构建共享库与静态库Autotools 时代可以通过./configure --enable-static --enable-shared一次生成两种形态的库而 CMake 没有开箱即用的对应选项HIDAPI 也刻意不引入 CMake 层面的 workaround。想复现该行为只需分别构建并安装两次且让两次安装共用同一个CMAKE_INSTALL_PREFIX# Static libraries cmake -S HIDAPI source dir -B build dir/static -DCMAKE_INSTALL_PREFIXyour installation prefix -DBUILD_SHARED_LIBSFALSE cmake --build build dir/static # Shared libraries cmake -S HIDAPI source dir -B build dir/shared -DCMAKE_INSTALL_PREFIXyour installation prefix -DBUILD_SHARED_LIBSTRUE cmake --build build dir/shared # (可选) 修改安装目标位置仅 UNIX 平台支持 DESTDIR export DESTDIR$STAGING_DIR # 安装顺序很重要 - 最后安装 Shared 变体 cmake --install build dir/static cmake --install build dir/shared这样处理后两种形态的二进制都可使用两者共享同一份头文件.pcpkg-config文件会按 Autotools--enable-static --enable-shared的方式生成CMake 包脚本也能正常生成但find_package(hidapi)找到的将是最后安装的那个变体若最后装的是 Shared则解析到共享库二进制。另外值得注意CMake 构建出的 HIDAPI 包同样支持 pkg-config 消费如同用 Autotools 构建的一样。方式二Autotools 构建已废弃HIDAPI 的 Autotools 构建说明见 BUILD.autotools.md。文档开头即声明该构建脚本已废弃官方推荐改用 CMake仍在使用者应尽快迁移。安装 AutotoolsHIDAPI 用到autoconf、automake、libtool三个工具Ubuntusudo apt install autoconf automake libtoolFreeBSDpkg_add -r autotools另外还需 GNU makepkg_add -r gmake。构建命令以共享库形式构建并安装到系统./bootstrap # 生成 configure 脚本 ./configure make # 构建库 make install # 以 root 或 sudo 执行安装 hidapi 到系统./configure的常用选项--enable-testgui # 构建基于 Fox toolkit 的测试 GUI需要预先安装 Fox 工具包 --prefix/usr # 指定头文件与库的安装位置上例把头文件装到 /usr/include、 # 二进制装到 /usr/lib默认安装到 /usr/local --disable-shared # 默认同时构建共享库与静态库本选项禁用共享库仅构建静态库Autotools 交叉编译嵌入式 Linux以下内容适用于通过 Autotools 为嵌入式 Linux 交叉编译 HIDAPI 的场景假设从最原始的环境开始所有依赖都要先交叉编译若使用 OpenEmbedded 或 Buildroot 等构建系统流程会有所不同。先导出两个环境变量可自行修改$ export STAGING$HOME/out $ export HOSTarm-linux准备依赖按后端准备libusblibusb 后端或libudevhidraw 后端。交叉编译 libusb 示例./configure --host$HOST --prefix$STAGING make make installlibudev的交叉编译不在该文档覆盖范围内请参考libudev自身文档。构建 HIDAPIPKG_CONFIG_DIR \ PKG_CONFIG_LIBDIR$STAGING/lib/pkgconfig:$STAGING/share/pkgconfig \ PKG_CONFIG_SYSROOT_DIR$STAGING \ ./configure --host$HOST --prefix$STAGING # make / make install - 与常规构建相同这里通过PKG_CONFIG_LIBDIR与PKG_CONFIG_SYSROOT_DIR让 pkg-config 在交叉编译根目录staging中查找依赖避免误用宿主机上的包。方式三Unix 平台手动 Makefile 构建HIDAPI 的 BUILD.md 强调手动 Makefile 的主要目的是让开发者了解把 HIDAPI 直接嵌入自己程序需要哪些依赖应仅作为示例参考要构建系统级共享库请使用前述构建系统。构建方法很直接进入对应平台的目录并运行 make。例如 Linuxcd linux/ make -f Makefile-manual以 src/hidapi/linux/Makefile-manual 为例可以清晰看到 hidraw 后端的真实依赖链目标hidtest-hidraw与libhidapi-hidraw.so都由hid.o后端实现与../hidtest/test.o测试程序链接而成链接参数取自pkg-config libudev --libs外加-lrt印证了 hidraw 后端依赖 libudev编译包含路径为-I../hidapi即公共头文件目录 src/hidapi/hidapi内含hidapi.h与pkg-config libusb-1.0 --cflags即使 hidraw 后端也保留 libusb 的 include 路径便于共享测试代码。make clean可清理产物。各平台的手动 Makefile 均位于对应后端目录下如 linux/Makefile-manual、libusb/Makefile-manual、windows/Makefile-manual、mac/Makefile-manual是理解各后端编译期依赖的速查参考。方式四Windows 上的构建Windows 构建路径汇总自 BUILD.mdVisual Studio 构建 DLL直接构建 src/hidapi/windows 目录下的hidapi.sln解决方案文件仓库同时提供hidapi.vcxproj与旧式hidapi.vcproj以及配套的hidtest.vcxproj测试工程MinGW / Cygwin 构建使用 Autotools 通用流程见 BUILD.autotools.md任意 Windows 工具链MSVC 或 MinGW/Cygwin都可用 CMake 方式 构建这也是推荐路径。关于 DDK 构建文档明确指出HIDAPI 的 DDK 构建已经损坏一段时间相关支持文件现已过时不应再使用。将 HIDAPI 直接嵌入你的源码树如果上面的构建系统都不适用你还可以把 HIDAPI 源码直接并入自己的构建系统。需要做两件事详见 BUILD.md根据平台与后端只引入一个单源文件到你的构建系统windows/hid.cWindowslinux/hid.cLinux hidrawlibusb/hid.clibusb 后端mac/hid.cmacOS。把 hidapi 目录 加入编译hid.c时的 include path其中是公共头文件 hidapi.h编译/链接时提供平台/后端对应的依赖即上文 Prerequisites 中列出的 libudev、libusb、libiconv 等。注意文档给出的边界上述做法并不能保证有backend/hid.c加一份hidapi/hidapi.h就一定能构建成功——唯一能保证的是每个backend/hid.c都是自包含的单文件实现编译这一个文件所需的全部源码都已包含在内。具体每个后端还有哪些依赖请以对应目录下的手动 Makefile 为参考。值得一提的是本 SDL 仓库正是把 HIDAPI 嵌入更大项目的实例src/hidapi 作为第三方目录随 SDL 一起维护SDL 通过 SDL_hidapi.c 及各平台适配头文件如 SDL_hidapi_linux.h、SDL_hidapi_windows.h、SDL_hidapi_steamxbox.h把 HIDAPI 能力封装进 SDL 的 joystick/gamepad 子系统这正是源码树嵌入模式的典型应用。构建后的验证与进一步探索构建完成后可以借助 HIDAPI 自带的测试程序验证安装是否正常hidtest随构建生成的小型控制台测试程序对应 src/hidapi/hidtest 目录枚举并操作连接的 HID 设备由HIDAPI_BUILD_HIDTEST变量控制是否构建Windows 单元测试由HIDAPI_WITH_TESTS控制仅 Windows 后端有测试源码位于 src/hidapi/windows/test。对于进一步深入公共 API 定义在 src/hidapi/hidapi/hidapi.h测试 GUI 的 Fox 依赖说明见仓库 README.md若想为特定平台新增或修改后端行为可从对应后端的hid.c入手各后端目录中还附有平台专用头文件如 linux、libusb、windows、mac这些是理解 HIDAPI 后端抽象与移植新平台的起点。【免费下载链接】SDLSimple DirectMedia Layer项目地址: https://gitcode.com/GitHub_Trending/sd/SDL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考