From fe48fa0853c633bee350d97596e607cbb20cf0ef Mon Sep 17 00:00:00 2001 From: Ihor Dutchak Date: Tue, 18 May 2021 03:15:57 +0300 Subject: [PATCH] documentation refactoring --- BUILD.autotools.md | 106 ++++++++++++++++++ BUILD.cmake.md | 8 ++ BUILD.md | 123 +++++++++++++++++++++ README.md | 265 +++++---------------------------------------- 4 files changed, 267 insertions(+), 235 deletions(-) create mode 100644 BUILD.autotools.md create mode 100644 BUILD.cmake.md create mode 100644 BUILD.md diff --git a/BUILD.autotools.md b/BUILD.autotools.md new file mode 100644 index 0000000..e10554e --- /dev/null +++ b/BUILD.autotools.md @@ -0,0 +1,106 @@ +# Building HIDAPI using Autotools + +To be able to use Autotools to build HIDAPI, it has to be installed/available in the system. + +Also, make sure you've checked [prerequisites](README.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 +``` diff --git a/BUILD.cmake.md b/BUILD.cmake.md new file mode 100644 index 0000000..5c1ca42 --- /dev/null +++ b/BUILD.cmake.md @@ -0,0 +1,8 @@ +# Building HIDAPI using CMake + +To build HIDAPI with CMake, it has to be installed/available in the system. + +CMake can be installed either using your system's package manager, +or by downloading an installer/prebuilt version from [official website](https://cmake.org/download/). + +TODO: finish me. diff --git a/BUILD.md b/BUILD.md new file mode 100644 index 0000000..b98efbd --- /dev/null +++ b/BUILD.md @@ -0,0 +1,123 @@ +# 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`; +- 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. Note: this solution is generated for MSVC 2015. + +If you need a solution for different version of Visual Studio you may generate +one using [CMake](BUILD.cmake.md). + +To build HIDAPI using MinGW or Cygwin using Autotools, use a general Autotools + [instruction](BUILD.autotools.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`. diff --git a/README.md b/README.md index 891bf68..30e7e7f 100644 --- a/README.md +++ b/README.md @@ -19,28 +19,19 @@ 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 four back-ends: * Windows (using `hid.dll`) * Linux/hidraw (using the Kernel's hidraw driver) -* libusb (using libusb-1.0 - Linux/BSD/other UNIX systems) +* 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 @@ -61,12 +52,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 . 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 @@ -149,231 +150,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 -, 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.