### Customizing Installation Prefix with CMake

Source: https://github.com/libusb/hidapi/blob/master/BUILD.cmake.md

This example demonstrates how to specify a custom installation directory for HIDAPI during the CMake configuration step using the CMAKE_INSTALL_PREFIX variable. This allows installation into locations other than the default /usr/local.

```sh
cmake <HIDAPI source dir> -DCMAKE_INSTALL_PREFIX=/usr
```

--------------------------------

### Installation and Version Printing Options

Source: https://github.com/libusb/hidapi/blob/master/CMakeLists.txt

Enables the installation of targets by default and enables printing the HIDAPI version during the build.

```cmake
set(HIDAPI_INSTALL_TARGETS ON)
set(HIDAPI_PRINT_VERSION ON)
```

--------------------------------

### Install HIDAPI Prerequisites on FreeBSD

Source: https://github.com/libusb/hidapi/blob/master/BUILD.md

Installs the libiconv package on FreeBSD systems. This is a prerequisite for building HIDAPI on this platform.

```sh
pkg_add -r libiconv
```

--------------------------------

### Install Autotools on FreeBSD

Source: https://github.com/libusb/hidapi/blob/master/BUILD.autotools.md

Installs Autotools and GNU make on FreeBSD systems using pkg_add.

```sh
pkg_add -r autotools
```

```sh
pkg_add -r gmake
```

--------------------------------

### Enable HIDAPI Target Installation

Source: https://github.com/libusb/hidapi/blob/master/BUILD.cmake.md

Set HIDAPI_INSTALL_TARGETS to ON before including the HIDAPI subdirectory to enable installation. Optionally, modify installation directories using CMAKE_INSTALL_LIBDIR.

```cmake
# enable the installation if you need it
set(HIDAPI_INSTALL_TARGETS ON)
# (optionally) change default installation locations if it makes sense for your target platform, etc.
set(CMAKE_INSTALL_LIBDIR "lib64")
add_subdirectory(hidapi)
```

--------------------------------

### Install HIDAPI Libraries (Static then Shared)

Source: https://github.com/libusb/hidapi/blob/master/BUILD.cmake.md

This sequence installs the previously built static and shared HIDAPI libraries. It's crucial to install the shared library last to ensure that CMake package scripts and pkg-config files correctly point to the shared version when both are installed in the same prefix.

```sh
# Install the libraries
# NOTE: order of installation matters - install Shared variant *the last*

# Static libraries
cmake --install "<build dir>/static"
# Shared libraries
cmake --install "<build dir>/shared"
```

--------------------------------

### Install NetBSD HidAPI Targets

Source: https://github.com/libusb/hidapi/blob/master/netbsd/CMakeLists.txt

Installs the NetBSD HidAPI library, archives, and public headers if HIDAPI_INSTALL_TARGETS is enabled.

```cmake
if(HIDAPI_INSTALL_TARGETS)
    install(TARGETS hidapi_netbsd EXPORT hidapi
        LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}"
        ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}"
        PUBLIC_HEADER DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/hidapi"
    )
endif()
```

--------------------------------

### Install Autotools on Ubuntu

Source: https://github.com/libusb/hidapi/blob/master/BUILD.autotools.md

Installs the necessary Autotools packages (autoconf, automake, libtool) on Ubuntu systems using APT.

```sh
sudo apt install autoconf automake libtool
```

--------------------------------

### Install Runtime Destinations

Source: https://github.com/libusb/hidapi/blob/master/hidtest/CMakeLists.txt

Installs the built HIDAPI test targets (executables) to the runtime destination directory, typically the bin directory.

```cmake
install(TARGETS ${HIDAPI_HIDTEST_TARGETS}
    RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}"
)
```

--------------------------------

### Basic HIDAPI CMake Build

Source: https://github.com/libusb/hidapi/blob/master/BUILD.cmake.md

This snippet shows the fundamental steps to configure, build, and install HIDAPI using CMake from an external build directory. Ensure you replace `<build dir>` and `<HIDAPI source dir>` with your actual paths.

```sh
# precondition: create a <build dir> somewhere on the filesystem (preferably outside of the HIDAPI source)
# this is the place where all intermediate/build files are going to be located
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: you need to run install command as root, to be able to install into /usr/local/
```

--------------------------------

### HIDAPI Example: Device Communication

Source: https://github.com/libusb/hidapi/blob/master/README.md

This C code demonstrates basic HIDAPI usage, including device initialization, opening, reading strings, sending reports, reading data, and closing the device. Error checking is omitted for simplicity. Warning: Writing data randomly to HID devices can break them.

```c
#include <stdio.h> // printf
#include <wchar.h> // wchar_t

#include <hidapi.h>

#define MAX_STR 255

int main(int argc, char* argv[])
{
	int res;
	unsigned char buf[65];
	wchar_t wstr[MAX_STR];
	hid_device *handle;
	int i;

	// Initialize the hidapi library
	res = hid_init();

	// Open the device using the VID, PID,
	// and optionally the Serial number.
	handle = hid_open(0x4d8, 0x3f, NULL);
	if (!handle) {
		printf("Unable to open device\n");
		hid_exit();
 		return 1;
	}

	// Read the Manufacturer String
	res = hid_get_manufacturer_string(handle, wstr, MAX_STR);
	printf("Manufacturer String: %ls\n", wstr);

	// Read the Product String
	res = hid_get_product_string(handle, wstr, MAX_STR);
	printf("Product String: %ls\n", wstr);

	// Read the Serial Number String
	res = hid_get_serial_number_string(handle, wstr, MAX_STR);
	printf("Serial Number String: (%d) %ls\n", wstr[0], wstr);

	// Read Indexed String 1
	res = hid_get_indexed_string(handle, 1, wstr, MAX_STR);
	printf("Indexed String 1: %ls\n", wstr);

	// Toggle LED (cmd 0x80). The first byte is the report number (0x0).
	buf[0] = 0x0;
	buf[1] = 0x80;
	res = hid_write(handle, buf, 65);

	// Request state (cmd 0x81). The first byte is the report number (0x0).
	buf[0] = 0x0;
	buf[1] = 0x81;
	res = hid_write(handle, buf, 65);

	// Read requested state
	res = hid_read(handle, buf, 65);

	// Print out the returned buffer.
	for (i = 0; i < 4; i++)
		printf("buf[%d]: %d\n", i, buf[i]);

	// Close the device
	hid_close(handle);

	// Finalize the hidapi library
	res = hid_exit();

	return 0;
}

```

--------------------------------

### Install HIDAPI Development Package on Ubuntu

Source: https://github.com/libusb/hidapi/blob/master/README.md

This command installs the HIDAPI development package on Ubuntu systems using APT. Ensure you have the necessary permissions.

```sh
sudo apt install libhidapi-dev
```

--------------------------------

### Install HIDAPI Windows Library Targets

Source: https://github.com/libusb/hidapi/blob/master/windows/CMakeLists.txt

This snippet defines the installation rules for the hidapi_winapi target, specifying destinations for runtime files, libraries, and public headers.

```cmake
if(HIDAPI_INSTALL_TARGETS)
    install(TARGETS hidapi_winapi EXPORT hidapi
        RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}"
        LIBRARY DESTINATION "${CMAKE_INSTALL_LIBDIR}"
        ARCHIVE DESTINATION "${CMAKE_INSTALL_LIBDIR}"
        PUBLIC_HEADER DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/hidapi"
    )
endif()
```

--------------------------------

### Install HIDAPI Prerequisites on Debian/Ubuntu

Source: https://github.com/libusb/hidapi/blob/master/BUILD.md

Installs necessary development packages for the hidraw and libusb backends on Debian/Ubuntu systems. Required only by the respective backends.

```sh
# required only by hidraw backend
sudo apt install libudev-dev
# required only by libusb backend
sudo apt install libusb-1.0-0-dev
```

--------------------------------

### HIDAPI CMake Build Setup

Source: https://github.com/libusb/hidapi/blob/master/subprojects/hidapi_build_cmake/CMakeLists.txt

This CMake script configures the build environment for HIDAPI. It sets the minimum required CMake version, defines the project, creates a build directory, copies essential project files, and includes the main HIDAPI build logic from a subdirectory.

```cmake
cmake_minimum_required(VERSION 3.1.3...3.25 FATAL_ERROR)
project(hidapi LANGUAGES C)

file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/root")

foreach(ROOT_ELEMENT CMakeLists.txt hidapi src windows linux mac libusb pc VERSION)
  file(COPY "${CMAKE_CURRENT_LIST_DIR}/../../${ROOT_ELEMENT}" DESTINATION "${CMAKE_CURRENT_BINARY_DIR}/root/")
endforeach()

add_subdirectory("${CMAKE_CURRENT_BINARY_DIR}/root" hidapi_root)
```

--------------------------------

### Build HIDAPI on NetBSD with CMake

Source: https://github.com/libusb/hidapi/wiki/Home

Use this CMake command to build HIDAPI on NetBSD, specifying include paths, linker flags, and installation prefix.

```bash
cmake .. -D HIDAPI_BUILD_HIDTEST=1  -D CMAKE_C_FLAGS=-I/usr/pkg/include -D CMAKE_EXE_LINKER_FLAGS=-R/usr/pkg/lib -DCMAKE_INSTALL_PREFIX=/usr/pkg
```

--------------------------------

### Building HIDAPI with Ninja Generator

Source: https://github.com/libusb/hidapi/blob/master/BUILD.cmake.md

This snippet illustrates how to use the Ninja build system with CMake for building HIDAPI. It involves configuring CMake with the -GNinja flag and then using the 'ninja' command directly for building and installation.

```sh
cd <build dir>
# configure the build
cmake -GNinja <HIDAPI source dir>
# we know, that CMake has generated build files for Ninja, 
# so we can use `ninja` directly, instead of `cmake --build .`
ninja
# install library
ninja install
```

--------------------------------

### Link to HIDAPI libusb Backend on Linux

Source: https://github.com/libusb/hidapi/blob/master/BUILD.cmake.md

This example demonstrates how to conditionally link to the `hidapi::libusb` target if it's available, falling back to the default `hidapi::hidapi` otherwise. This is useful for cross-platform applications requiring the libusb backend on Linux.

```cmake
if(TARGET hidapi::libusb)
    target_link_libraries(my_project PRIVATE hidapi::libusb)
else()
    target_link_libraries(my_project PRIVATE hidapi::hidapi)
endif()
```

--------------------------------

### Configure and Build Static HIDAPI Library

Source: https://github.com/libusb/hidapi/blob/master/BUILD.cmake.md

This command configures a CMake build for HIDAPI, specifically targeting the creation of static libraries. Ensure the source and build directories are correctly specified, and `CMAKE_INSTALL_PREFIX` points to your desired installation location.

```sh
cmake -S <HIDAPI source dir> -B "<build dir>/static" -DCMAKE_INSTALL_PREFIX=<your installation prefix> -DBUILD_SHARED_LIBS=FALSE
cmake --build "<build dir>/static"
```

--------------------------------

### Build HIDAPI with Autotools

Source: https://github.com/libusb/hidapi/blob/master/BUILD.autotools.md

Steps to build HIDAPI as a shared library using Autotools, including bootstrapping, configuring, and installing. It recommends creating a separate build directory.

```sh
./bootstrap # this prepares the configure script
mkdir build
cd build # in-source builds are not recommended and known to be broken in some cases (https://github.com/libusb/hidapi/issues/621)
../configure
make # build the library
make install # as root, or using sudo, this will install hidapi into your system
```

--------------------------------

### Cross-Compile libusb with Autotools

Source: https://github.com/libusb/hidapi/blob/master/BUILD.autotools.md

Example of cross-compiling the libusb library for an embedded Linux target using Autotools. Requires setting STAGING and HOST environment variables.

```sh
./configure --host=$HOST --prefix=$STAGING
make
make install
```

--------------------------------

### Configure Autotools Build Options

Source: https://github.com/libusb/hidapi/blob/master/BUILD.autotools.md

Commonly used options for the `./configure` script when building HIDAPI with Autotools. These control features like the test GUI, installation prefix, and library type.

```sh
--enable-testgui
		# Enable the build of Foxit-based Test GUI. This requires Fox toolkit to
		# be installed/available. See README.md#test-gui for remarks.

	--prefix=/usr
		# Specify where you want the output headers and libraries to
		# be installed. The example above will put the headers in
		# /usr/include and the binaries in /usr/lib. The default is to
		# install into /usr/local which is fine on most systems.

	--disable-shared
		# By default, both shared and static libraries are going to be built/installed.
		# This option disables shared library build, if only static library is required.
```

--------------------------------

### CMake Function to Configure HIDAPI Pkg-Config

Source: https://github.com/libusb/hidapi/blob/master/src/CMakeLists.txt

Use this function to generate and install pkg-config files for HIDAPI. It requires the path to a template .pc file and handles directory creation and variable substitution.

```cmake
function(hidapi_configure_pc PC_IN_FILE)
    file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/pc")

    set(VERSION "${VERSION}${VERSION_SUFFIX}")
    set(prefix "${CMAKE_INSTALL_PREFIX}")
    set(exec_prefix "\${prefix}")
    if(IS_ABSOLUTE "${CMAKE_INSTALL_LIBDIR}")
        set(libdir "${CMAKE_INSTALL_LIBDIR}")
    else()
        set(libdir "\${exec_prefix}/${CMAKE_INSTALL_LIBDIR}")
    endif()
    if(IS_ABSOLUTE "${CMAKE_INSTALL_INCLUDEDIR}")
        set(includedir "${CMAKE_INSTALL_INCLUDEDIR}")
    else()
        set(includedir "\${prefix}/${CMAKE_INSTALL_INCLUDEDIR}")
    endif()

    get_filename_component(PC_IN_FILENAME "${PC_IN_FILE}" NAME_WE)
    set(PC_FILE "${CMAKE_CURRENT_BINARY_DIR}/pc/${PC_IN_FILENAME}.pc")
    configure_file("${PC_IN_FILE}" "${PC_FILE}" @ONLY)
    if(HIDAPI_INSTALL_TARGETS)
        install(FILES "${PC_FILE}" DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig/")
    endif()
endfunction()
```

--------------------------------

### Check for EXCLUDE_FROM_ALL and Install Targets Conflict

Source: https://github.com/libusb/hidapi/blob/master/src/CMakeLists.txt

Warns if the project is configured to be excluded from all targets and also set to install targets, as this combination can lead to undefined behavior in CMake.

```cmake
get_directory_property(IS_EXCLUDE_FROM_ALL EXCLUDE_FROM_ALL)
if(IS_EXCLUDE_FROM_ALL)
    if(HIDAPI_INSTALL_TARGETS)
        message(WARNING "Installing EXCLUDE_FROM_ALL targets in an undefined behavior in CMake.\nDon't add 'hidapi' sundirectory with 'EXCLUDE_FROM_ALL' property, or don't set 'HIDAPI_INSTALL_TARGETS' to TRUE.")
    endif()
endif()
```

--------------------------------

### Set Default Build Options

Source: https://github.com/libusb/hidapi/blob/master/src/CMakeLists.txt

Sets default values for various build options if they are not already defined. This includes enabling tests, shared libraries, and position-independent code by default, while disabling installation targets and C++ compilation unless explicitly overridden.

```cmake
if(NOT DEFINED HIDAPI_WITH_TESTS)
    set(HIDAPI_WITH_TESTS OFF)
endif()
if(NOT DEFINED BUILD_SHARED_LIBS)
    set(BUILD_SHARED_LIBS ON)
endif()
if(NOT DEFINED HIDAPI_INSTALL_TARGETS)
    set(HIDAPI_INSTALL_TARGETS OFF)
endif()
if(NOT DEFINED CMAKE_POSITION_INDEPENDENT_CODE)
    set(CMAKE_POSITION_INDEPENDENT_CODE ON)
endif()
if(NOT DEFINED HIDAPI_BUILD_AS_CXX)
    set(HIDAPI_BUILD_AS_CXX FALSE)
endif()
```

--------------------------------

### Adding HID Report Reconstructor Test Cases

Source: https://github.com/libusb/hidapi/blob/master/windows/test/CMakeLists.txt

Iterates through a list of test cases, checks for the existence of required data files (.pp_data and .rpt_desc), and adds a test to the build system. This snippet also includes conditional environment setup for ASAN on MSVC.

```cmake
foreach(TEST_CASE ${HID_DESCRIPTOR_RECONSTRUCT_TEST_CASES})
     set(TEST_PP_DATA "${CMAKE_CURRENT_LIST_DIR}/data/${TEST_CASE}.pp_data")
     if(NOT EXISTS "${TEST_PP_DATA}")
          message(FATAL_ERROR "Missing '${TEST_PP_DATA}' file for '${TEST_CASE}' test case")
     endif()
     set(TEST_EXPECTED_DESCRIPTOR "${CMAKE_CURRENT_LIST_DIR}/data/${TEST_CASE}_expected.rpt_desc")
     if(NOT EXISTS "${TEST_EXPECTED_DESCRIPTOR}")
          message(FATAL_ERROR "Missing '${TEST_EXPECTED_DESCRIPTOR}' file for '${TEST_CASE}' test case")
     endif()

     add_test(NAME "WinHidReportReconstructTest_${TEST_CASE}"
          COMMAND hid_report_reconstructor_test "${TEST_PP_DATA}" "${TEST_EXPECTED_DESCRIPTOR}"
          WORKING_DIRECTORY "$<TARGET_FILE_DIR:hidapi_winapi>"
     )
     if(HIDAPI_ENABLE_ASAN)
          if(MSVC)
               if(NOT CMAKE_VERSION VERSION_LESS CMAKE_VERSION_SUPPORTS_ENVIRONMENT_MODIFICATION)
                    get_filename_component(MSVC_BUILD_TOOLS_DIR "${CMAKE_LINKER}" DIRECTORY)
                    set_property(TEST "WinHidReportReconstructTest_${TEST_CASE}" PROPERTY ENVIRONMENT_MODIFICATION "PATH=path_list_append:${MSVC_BUILD_TOOLS_DIR}")
               endif()
          endif()
          set_property(TEST "WinHidReportReconstructTest_${TEST_CASE}" PROPERTY ENVIRONMENT "ASAN_SAVE_DUMPS=AsanDump_${TEST_CASE}.dmp")
     endif()
endforeach()
```

--------------------------------

### Configure NetBSD pkg-config File

Source: https://github.com/libusb/hidapi/blob/master/netbsd/CMakeLists.txt

Configures the pkg-config file for the NetBSD HidAPI build using a template.

```cmake
hidapi_configure_pc("${PROJECT_ROOT}/pc/hidapi-netbsd.pc.in")
```

--------------------------------

### Configure and Build Shared HIDAPI Library

Source: https://github.com/libusb/hidapi/blob/master/BUILD.cmake.md

This command configures a CMake build for HIDAPI, specifically targeting the creation of shared libraries. Use this after building the static library if you need both. The `CMAKE_INSTALL_PREFIX` should be the same as used for the static build.

```sh
cmake -S <HIDAPI source dir> -B "<build dir>/shared" -DCMAKE_INSTALL_PREFIX=<your installation prefix> -DBUILD_SHARED_LIBS=TRUE
cmake --build "<build dir>/shared"
```

--------------------------------

### Configure pp_data_dump Executable Build

Source: https://github.com/libusb/hidapi/blob/master/windows/pp_data_dump/CMakeLists.txt

Defines the build process for the pp_data_dump executable, setting the C standard to 11 and linking against hidapi_winapi. Ensure hidapi_winapi is available in your build environment.

```cmake
project(pp_data_dump C)

add_executable(pp_data_dump pp_data_dump.c)
set_target_properties(pp_data_dump
    PROPERTIES
        C_STANDARD 11
        C_STANDARD_REQUIRED TRUE
)
target_link_libraries(pp_data_dump
    PRIVATE hidapi_winapi
)

install(TARGETS pp_data_dump
    RUNTIME DESTINATION "${CMAKE_INSTALL_BINDIR}"
)
```

--------------------------------

### Project Definition with Version

Source: https://github.com/libusb/hidapi/blob/master/src/CMakeLists.txt

Defines the main project 'hidapi' and sets its version using the parsed version string. It specifies C as the primary language.

```cmake
project(hidapi VERSION "${VERSION}" LANGUAGES C)
```

--------------------------------

### Platform-Specific Options (macOS, Linux, NetBSD)

Source: https://github.com/libusb/hidapi/blob/master/CMakeLists.txt

Configures platform-specific options like building a macOS/iOS framework or enabling HIDRAW/LIBUSB on Linux and NetBSD.

```cmake
if(APPLE)
    if(NOT CMAKE_VERSION VERSION_LESS "3.15")
        option(CMAKE_FRAMEWORK "Build macOS/iOS Framework version of the library" OFF)
    endif()
elseif(NOT WIN32)
    if(CMAKE_SYSTEM_NAME MATCHES "Linux")
        option(HIDAPI_WITH_HIDRAW "Build HIDRAW-based implementation of HIDAPI" ON)
        option(HIDAPI_WITH_LIBUSB "Build LIBUSB-based implementation of HIDAPI" ON)
    endif()
    if(CMAKE_SYSTEM_NAME MATCHES "NetBSD")
        option(HIDAPI_WITH_NETBSD "Build NetBSD/UHID implementation of HIDAPI" ON)
    endif()
endif()
```

--------------------------------

### Main CMake Configuration

Source: https://github.com/libusb/hidapi/blob/master/hidtest/CMakeLists.txt

Sets the minimum CMake version, project name, and handles conditional logic for standalone builds versus builds as part of the main HIDAPI project. It also finds the required hidapi package.

```cmake
cmake_minimum_required(VERSION 3.1.3...4.3 FATAL_ERROR)
project(hidtest C)

if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
    # hidtest is build as a standalone project

    if(POLICY CMP0074)
        # allow using hidapi_ROOT if CMake supports it
        cmake_policy(SET CMP0074 NEW)
    endif()

    find_package(hidapi 0.12 REQUIRED)
    message(STATUS "Using HIDAPI: ${hidapi_VERSION}")
else()
    # hidtest is built as part of the main HIDAPI build
    message(STATUS "Building hidtest")
endif()
```

--------------------------------

### Create Aliases for NetBSD HidAPI

Source: https://github.com/libusb/hidapi/blob/master/netbsd/CMakeLists.txt

Creates aliases for the hidapi_netbsd target to ensure compatibility with find_package() and raw library linking.

```cmake
# compatibility with find_package()
add_library(hidapi::netbsd ALIAS hidapi_netbsd)
# compatibility with raw library link
add_library(hidapi-netbsd ALIAS hidapi_netbsd)
```

--------------------------------

### Set Minimum CMake Version and Handle Subdirectory Builds

Source: https://github.com/libusb/hidapi/blob/master/CMakeLists.txt

Ensures a minimum CMake version is met and handles cases where HIDAPI is included as a subdirectory in a larger project.

```cmake
cmake_minimum_required(VERSION 3.6.3...4.3 FATAL_ERROR)

if(NOT CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
    add_subdirectory(src)
    # compatibility with find_package() vs add_subdirectory
    set(hidapi_VERSION "${hidapi_VERSION}" PARENT_SCOPE)
    return()
endif()
```

--------------------------------

### Executable and C Standard Configuration

Source: https://github.com/libusb/hidapi/blob/master/windows/test/CMakeLists.txt

Defines an executable for testing HID report reconstruction and sets the C standard to C11.

```cmake
add_executable(hid_report_reconstructor_test hid_report_reconstructor_test.c)
set_target_properties(hid_report_reconstructor_test
    PROPERTIES
        C_STANDARD 11
        C_STANDARD_REQUIRED TRUE
)
```

--------------------------------

### Link Threading Library

Source: https://github.com/libusb/hidapi/blob/master/netbsd/CMakeLists.txt

Finds and links the required threading library for the NetBSD HidAPI build.

```cmake
find_package(Threads REQUIRED)
target_link_libraries(hidapi_netbsd PRIVATE Threads::Threads)
```

--------------------------------

### Add HIDAPI as a Subdirectory

Source: https://github.com/libusb/hidapi/blob/master/BUILD.cmake.md

Include HIDAPI as a subdirectory in your root CMakeLists.txt and link your application against the hidapi::hidapi target.

```cmake
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: no `find_package` is required, since HIDAPI targets are already a part of the project tree
target_link_libraries(my_application PRIVATE hidapi::hidapi)
```

--------------------------------

### HIDAPI Device Info and Preparsed Data Structure

Source: https://github.com/libusb/hidapi/blob/master/windows/pp_data_dump/README.md

This snippet shows the internal structure of HIDAPI's device information and the Preparsed Data, as represented in a .pp_data file. It details fields like vendor ID, product ID, usage information, and capability details for input, output, and feature reports.

```text
# HIDAPI device info struct:
dev->vendor_id           = 0x046D
dev->product_id          = 0xB010
dev->manufacturer_string = "Logitech"
dev->product_string      = "Logitech Bluetooth Wireless Mouse"
dev->release_number      = 0x0000
dev->interface_number    = -1
dev->usage               = 0x0001
dev->usage_page          = 0x000C
dev->path                = "\\?\hid#{00001124-0000-1000-8000-00805f9b34fb}_vid&0002046d_pid&b010&col02#8&1cf1c1b9&3&0001#{4d1e55b2-f16f-11cf-88cb-001111000030}"

# Preparsed Data struct:
pp_data->MagicKey                             = 0x48696450204B4452
pp_data->Usage                                = 0x0001
pp_data->UsagePage                            = 0x000C
pp_data->Reserved                             = 0x00000000
# Input caps_info struct:
pp_data->caps_info[0]->FirstCap           = 0
pp_data->caps_info[0]->LastCap            = 1
pp_data->caps_info[0]->NumberOfCaps       = 1
pp_data->caps_info[0]->ReportByteLength   = 2
# Output caps_info struct:
pp_data->caps_info[1]->FirstCap           = 1
pp_data->caps_info[1]->LastCap            = 1
pp_data->caps_info[1]->NumberOfCaps       = 0
pp_data->caps_info[1]->ReportByteLength   = 0
# Feature caps_info struct:
pp_data->caps_info[2]->FirstCap           = 1
pp_data->caps_info[2]->LastCap            = 1
pp_data->caps_info[2]->NumberOfCaps       = 0
pp_data->caps_info[2]->ReportByteLength   = 0
# LinkCollectionArray Offset & Size:
pp_data->FirstByteOfLinkCollectionArray       = 0x0068
pp_data->NumberLinkCollectionNodes            = 1

```

--------------------------------

### Add Source Subdirectory

Source: https://github.com/libusb/hidapi/blob/master/CMakeLists.txt

Includes the 'src' subdirectory, which likely contains the main library source files.

```cmake
add_subdirectory(src)
```

--------------------------------

### Configure HIDAPI pkg-config File

Source: https://github.com/libusb/hidapi/blob/master/windows/CMakeLists.txt

This snippet calls a helper function to configure the HIDAPI pkg-config file, which is used for managing library dependencies.

```cmake
hidapi_configure_pc("${PROJECT_ROOT}/pc/hidapi.pc.in")
```

--------------------------------

### Create Aliases for HIDAPI Library

Source: https://github.com/libusb/hidapi/blob/master/windows/CMakeLists.txt

These snippets create aliases for the hidapi_winapi target to ensure compatibility with find_package() and raw library linking.

```cmake
# compatibility with find_package()
add_library(hidapi::winapi ALIAS hidapi_winapi)
# compatibility with raw library link
add_library(hidapi ALIAS hidapi_winapi)
```

--------------------------------

### Use HIDAPI as a Standalone Package in CMake

Source: https://github.com/libusb/hidapi/blob/master/BUILD.cmake.md

This snippet shows the basic CMake configuration to find and link against a system-installed or manually built HIDAPI library.

```cmake
project(my_application)

add_executable(my_application main.c)

find_package(hidapi REQUIRED)
target_link_libraries(my_application PRIVATE hidapi::hidapi)
```

--------------------------------

### HIDAPI Tests Build Option

Source: https://github.com/libusb/hidapi/blob/master/CMakeLists.txt

Enables building HIDAPI tests, defaulting to ON only for Debug builds on Windows. Requires 'enable_testing()' to be called.

```cmake
if(WIN32)
    # so far only Windows has tests
    option(HIDAPI_WITH_TESTS "Build HIDAPI (unit-)tests" ${IS_DEBUG_BUILD})
else()
    set(HIDAPI_WITH_TESTS OFF)
endif()

if(HIDAPI_WITH_TESTS)
    enable_testing()
endif()
```

--------------------------------

### Configuring HID Report Descriptor Test Cases

Source: https://github.com/libusb/hidapi/blob/master/windows/test/CMakeLists.txt

Sets a list of test cases for reconstructing HID report descriptors. Each test case requires specific data files.

```cmake
set(HID_DESCRIPTOR_RECONSTRUCT_TEST_CASES
     046D_C52F_0001_000C
     046D_C52F_0001_FF00
     046D_C52F_0002_0001
     046D_C52F_0002_FF00
     17CC_1130_0000_FF01
     046D_0A37_0001_000C
     046A_0011_0006_0001
     046D_C077_0002_0001
     046D_C283_0004_0001
     046D_B010_0006_0001
     046D_B010_0002_FF00
     046D_B010_0002_0001
     046D_B010_0001_FF00
     046D_B010_0001_000C
     046D_C534_0001_000C
     046D_C534_0001_FF00
     046D_C534_0002_0001
     046D_C534_0002_FF00
     046D_C534_0006_0001
     046D_C534_0080_0001
     047F_C056_0001_000C
     047F_C056_0003_FFA0
     047F_C056_0005_000B
     045E_02FF_0005_0001
     1532_00A3_0002_0001
)

set(CMAKE_VERSION_SUPPORTS_ENVIRONMENT_MODIFICATION "3.22")
```

--------------------------------

### Cross-Compile HIDAPI with Autotools

Source: https://github.com/libusb/hidapi/blob/master/BUILD.autotools.md

Builds HIDAPI for an embedded Linux target using Autotools, setting up necessary PKG_CONFIG environment variables for cross-compilation.

```sh
PKG_CONFIG_DIR= \
PKG_CONFIG_LIBDIR=$STAGING/lib/pkgconfig:$STAGING/share/pkgconfig \
PKG_CONFIG_SYSROOT_DIR=$STAGING \
./configure --host=$HOST --prefix=$STAGING
# make / make install - same as for a regular build
```

--------------------------------

### Enable C++ Language if Required

Source: https://github.com/libusb/hidapi/blob/master/src/CMakeLists.txt

Enables the C++ compiler if the HIDAPI_BUILD_AS_CXX option is set to true. This allows the project to be built using C++ features.

```cmake
if(HIDAPI_BUILD_AS_CXX)
    enable_language(CXX)
endif()
```

--------------------------------

### Build HIDAPI Manually on Linux

Source: https://github.com/libusb/hidapi/blob/master/BUILD.md

Builds HIDAPI using manual makefiles on Linux. This method is primarily for understanding dependencies and is not recommended for system-wide shared libraries.

```sh
cd linux/
make -f Makefile-manual
```

--------------------------------

### Windows PP Data Dump Application Build Option

Source: https://github.com/libusb/hidapi/blob/master/CMakeLists.txt

Controls the build of a small Windows console application 'pp_data_dump.exe', defaulting to ON for Debug builds.

```cmake
if(WIN32)
    option(HIDAPI_BUILD_PP_DATA_DUMP "Build small Windows console application pp_data_dump.exe" ${IS_DEBUG_BUILD})
endif()
```

--------------------------------

### HIDAPI Test Application Build Option

Source: https://github.com/libusb/hidapi/blob/master/CMakeLists.txt

Controls the build of a small console test application 'hidtest', defaulting to ON for Debug builds.

```cmake
option(HIDAPI_BUILD_HIDTEST "Build small console test application hidtest" ${IS_DEBUG_BUILD})
if(HIDAPI_BUILD_HIDTEST)
    add_subdirectory(hidtest)
endif()
```

--------------------------------

### Executable Target for libusb Backend (Linux)

Source: https://github.com/libusb/hidapi/blob/master/hidtest/CMakeLists.txt

Adds an executable target 'hidtest_libusb' using 'test.c', defines 'USING_HIDAPI_LIBUSB', and links it against the 'hidapi::libusb' target. This is specific to Linux systems using libusb.

```cmake
add_executable(hidtest_libusb test.c)
target_compile_definitions(hidtest_libusb PRIVATE USING_HIDAPI_LIBUSB)
target_link_libraries(hidtest_libusb hidapi::libusb)
list(APPEND HIDAPI_HIDTEST_TARGETS hidtest_libusb)
```

--------------------------------

### Set Target Properties for NetBSD HidAPI

Source: https://github.com/libusb/hidapi/blob/master/netbsd/CMakeLists.txt

Configures properties for the NetBSD HidAPI target, including export name, output name, and versioning.

```cmake
set_target_properties(hidapi_netbsd
    PROPERTIES
        EXPORT_NAME "netbsd"
        OUTPUT_NAME "hidapi-netbsd"
        VERSION ${PROJECT_VERSION}
        SOVERSION ${PROJECT_VERSION_MAJOR}
        PUBLIC_HEADER "${HIDAPI_PUBLIC_HEADERS}"
)
```

--------------------------------

### Control HIDAPI Build Options as Subdirectory

Source: https://github.com/libusb/hidapi/blob/master/BUILD.cmake.md

Set variables like HIDAPI_WITH_LIBUSB and BUILD_SHARED_LIBS before adding the HIDAPI subdirectory to control its build configuration.

```cmake
set(HIDAPI_WITH_LIBUSB FALSE) # surely will be used only on Linux
set(BUILD_SHARED_LIBS FALSE) # HIDAPI as static library on all platforms
add_subdirectory(hidapi)
```

--------------------------------

### Define NetBSD HidAPI Library

Source: https://github.com/libusb/hidapi/blob/master/netbsd/CMakeLists.txt

Defines the NetBSD-specific HidAPI library, including public headers and source files. Sets the CXX language property if building as C++.

```cmake
add_library(hidapi_netbsd
    ${HIDAPI_PUBLIC_HEADERS}
    hid.c
)
if(HIDAPI_BUILD_AS_CXX)
    set_source_files_properties(hid.c PROPERTIES LANGUAGE CXX)
endif()
target_link_libraries(hidapi_netbsd PUBLIC hidapi_include)
```

--------------------------------

### Project Definition for HIDAPI

Source: https://github.com/libusb/hidapi/blob/master/CMakeLists.txt

Defines the project name as 'hidapi' and specifies C as the primary language.

```cmake
project(hidapi LANGUAGES C)
```

--------------------------------

### Executable Target for hidraw Backend (Linux)

Source: https://github.com/libusb/hidapi/blob/master/hidtest/CMakeLists.txt

Adds an executable target 'hidtest_hidraw' using 'test.c' and links it against the 'hidapi::hidraw' target. This is specific to Linux systems where hidraw is available.

```cmake
add_executable(hidtest_hidraw test.c)
target_link_libraries(hidtest_hidraw hidapi::hidraw)
list(APPEND HIDAPI_HIDTEST_TARGETS hidtest_hidraw)
```

--------------------------------

### Default Executable Target (Non-Linux/Windows/macOS)

Source: https://github.com/libusb/hidapi/blob/master/hidtest/CMakeLists.txt

Adds a default executable target 'hidtest' using 'test.c' and links it against the main 'hidapi::hidapi' target. This is used for platforms other than Linux, Windows, and macOS.

```cmake
add_executable(hidtest test.c)
target_link_libraries(hidtest hidapi::hidapi)
list(APPEND HIDAPI_HIDTEST_TARGETS hidtest)
```

--------------------------------

### Shared vs. Static Library Build Option

Source: https://github.com/libusb/hidapi/blob/master/CMakeLists.txt

Controls whether to build shared libraries (ON by default) or static libraries.

```cmake
option(BUILD_SHARED_LIBS "Build shared version of the libraries, otherwise build statically" ON)
```

--------------------------------

### Linking Libraries for Test Executable

Source: https://github.com/libusb/hidapi/blob/master/windows/test/CMakeLists.txt

Links the necessary HIDAPI libraries to the test executable.

```cmake
target_link_libraries(hid_report_reconstructor_test
     PRIVATE hidapi_include hidapi_winapi
)
```

--------------------------------

### AI Assistance Attribution Trailer

Source: https://github.com/libusb/hidapi/blob/master/AGENTS.md

Include this trailer at the end of every commit message to indicate which AI model assisted. Use the specified format: 'Assisted-by: AGENT_NAME:MODEL_VERSION'.

```markdown
Assisted-by: AGENT_NAME:MODEL_VERSION
```

--------------------------------

### Read Project Version from VERSION File

Source: https://github.com/libusb/hidapi/blob/master/src/CMakeLists.txt

Reads the project version from a file named VERSION. It expects the version to be in a 'MAJOR.MINOR.PATCH' format and extracts it. If the file is malformed, it will cause a fatal error.

```cmake
get_filename_component(PROJECT_ROOT "${CMAKE_CURRENT_LIST_DIR}/.." ABSOLUTE)

# Read version from file
file(READ "${PROJECT_ROOT}/VERSION" RAW_VERSION_STR)
string(REGEX MATCH "^([0-9]+\.[0-9]+\.[0-9]+)(.*)" VERSION_STR "${RAW_VERSION_STR}")

if(NOT VERSION_STR)
    message(FATAL_ERROR "Broken VERSION file, couldn't parse '${PROJECT_ROOT}/VERSION' with content: '${RAW_VERSION_STR}'")
endif()

set(VERSION "${CMAKE_MATCH_1}")
string(STRIP "${CMAKE_MATCH_2}" VERSION_SUFFIX)
# compatibility with find_package() vs add_subdirectory
set(hidapi_VERSION "${VERSION}" PARENT_SCOPE)
```

--------------------------------

### Configure Default Build Types

Source: https://github.com/libusb/hidapi/blob/master/CMakeLists.txt

Sets the default CMake build types and ensures CMAKE_BUILD_TYPE is set, defaulting to 'Release' if not specified.

```cmake
set(DEFAULT_CMAKE_BUILD_TYPES "Debug" "Release" "MinSizeRel" "RelWithDebInfo")
if(NOT DEFINED CMAKE_BUILD_TYPE OR NOT CMAKE_BUILD_TYPE)
    set(CMAKE_BUILD_TYPE "Release" CACHE STRING "${DEFAULT_CMAKE_BUILD_TYPES}" FORCE)
endif()
# This part is for convenience, when used one of the standard build types with cmake-gui
list(FIND DEFAULT_CMAKE_BUILD_TYPES "${CMAKE_BUILD_TYPE}" _build_type_index)
if(${_build_type_index} GREATER -1)
    # set it optionally, so a custom CMAKE_BUILD_TYPE can be used as well, if needed
    set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS ${DEFAULT_CMAKE_BUILD_TYPES})
endif()
unset(_build_type_index)
```

--------------------------------

### Link HIDAPI Library Dependencies

Source: https://github.com/libusb/hidapi/blob/master/windows/CMakeLists.txt

This snippet links the necessary HIDAPI include library to the main Windows library target.

```cmake
target_link_libraries(hidapi_winapi
    PUBLIC hidapi_include
)
```

--------------------------------

### Link ASan Options for Targets

Source: https://github.com/libusb/hidapi/blob/master/CMakeLists.txt

Applies ASan linker options to various HIDAPI targets if ASan is enabled and not using MSVC.

```cmake
if(HIDAPI_ENABLE_ASAN)
    if(NOT MSVC)
        # MSVC doesn't recognize those options, other compilers - requiring it
        foreach(HIDAPI_TARGET hidapi_winapi hidapi_darwin hidapi_hidraw hidapi_libusb hidtest_hidraw hidtest_libusb hidtest)
            if(TARGET ${HIDAPI_TARGET})
                if(BUILD_SHARED_LIBS)
                    target_link_options(${HIDAPI_TARGET} PRIVATE -fsanitize=address)
                else()
                    target_link_options(${HIDAPI_TARGET} PUBLIC -fsanitize=address)
                endif()
            endif()
        endforeach()
    endif()
endif()
```

--------------------------------

### Address Sanitizer (ASan) Option

Source: https://github.com/libusb/hidapi/blob/master/CMakeLists.txt

Enables the AddressSanitizer instrumentation for detecting memory errors during the build. Defaults to OFF.

```cmake
option(HIDAPI_ENABLE_ASAN "Build HIDAPI with ASAN address sanitizer instrumentation" OFF)
```

--------------------------------

### Set Target Properties for HIDAPI Windows Library

Source: https://github.com/libusb/hidapi/blob/master/windows/CMakeLists.txt

This snippet configures properties for the hidapi_winapi target, including its export name, output name, version, and public headers.

```cmake
set_target_properties(hidapi_winapi
    PROPERTIES
        EXPORT_NAME "winapi"
        OUTPUT_NAME "hidapi"
        VERSION ${PROJECT_VERSION}
        PUBLIC_HEADER "${HIDAPI_PUBLIC_HEADERS}"
)
```

--------------------------------

### Conditionally Compile HIDAPI with NO_ICONV

Source: https://github.com/libusb/hidapi/blob/master/BUILD.cmake.md

This snippet shows how to conditionally add the `NO_ICONV` compile definition to the `hidapi_libusb` target if it exists. This is useful for specific build configurations where iconv is not available or desired.

```cmake
add_subdirectory(hidapi)
if(TARGET hidapi_libusb)
  # see libusb/hid.c for usage of `NO_ICONV`
  target_compile_definitions(hidapi_libusb PRIVATE NO_ICONV)
endif()
```

--------------------------------

### Include pp_data_dump Subdirectory

Source: https://github.com/libusb/hidapi/blob/master/windows/CMakeLists.txt

This snippet conditionally includes the 'pp_data_dump' subdirectory if the HIDAPI_BUILD_PP_DATA_DUMP option is defined and enabled.

```cmake
if(DEFINED HIDAPI_BUILD_PP_DATA_DUMP AND HIDAPI_BUILD_PP_DATA_DUMP)
    add_subdirectory(pp_data_dump)
endif()
```

--------------------------------

### Print hidapi Version if Enabled

Source: https://github.com/libusb/hidapi/blob/master/src/CMakeLists.txt

Conditionally prints the hidapi version, including any suffix, if the HIDAPI_PRINT_VERSION variable is set to true. This is useful for build system feedback.

```cmake
if(DEFINED HIDAPI_PRINT_VERSION AND HIDAPI_PRINT_VERSION)
    set(HIDAPI_PRINT_VERSION "hidapi: v${VERSION}")
    if(VERSION_SUFFIX)
        set(HIDAPI_PRINT_VERSION "${HIDAPI_PRINT_VERSION} (${VERSION_SUFFIX})")
    endif()
    message(STATUS "${HIDAPI_PRINT_VERSION}")
endif()
```