Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README: explicit statement on single source build #370

Merged
merged 6 commits into from
May 2, 2022
Merged

README: explicit statement on single source build #370

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5718af1
Update README.md
Youw Jan 22, 2022
7399b43
Update README.md
Youw Jan 22, 2022
023b9d2
Update BUILD.md
Youw Jan 22, 2022
e522f95
more updates
Youw Apr 25, 2022
060f000
Merge remote-tracking branch 'origin/master' into build-readme
Youw Apr 25, 2022
bb9fac2
fix typo
Youw Apr 25, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
more updates
  • Loading branch information
@Youw
Youw committed Apr 25, 2022
commit e522f9555b754c3855c25c98b5ee431f1ec70fce
56 changes: 23 additions & 33 deletions BUILD.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,9 @@
* [FreeBSD](#freebsd)
* [Mac](#mac)
* [Windows](#windows)
* [Integrating hidapi directly into your source tree](#integrating-hidapi-directly-into-your-source-tree)
* [Embedding HIDAPI directly into your source tree](#embedding-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)
* [Embedding source code directly](#embedding-source-code-directly)

## Intro

Expand Down Expand Up @@ -69,19 +68,31 @@ On Mac make sure you have XCode installed and its Command Line Tools.
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
## Embedding 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.
Instead of using one of the provided standalone build systems,
you may want to integrate HIDAPI directly into your source tree.

Check the manual makefiles for a simple example/reference of what are the dependencies of each specific backend.
---
If your project uses CMake as a build system, it is safe to add HIDAPI as a [subdirectory](BUILD.cmake.md#hidapi-as-a-subdirectory).

---
If _the only option_ that works for you is adding HIDAPI sources directly
to your project's build system, then you need:
- include a _single source file_ into your project's build system,
depending on your platform and the backend you want to use:
- [`windows\hid.c`](windows/hid.c);
- [`linux/hid.c`](windows/hid.c);
Youw marked this conversation as resolved.
Show resolved Hide resolved
- [`libusb/hid.c`](windows/hid.c);
- [`libusb/hid.c`](windows/hid.c);
- [`mac/hid.c`](windows/hid.c);
- add a [`hidapi`](hidapi) folder to the include path when building `hid.c`;
- make the platform/backend specific [dependencies](#prerequisites) available during the compilation/linking, when building `hid.c`;

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.
NOTE: the above doesn't guarantee that having a copy of `<backend>/hid.c` and `hidapi/hidapi.h` is enough to build HIDAPI.
The only guarantee that `<backend>/hid.c` includes all nesessary sources to compile it as a single file.

Check the manual makefiles for a simple example/reference of what are the dependencies of each specific backend.

## Building the manual way on Unix platforms

Expand Down Expand Up @@ -109,24 +120,3 @@ Any windows builds (MSVC or MinGW/Cygwin) are also supported by [CMake](BUILD.cm

If you are looking for information regarding DDK build of HIDAPI:
- the build has been broken for a while and now the support files are obsolete.

## Embedding source code directly

The recommended way of using HIDAPI is by using it as a library built with its own build system.

If for some reason you cannot use HIDAPI's build system,
directly or [indirectly](README.md#installing-hidapi),
or you really think that embedding HIDAPI directly as a source into your project
is the best available option for you - HIDAPI guarantees:
- you need to include a _single source file_ into your project's build system,
depending on your platform and the backend you want to use:
- [`windows\hid.c`](windows/hid.c);
- [`linux/hid.c`](windows/hid.c);
- [`libusb/hid.c`](windows/hid.c);
- [`libusb/hid.c`](windows/hid.c);
- [`mac/hid.c`](windows/hid.c);
- add a [`hidapi`](hidapi) forlder to the include path when building `hid.c`;
- make the platform/backend specific [dependencies](#prerequisites) available during the compilation/linking, when building `hid.c`;

NOTE: the above doesn't guarantee that having a copy of `<backend>/hid.c` and `hidapi/hidapi.h` is enough to build HIDAPI.
It only guarantee that `<backend>/hid.c` `#include`'s all nesessary sources to compile it as a single file.
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ with USB and Bluetooth HID-Class devices on Windows, Linux, FreeBSD, and macOS.
HIDAPI can be either built as a shared library (`.so`, `.dll` or `.dylib`) or
can be embedded directly into a target application by adding a _single source_
file (per platform) and a single header.<br>
See [remarks](BUILD.md#embedding-source-code-directly) on embedding _directly_ into your application.
See [remarks](BUILD.md#embedding-hidapi-directly-into-your-source-tree) on embedding _directly_ into your build system.

HIDAPI library was originally developed by Alan Ott ([signal11](https://github.com/signal11)).

Expand Down