mirror of
https://github.com/RPCS3/hidapi.git
synced 2024-11-26 19:40:35 +00:00
Documentation refactoring and update
- separate readme for HIDAPI build; - separate readme for HIDAPI build with Autotools; - add (separate) readme for HIDAPI build with CMake;
This commit is contained in:
Ihor Dutchak
parent
f5ada42915
commit
b7053119ed
106
BUILD.autotools.md
Normal file
106
BUILD.autotools.md
Normal file
@ -0,0 +1,106 @@
|
||||
# Building HIDAPI using Autotools
|
||||
|
||||
To be able to use Autotools to build HIDAPI, it has to be [installed](#installing-autotools)/available in the system.
|
||||
|
||||
Make sure you've checked [prerequisites](BUILD.md#prerequisites) and installed all required dependencies.
|
||||
|
||||
## Installing Autotools
|
||||
|
||||
HIDAPI uses few specific tools/packages from Autotools: `autoconf`, `automake`, `libtool`.
|
||||
|
||||
On different platforms or package managers, those could be named a bit differently or packaged together.
|
||||
You'll have to check the documentation/package list for your specific package manager.
|
||||
|
||||
### Linux
|
||||
|
||||
On Ubuntu the tools are available via APT:
|
||||
|
||||
```sh
|
||||
sudo apt install autoconf automake libtool
|
||||
```
|
||||
|
||||
### FreeBSD
|
||||
|
||||
FreeBSD Autotools can be installed as:
|
||||
|
||||
```sh
|
||||
pkg_add -r autotools
|
||||
```
|
||||
|
||||
Additionally, on FreeBSD you will need to install GNU make:
|
||||
```sh
|
||||
pkg_add -r gmake
|
||||
```
|
||||
|
||||
## Building HIDAPI with Autotools
|
||||
|
||||
A simple command list, to build HIDAPI with Autotools as a _shared library_ and install in into your system:
|
||||
|
||||
```sh
|
||||
./bootstrap # this prepares the configure script
|
||||
./configure
|
||||
make # build the library
|
||||
make install # as root, or using sudo, this will install hidapi into your system
|
||||
```
|
||||
|
||||
`./configure` can take several arguments which control the build. A few commonly used options:
|
||||
```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.
|
||||
```
|
||||
|
||||
|
||||
## Cross Compiling
|
||||
|
||||
This section talks about cross compiling HIDAPI for Linux using Autotools.
|
||||
This is useful for using HIDAPI on embedded Linux targets. These
|
||||
instructions assume the most raw kind of embedded Linux build, where all
|
||||
prerequisites will need to be built first. This process will of course vary
|
||||
based on your embedded Linux build system if you are using one, such as
|
||||
OpenEmbedded or Buildroot.
|
||||
|
||||
For the purpose of this section, it will be assumed that the following
|
||||
environment variables are exported.
|
||||
```sh
|
||||
$ export STAGING=$HOME/out
|
||||
$ export HOST=arm-linux
|
||||
```
|
||||
|
||||
`STAGING` and `HOST` can be modified to suit your setup.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Depending on what backend you want to cross-compile, you also need to prepare the dependencies:
|
||||
`libusb` for libusb HIDAPI backend, or `libudev` for hidraw HIDAPI backend.
|
||||
|
||||
An example of cross-compiling `libusb`. From `libusb` source directory, run:
|
||||
```sh
|
||||
./configure --host=$HOST --prefix=$STAGING
|
||||
make
|
||||
make install
|
||||
```
|
||||
|
||||
An example of cross-comping `libudev` is not covered by this section.
|
||||
Check `libudev`'s documentation for details.
|
||||
|
||||
### Building HIDAPI
|
||||
|
||||
Build HIDAPI:
|
||||
```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
|
||||
```
|
||||
223
BUILD.cmake.md
Normal file
223
BUILD.cmake.md
Normal file
@ -0,0 +1,223 @@
|
||||
# Building HIDAPI using CMake
|
||||
|
||||
To build HIDAPI with CMake, it has to be [installed](#installing-cmake)/available in the system.
|
||||
|
||||
Make sure you've checked [prerequisites](BUILD.md#prerequisites) and installed all required dependencies.
|
||||
|
||||
HIDAPI CMake build system allows you to build HIDAPI in two generally different ways:
|
||||
1) As a [standalone package/library](#standalone-package-build);
|
||||
2) As [part of a larger CMake project](#hidapi-as-a-subdirectory).
|
||||
|
||||
**TL;DR**: if you're experienced developer and have been working with CMake projects or have been written some of your own -
|
||||
most of this document may not be of interest for you; just check variables names, its default values and the target names.
|
||||
|
||||
## Installing CMake
|
||||
|
||||
CMake can be installed either using your system's package manager,
|
||||
or by downloading an installer/prebuilt version from the [official website](https://cmake.org/download/).
|
||||
|
||||
On most \*nix systems, the prefered way to install CMake is via package manager,
|
||||
e.g. `sudo apt install cmake`.
|
||||
|
||||
On Windows CMake could be provided by your development environment (e.g. by Visual Studio Installer or MinGW installer),
|
||||
or you may install it system-wise using the installer from the official website.
|
||||
|
||||
On macOS CMake may be installed by Homebrew/MacPorts or using the installer from the official website.
|
||||
|
||||
## Standalone package build
|
||||
|
||||
To build HIDAPI as a standalone package, you follow [general steps](https://cmake.org/runningcmake/) of building any CMake project.
|
||||
|
||||
An example of building HIDAPI with CMake:
|
||||
```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/
|
||||
```
|
||||
Such invocation will use the default (as per CMake magic) compiler/build environment available in your system.
|
||||
|
||||
You may pass some additional CMake variables to control the build configuration as `-D<CMake Variable>=value`.
|
||||
E.g.:
|
||||
```sh
|
||||
# install command now would install things into /usr
|
||||
cmake <HIDAPI source dir> -DCMAKE_INSTALL_PREFIX=/usr
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>Using a specific CMake generator</summary>
|
||||
|
||||
An example of using `Ninja` as a CMake generator:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
`-G` here specifies a native build system CMake would generate build files for.
|
||||
Check [CMake Documentation](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html) for a list of available generators (system-specific).
|
||||
|
||||
</details><br>
|
||||
|
||||
Some of the [standard](https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html) CMake variables you may want to use to configure a build:
|
||||
|
||||
- [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) - prefix where `install` target would install the library(ies);
|
||||
- [`CMAKE_BUILD_TYPE`](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html) - standard possible values: `Debug`, `Release`, `RelWithDebInfo`, `MinSizeRel`; Defaults to `Release` for HIDAPI, if not specified;
|
||||
- [`BUILD_SHARED_LIBS`](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html) - when set to TRUE, HIDAPI is built as a shared library, otherwise build statically; Defaults to `TRUE` for HIDAPI, if not specified;
|
||||
|
||||
<details>
|
||||
<summary>macOS-specific variables</summary>
|
||||
|
||||
- [`CMAKE_FRAMEWORK`](https://cmake.org/cmake/help/latest/variable/CMAKE_FRAMEWORK.html) - (since CMake 3.15) when set to TRUE, HIDAPI is built as a framework library, otherwise build as a regular static/shared library; Defaults to `FALSE` for HIDAPI, if not specified;
|
||||
- [`CMAKE_OSX_DEPLOYMENT_TARGET`](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_DEPLOYMENT_TARGET.html) - minimum version of the target platform (e.g. macOS or iOS) on which the target binaries are to be deployed; defaults to a maximum supported target platform by currently used XCode/Toolchain;
|
||||
|
||||
</details><br>
|
||||
|
||||
HIDAPI-specific CMake variables:
|
||||
|
||||
- `HIDAPI_BUILD_HIDTEST` - when set to TRUE, build a small test application `hidtest`;
|
||||
|
||||
<details>
|
||||
<summary>Linux-specific variables</summary>
|
||||
|
||||
- `HIDAPI_WITH_HIDRAW` - when set to TRUE, build HIDRAW-based implementation of HIDAPI (`hidapi-hidraw`), otherwise don't build it; defaults to TRUE;
|
||||
- `HIDAPI_WITH_LIBUSB` - when set to TRUE, build LIBUSB-based implementation of HIDAPI (`hidapi-libusb`), otherwise don't build it; defaults to TRUE;
|
||||
|
||||
**NOTE**: at least one of `HIDAPI_WITH_HIDRAW` or `HIDAPI_WITH_LIBUSB` has to be set to TRUE.
|
||||
|
||||
</details><br>
|
||||
|
||||
To see all most-useful CMake variables available for HIDAPI, one of the most convenient ways is too use [`cmake-gui`](https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html) tool ([example](https://cmake.org/runningcmake/)).
|
||||
|
||||
_NOTE_: HIDAPI packages built by CMake can be used with `pkg-config`, as if built with [Autotools](BUILD.autotools.md).
|
||||
|
||||
### MSVC and Ninja
|
||||
It is possible to build a CMake project (including HIDAPI) using MSVC compiler and Ninja (for medium and larger projects it is so much faster than msbuild).
|
||||
|
||||
For that:
|
||||
1) Open cmd.exe;
|
||||
2) Setup MSVC build environment variables, e.g.: `vcvarsall.bat x64`, where:
|
||||
- `vcvarsall.bat` is an environment setup script of your MSVC toolchain installation;<br>For MSVC 2019 Community edition it is located at: `C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\`;
|
||||
- `x64` -a target architecture to build;
|
||||
3) Follow general build steps, and use `Ninja` as a generator.
|
||||
|
||||
### Using HIDAPI in a CMake project
|
||||
|
||||
When HIDAPI is used as a standalone package (either installed into the system or built manually and installed elsewhere), the simplest way to use it is as showed in the example:
|
||||
|
||||
```cmake
|
||||
project(my_application)
|
||||
|
||||
add_executable(my_application main.c)
|
||||
|
||||
find_package(hidapi REQUIRED)
|
||||
target_link_libraries(my_application PRIVATE hidapi::hidapi)
|
||||
```
|
||||
|
||||
If HIDAPI isn't installed in your system, or `find_package` cannot find HIDAPI by default for any other reasons,
|
||||
the recommended way manually specify which HIDAPI package to use is via `hidapi_ROOT` CMake variable, e.g.:
|
||||
`-Dhidapi_ROOT=<path to HIDAPI installation prefix>`.
|
||||
|
||||
_NOTE_: usage of `hidapi_ROOT` is only possible (and recommended) with CMake 3.12 and higher. For older versions of CMake you'd need to specify [`CMAKE_PREFIX_PATH`](https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html#variable:CMAKE_PREFIX_PATH) instead.
|
||||
|
||||
Check with [`find_package`](https://cmake.org/cmake/help/latest/command/find_package.html) documentation if you need more details.
|
||||
|
||||
Available CMake targets after successful `find_package(hidapi)`:
|
||||
- `hidapi::hidapi` - indented to be used in most cases;
|
||||
- `hidapi::include` - if you need only to include `<hidapi.h>` but not link against the library;
|
||||
- `hidapi::winapi` - same as `hidapi::hidapi` on Windows; available only on Windows;
|
||||
- `hidapi::darwin` - same as `hidapi::hidapi` on macOS; available only on macOS;
|
||||
- `hidapi::libusb` - available when libusb backend is used/available;
|
||||
- `hidapi::hidraw` - available when hidraw backend is used/available on Linux;
|
||||
|
||||
**NOTE**: on Linux often both `hidapi::libusb` and `hidapi::hidraw` backends are available; in that case `hidapi::hidapi` is an alias for **`hidapi::hidraw`**. The motivation is that `hidraw` backend is a native Linux kernel implementation of HID protocol, and supports various HID devices (USB, Bluetooth, I2C, etc.). If `hidraw` backend isn't built at all (`hidapi::libusb` is the only target) - `hidapi::hidapi` is an alias for `hidapi::libusb`.
|
||||
If you're developing a cross-platform application and you are sure you need to use `libusb` backend on Linux, the simple way to achieve this is:
|
||||
```cmake
|
||||
if(TARGET hidapi::libusb)
|
||||
target_link_libraries(my_project PRIVATE hidapi::libusb)
|
||||
else()
|
||||
target_link_libraries(my_project PRIVATE hidapi::hidapi)
|
||||
endif()
|
||||
```
|
||||
|
||||
## HIDAPI as a subdirectory
|
||||
|
||||
HIDAPI can be easily used as a subdirectory of a larger CMake project:
|
||||
```cmake
|
||||
# root CMakeLists.txt
|
||||
cmake_minimum_required(VERSION 3.4.3 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)
|
||||
```
|
||||
Lets call this "larger project" a "host project".
|
||||
|
||||
All of the variables described in [standalone build](#standalone-package-build) section can be used to control HIDAPI build in case of a subdirectory, e.g.:
|
||||
```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)
|
||||
```
|
||||
|
||||
There is two important differences in the behavior of HIDAPI CMake build system when CMake is built as standalone package vs subdirectory build:
|
||||
|
||||
1) In _standalone build_ a number of standard and HIDAPI-specific variables are marked as _cache variables_ or _options_.
|
||||
This is done for convenience: when you're building HIDAPI as a standalone package and using tools like `cmake-gui` - those are highlighted as variables that can be changed and has some short description/documentation. E.g.:
|
||||
<br>
|
||||
E.g.2:<br>
|
||||
<br>
|
||||
When HIDAPI is built as a _subdirectory_ - **_none of the variables are marked for cache or as options_** by HIDAPI.
|
||||
This is done to let the host project's developer decide what is important (what needs to be highlighted) and what's not.
|
||||
|
||||
2) The default behavior/default value for some of the variables is a bit different:
|
||||
- by default, none of HIDAPI targets are [installed](https://cmake.org/cmake/help/latest/command/install.html); if required, HIDAPI targets can be installed by host project _after_ including HIDAPI subdirectory (requires CMake 3.13 or later); **or**, the default installation can be enabled by setting `HIDAPI_INSTALL_TARGETS` variable _before_ including HIDAPI subdirectory.
|
||||
HIDAPI uses [GNUInstallDirs](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html) to specify install locations. Variables like `CMAKE_INSTALL_LIBDIR` can be used to control HIDAPI's installation locations. E.g.:
|
||||
```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)
|
||||
```
|
||||
- HIDAPI prints its version during the configuration when built as a standalone package; to enable this for subdirectory builds - set `HIDAPI_PRINT_VERSION` to TRUE before including HIDAPI;
|
||||
|
||||
Available CMake targets after `add_subdirectory(hidapi)` _are the same as in case of [standalone build](#standalone-package-build)_, and a few additional ones:
|
||||
- `hidapi_include` - the interface library; `hidapi::hidapi` is an alias of it;
|
||||
- `hidapi_winapi` - library target on Windows; `hidapi::winapi` is an alias of it;
|
||||
- `hidapi_darwin` - library target on macOS; `hidapi::darwin` is an alias of it;
|
||||
- `hidapi_libusb` - library target for libusb backend; `hidapi::libusb` is an alias of it;
|
||||
- `hidapi_hidraw` - library target for hidraw backend; `hidapi::hidraw` is an alias of it;
|
||||
- `hidapi-libusb` - an alias of `hidapi_libusb` for compatibility with raw library name;
|
||||
- `hidapi-hidraw` - an alias of `hidapi_hidraw` for compatibility with raw library name;
|
||||
- `hidapi` - an alias of `hidapi_winapi` or `hidapi_darwin` on Windows or macOS respectfully.
|
||||
|
||||
Advanced:
|
||||
- Why would I need additional targets described in this section above, if I already have alias targets compatible with `find_package`?
|
||||
- an example:
|
||||
```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()
|
||||
```
|
||||
122
BUILD.md
Normal file
122
BUILD.md
Normal file
@ -0,0 +1,122 @@
|
||||
# Building HIDAPI from Source
|
||||
|
||||
## Table of content
|
||||
|
||||
* [Intro](#intro)
|
||||
* [Prerequisites](#prerequisites)
|
||||
* [Linux](#linux)
|
||||
* [FreeBSD](#freebsd)
|
||||
* [Mac](#mac)
|
||||
* [Windows](#windows)
|
||||
* [Integrating hidapi directly into your source tree](#integrating-hidapi-directly-into-your-source-tree)
|
||||
* [Building the manual way on Unix platforms](#building-the-manual-way-on-unix-platforms)
|
||||
* [Building on Windows](#building-on-windows)
|
||||
|
||||
## Intro
|
||||
|
||||
For various reasons you may need to build HIDAPI on your own.
|
||||
|
||||
It can be done in several different ways:
|
||||
- using [Autotools](BUILD.autotools.md);
|
||||
- using [CMake](BUILD.cmake.md);
|
||||
- using [manual makefiles](#building-the-manual-way-on-unix-platforms).
|
||||
|
||||
**Autotools** build system is historically first mature build system for
|
||||
HIDAPI. Most common usage of it is in its separate README: [BUILD.autotools.md](BUILD.autotools.md).
|
||||
|
||||
**CMake** build system is de facto an industry standard for many open-source and proprietary projects and solutions.
|
||||
HIDAPI is one of the projects which uses the power of CMake for its advantage.
|
||||
More documentation is available in its separate README: [BUILD.cmake.md](BUILD.cmake.md).
|
||||
|
||||
If you don't know where to start to build HIDAPI, we recommend starting with [CMake](BUILD.cmake.md) build.
|
||||
|
||||
## Prerequisites:
|
||||
|
||||
Regardless of what build system system you choose to use, there are specific dependencies for each platform/backend.
|
||||
|
||||
### Linux:
|
||||
|
||||
Depending on which backend you're going to build, you'll need to install
|
||||
additional development packages. For `linux/hidraw` backend you need
|
||||
development package for `libudev`. For `libusb` backend, naturally, you need
|
||||
`libusb` development package.
|
||||
|
||||
On Debian/Ubuntu systems these can be installed by running:
|
||||
```sh
|
||||
# required only by hidraw backend
|
||||
sudo apt install libudev-dev
|
||||
# required only by libusb backend
|
||||
sudo apt install libusb-1.0-0-dev
|
||||
```
|
||||
|
||||
### FreeBSD:
|
||||
|
||||
On FreeBSD you will need to install libiconv. This is done by running
|
||||
the following:
|
||||
```sh
|
||||
pkg_add -r libiconv
|
||||
```
|
||||
|
||||
### Mac:
|
||||
|
||||
On Mac make sure you have XCode installed and its Command Line Tools.
|
||||
|
||||
### Windows:
|
||||
|
||||
On Windows you just need a compiler. You may use Visual Studio or Cygwin/MinGW,
|
||||
depending on which environment is best for your needs.
|
||||
|
||||
## Integrating HIDAPI directly into your source tree
|
||||
|
||||
Instead of using one of the provided build systems, you may want to integrate
|
||||
HIDAPI directly into your source tree.
|
||||
Generally it is not encouraged to do so, but if you must, all you need to do:
|
||||
- add a single source file `hid.c` (for a specific backend);
|
||||
- setup include directory to `<HIDAPI repo root>/hidapi`;
|
||||
- add link libraries, that are specific for each backend.
|
||||
|
||||
Check the manual makefiles for a simple example/reference of what are the dependencies of each specific backend.
|
||||
|
||||
NOTE: if your have a CMake-based project, you're likely be able to use
|
||||
HIDAPI directly as a subdirectory. Check [BUILD.cmake.md](BUILD.cmake.md) for details.
|
||||
|
||||
## Building the manual way on Unix platforms
|
||||
|
||||
Manual Makefiles are provided mostly to give the user an idea what it takes
|
||||
to build a program which embeds HIDAPI directly inside of it. These should
|
||||
really be used as examples only. If you want to build a system-wide shared
|
||||
library, use one of the build systems mentioned above.
|
||||
|
||||
To build HIDAPI using the manual Makefiles, change to the directory
|
||||
of your platform and run make. For example, on Linux run:
|
||||
```sh
|
||||
cd linux/
|
||||
make -f Makefile-manual
|
||||
```
|
||||
|
||||
## Building on Windows
|
||||
|
||||
To build the HIDAPI DLL on Windows using Visual Studio, build the `.sln` file
|
||||
in the `windows/` directory.
|
||||
|
||||
To build HIDAPI using MinGW or Cygwin using Autotools, use a general Autotools
|
||||
[instruction](BUILD.autotools.md).
|
||||
|
||||
Any windows builds (MSVC or MinGW/Cygwin) are also supported by [CMake](BUILD.cmake.md).
|
||||
|
||||
HIDAPI can also be built using the Windows DDK (now also called the Windows
|
||||
Driver Kit or WDK). This method was originally required for the HIDAPI build
|
||||
but not anymore. However, some users still prefer this method. It is not as
|
||||
well supported anymore but should still work. Patches are welcome if it does
|
||||
not. To build using the DDK:
|
||||
|
||||
1. Install the Windows Driver Kit (WDK) from Microsoft.
|
||||
2. From the Start menu, in the Windows Driver Kits folder, select Build
|
||||
Environments, then your operating system, then the x86 Free Build
|
||||
Environment (or one that is appropriate for your system).
|
||||
3. From the console, change directory to the `windows/ddk_build/` directory,
|
||||
which is part of the HIDAPI distribution.
|
||||
4. Type build.
|
||||
5. You can find the output files (DLL and LIB) in a subdirectory created
|
||||
by the build system which is appropriate for your environment. On
|
||||
Windows XP, this directory is `objfre_wxp_x86/i386`.
|
||||
274
README.md
274
README.md
@ -19,30 +19,20 @@ It was moved to [libusb/hidapi](https://github.com/libusb/hidapi) on June 4th, 2
|
||||
## Table of Contents
|
||||
|
||||
* [About](#about)
|
||||
* [Test GUI](#test-gui)
|
||||
* [What Does the API Look Like?](#what-does-the-api-look-like)
|
||||
* [License](#license)
|
||||
* [Download](#download)
|
||||
* [Build Instructions](#build-instructions)
|
||||
* [Prerequisites](#prerequisites)
|
||||
* [Linux](#linux)
|
||||
* [FreeBSD](#freebsd)
|
||||
* [Mac](#mac)
|
||||
* [Windows](#windows)
|
||||
* [Building HIDAPI into a shared library on Unix Platforms](#building-hidapi-into-a-shared-library-on-unix-platforms)
|
||||
* [Building the manual way on Unix platforms](#building-the-manual-way-on-unix-platforms)
|
||||
* [Building on Windows](#building-on-windows)
|
||||
* [Cross Compiling](#cross-compiling)
|
||||
* [Prerequisites](#prerequisites-1)
|
||||
* [Building HIDAPI](#building-hidapi)
|
||||
* [Installing HIDAPI](#installing-hidapi)
|
||||
* [Build from Source](#build-from-source)
|
||||
|
||||
|
||||
## About
|
||||
|
||||
HIDAPI has five back-ends:
|
||||
HIDAPI has four back-ends:
|
||||
* Windows (using `hid.dll`)
|
||||
* Linux/hidraw (using the Kernel's hidraw driver)
|
||||
* Linux/libusb (using libusb-1.0)
|
||||
* FreeBSD (using libusb-1.0)
|
||||
* Mac (using IOHidManager)
|
||||
* libusb (using libusb-1.0 - Linux/BSD/other UNIX-like systems)
|
||||
* macOS (using IOHidManager)
|
||||
|
||||
On Linux, either the hidraw or the libusb back-end can be used. There are
|
||||
tradeoffs, and the functionality supported is slightly different. Both are
|
||||
@ -50,9 +40,9 @@ built by default. It is up to the application linking to hidapi to choose
|
||||
the backend at link time by linking to either `libhidapi-libusb` or
|
||||
`libhidapi-hidraw`.
|
||||
|
||||
Note that you will need to install a udev rule file with your application
|
||||
Note that you will need to install an udev rule file with your application
|
||||
for unprivileged users to be able to access HID devices with hidapi. Refer
|
||||
to the [69-hid-udev.rules](udev/69-hid-udev.rules) file in the `udev` directory
|
||||
to the [69-hid.rules](udev/69-hid.rules) file in the `udev` directory
|
||||
for an example.
|
||||
|
||||
__Linux/hidraw__ (`linux/hid.c`):
|
||||
@ -70,12 +60,22 @@ __Linux/FreeBSD/libusb__ (`libusb/hid.c`):
|
||||
This back-end uses libusb-1.0 to communicate directly to a USB device. This
|
||||
back-end will of course not work with Bluetooth devices.
|
||||
|
||||
### Test GUI
|
||||
|
||||
HIDAPI also comes with a Test GUI. The Test GUI is cross-platform and uses
|
||||
Fox Toolkit <http://www.fox-toolkit.org>. It will build on every platform
|
||||
which HIDAPI supports. Since it relies on a 3rd party library, building it
|
||||
is optional but recommended because it is so useful when debugging hardware.
|
||||
|
||||
NOTE: Test GUI based on Fox Toolkit is not actively developed nor supported
|
||||
by HIDAPI team. It is kept as a historical artifact. It may even work sometime
|
||||
or on some platforms, but it is not going to get any new features or bugfixes.
|
||||
|
||||
Instructions for installing Fox-Toolkit on each platform is not provided.
|
||||
Make sure to use Fox-Toolkit v1.6 if you choose to use it.
|
||||
|
||||
## What Does the API Look Like?
|
||||
|
||||
The API provides the most commonly used HID functions including sending
|
||||
and receiving of input, output, and feature reports. The sample program,
|
||||
which communicates with a heavily hacked up version of the Microchip USB
|
||||
@ -158,231 +158,25 @@ as a starting point for your applications.
|
||||
|
||||
|
||||
## License
|
||||
|
||||
HIDAPI may be used by one of three licenses as outlined in [LICENSE.txt](LICENSE.txt).
|
||||
|
||||
## Download
|
||||
HIDAPI can be downloaded from GitHub
|
||||
## Installing HIDAPI
|
||||
|
||||
If you want to build your own application that uses HID devices with HIDAPI,
|
||||
you need to get HIDAPI development package.
|
||||
|
||||
Depending on what your development environment is, HIDAPI likely to be provided
|
||||
by your package manager.
|
||||
|
||||
For instance on Ubuntu, HIDAPI is available via APT:
|
||||
```sh
|
||||
git clone git://github.com/libusb/hidapi.git
|
||||
sudo apt install libhidapi-dev
|
||||
```
|
||||
|
||||
## Build Instructions
|
||||
HIDAPI package name for other systems/package managers may differ.
|
||||
Check the documentation/package list of your package manager.
|
||||
|
||||
This section is long. Don't be put off by this. It's not long because it's
|
||||
complicated to build HIDAPI; it's quite the opposite. This section is long
|
||||
because of the flexibility of HIDAPI and the large number of ways in which
|
||||
it can be built and used. You will likely pick a single build method.
|
||||
## Build from Source
|
||||
|
||||
HIDAPI can be built in several different ways. If you elect to build a
|
||||
shared library, you will need to build it from the HIDAPI source
|
||||
distribution. If you choose instead to embed HIDAPI directly into your
|
||||
application, you can skip the building and look at the provided platform
|
||||
Makefiles for guidance. These platform Makefiles are located in `linux/`,
|
||||
`libusb/`, `mac/` and `windows/` and are called `Makefile-manual`. In addition,
|
||||
Visual Studio projects are provided. Even if you're going to embed HIDAPI
|
||||
into your project, it is still beneficial to build the example programs.
|
||||
|
||||
|
||||
### Prerequisites:
|
||||
|
||||
#### Linux:
|
||||
On Linux, you will need to install development packages for libudev,
|
||||
libusb and optionally Fox-toolkit (for the test GUI). On
|
||||
Debian/Ubuntu systems these can be installed by running:
|
||||
```sh
|
||||
sudo apt-get install libudev-dev libusb-1.0-0-dev libfox-1.6-dev
|
||||
```
|
||||
|
||||
If you downloaded the source directly from the git repository (using
|
||||
git clone), you'll need Autotools:
|
||||
```sh
|
||||
sudo apt-get install autotools-dev autoconf automake libtool
|
||||
```
|
||||
|
||||
#### FreeBSD:
|
||||
On FreeBSD you will need to install GNU make, libiconv, and
|
||||
optionally Fox-Toolkit (for the test GUI). This is done by running
|
||||
the following:
|
||||
```sh
|
||||
pkg_add -r gmake libiconv fox16
|
||||
```
|
||||
|
||||
If you downloaded the source directly from the git repository (using
|
||||
git clone), you'll need Autotools:
|
||||
```sh
|
||||
pkg_add -r autotools
|
||||
```
|
||||
|
||||
#### Mac:
|
||||
On Mac, you will need to install Fox-Toolkit if you wish to build
|
||||
the Test GUI. There are two ways to do this, and each has a slight
|
||||
complication. Which method you use depends on your use case.
|
||||
|
||||
If you wish to build the Test GUI just for your own testing on your
|
||||
own computer, then the easiest method is to install Fox-Toolkit
|
||||
using ports:
|
||||
```sh
|
||||
sudo port install fox
|
||||
```
|
||||
|
||||
If you wish to build the TestGUI app bundle to redistribute to
|
||||
others, you will need to install Fox-toolkit from source. This is
|
||||
because the version of fox that gets installed using ports uses the
|
||||
ports X11 libraries which are not compatible with the Apple X11
|
||||
libraries. If you install Fox with ports and then try to distribute
|
||||
your built app bundle, it will simply fail to run on other systems.
|
||||
To install Fox-Toolkit manually, download the source package from
|
||||
<http://www.fox-toolkit.org>, extract it, and run the following from
|
||||
within the extracted source:
|
||||
```sh
|
||||
./configure && make && make install
|
||||
```
|
||||
|
||||
#### Windows:
|
||||
On Windows, if you want to build the test GUI, you will need to get
|
||||
the `hidapi-externals.zip` package from the download site. This
|
||||
contains pre-built binaries for Fox-toolkit. Extract
|
||||
`hidapi-externals.zip` just outside of hidapi, so that
|
||||
hidapi-externals and hidapi are on the same level, as shown:
|
||||
```
|
||||
Parent_Folder
|
||||
|
|
||||
+hidapi
|
||||
+hidapi-externals
|
||||
```
|
||||
Again, this step is not required if you do not wish to build the
|
||||
test GUI.
|
||||
|
||||
|
||||
### Building HIDAPI into a shared library on Unix Platforms:
|
||||
|
||||
On Unix-like systems such as Linux, FreeBSD, macOS, and even Windows, using
|
||||
MinGW or Cygwin, the easiest way to build a standard system-installed shared
|
||||
library is to use the GNU Autotools build system. If you checked out the
|
||||
source from the git repository, run the following:
|
||||
|
||||
```sh
|
||||
./bootstrap
|
||||
./configure
|
||||
make
|
||||
make install # as root, or using sudo
|
||||
```
|
||||
|
||||
If you downloaded a source package (i.e.: if you did not run git clone), you
|
||||
can skip the `./bootstrap` step.
|
||||
|
||||
`./configure` can take several arguments which control the build. The two most
|
||||
likely to be used are:
|
||||
```sh
|
||||
--enable-testgui
|
||||
Enable build of the Test GUI. This requires Fox toolkit to
|
||||
be installed. Instructions for installing Fox-Toolkit on
|
||||
each platform are in the Prerequisites section above.
|
||||
|
||||
--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.
|
||||
```
|
||||
### Building the manual way on Unix platforms:
|
||||
|
||||
Manual Makefiles are provided mostly to give the user and idea what it takes
|
||||
to build a program which embeds HIDAPI directly inside of it. These should
|
||||
really be used as examples only. If you want to build a system-wide shared
|
||||
library, use the Autotools method described above.
|
||||
|
||||
To build HIDAPI using the manual Makefiles, change to the directory
|
||||
of your platform and run make. For example, on Linux run:
|
||||
```sh
|
||||
cd linux/
|
||||
make -f Makefile-manual
|
||||
```
|
||||
|
||||
To build the Test GUI using the manual makefiles:
|
||||
```sh
|
||||
cd testgui/
|
||||
make -f Makefile-manual
|
||||
```
|
||||
|
||||
### Building on Windows:
|
||||
|
||||
To build the HIDAPI DLL on Windows using Visual Studio, build the `.sln` file
|
||||
in the `windows/` directory.
|
||||
|
||||
To build the Test GUI on windows using Visual Studio, build the `.sln` file in
|
||||
the `testgui/` directory.
|
||||
|
||||
To build HIDAPI using MinGW or Cygwin using Autotools, use the instructions
|
||||
in the section [Building HIDAPI into a shared library on Unix Platforms](#building-hidapi-into-a-shared-library-on-unix-platforms)
|
||||
above. Note that building the Test GUI with MinGW or Cygwin will
|
||||
require the Windows procedure in the [Prerequisites](#prerequisites-1) section
|
||||
above (i.e.: `hidapi-externals.zip`).
|
||||
|
||||
To build HIDAPI using MinGW using the Manual Makefiles, see the section
|
||||
[Building the manual way on Unix platforms](#building-the-manual-way-on-unix-platforms)
|
||||
above.
|
||||
|
||||
HIDAPI can also be built using the Windows DDK (now also called the Windows
|
||||
Driver Kit or WDK). This method was originally required for the HIDAPI build
|
||||
but not anymore. However, some users still prefer this method. It is not as
|
||||
well supported anymore but should still work. Patches are welcome if it does
|
||||
not. To build using the DDK:
|
||||
|
||||
1. Install the Windows Driver Kit (WDK) from Microsoft.
|
||||
2. From the Start menu, in the Windows Driver Kits folder, select Build
|
||||
Environments, then your operating system, then the x86 Free Build
|
||||
Environment (or one that is appropriate for your system).
|
||||
3. From the console, change directory to the `windows/ddk_build/` directory,
|
||||
which is part of the HIDAPI distribution.
|
||||
4. Type build.
|
||||
5. You can find the output files (DLL and LIB) in a subdirectory created
|
||||
by the build system which is appropriate for your environment. On
|
||||
Windows XP, this directory is `objfre_wxp_x86/i386`.
|
||||
|
||||
## Cross Compiling
|
||||
|
||||
This section talks about cross compiling HIDAPI for Linux using Autotools.
|
||||
This is useful for using HIDAPI on embedded Linux targets. These
|
||||
instructions assume the most raw kind of embedded Linux build, where all
|
||||
prerequisites will need to be built first. This process will of course vary
|
||||
based on your embedded Linux build system if you are using one, such as
|
||||
OpenEmbedded or Buildroot.
|
||||
|
||||
For the purpose of this section, it will be assumed that the following
|
||||
environment variables are exported.
|
||||
```sh
|
||||
$ export STAGING=$HOME/out
|
||||
$ export HOST=arm-linux
|
||||
```
|
||||
|
||||
`STAGING` and `HOST` can be modified to suit your setup.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Note that the build of libudev is the very basic configuration.
|
||||
|
||||
Build libusb. From the libusb source directory, run:
|
||||
```sh
|
||||
./configure --host=$HOST --prefix=$STAGING
|
||||
make
|
||||
make install
|
||||
```
|
||||
|
||||
Build libudev. From the libudev source directory, run:
|
||||
```sh
|
||||
./configure --disable-gudev --disable-introspection --disable-hwdb \
|
||||
--host=$HOST --prefix=$STAGING
|
||||
make
|
||||
make install
|
||||
```
|
||||
|
||||
### Building HIDAPI
|
||||
|
||||
Build HIDAPI:
|
||||
```
|
||||
PKG_CONFIG_DIR= \
|
||||
PKG_CONFIG_LIBDIR=$STAGING/lib/pkgconfig:$STAGING/share/pkgconfig \
|
||||
PKG_CONFIG_SYSROOT_DIR=$STAGING \
|
||||
./configure --host=$HOST --prefix=$STAGING
|
||||
```
|
||||
Check [BUILD.md](BUILD.md) for details.
|
||||
|
||||
BIN
documentation/cmake-gui-drop-down.png
Normal file
BIN
documentation/cmake-gui-drop-down.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
BIN
documentation/cmake-gui-highlights.png
Normal file
BIN
documentation/cmake-gui-highlights.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 76 KiB |
Loading…
Reference in New Issue
Block a user