1# Libusb Rust Bindings
2
3The `libusb1-sys` crate provides declarations and linkage for the `libusb` C library. Following the
4`*-sys` package conventions, the `libusb1-sys` crate does not define higher-level abstractions over
5the native `libusb` library functions.
6
7## Dependencies
8In order to use the `libusb1-sys` crate, you must have the `libusb` library installed where it can be
9found by `pkg-config`.
10
11All systems supported by `libusb` are also supported by the `libusb1-sys` crate. It's been tested on
12Linux, OS X, and Windows.
13
14### Cross-Compiling
15To link to a cross-compiled version of the native `libusb` library, it's necessary to set several
16environment variables to configure `pkg-config` to work with a cross-compiler's sysroot. [Autotools
17Mythbuster](https://autotools.io/) has a good explanation of [supporting
18cross-compilation](https://autotools.io/pkgconfig/cross-compiling.html) with `pkg-config`.
19
20However, Rust's [`pkg-config` build helper](https://github.com/alexcrichton/pkg-config-rs) doesn't
21support calling a `$CHOST`-prefixed `pkg-config`. It will always call `pkg-config` without a prefix.
22To cross-compile `libusb1-sys` with the `pkg-config` build helper, one must define the environment
23variables `PKG_CONFIG_DIR`, `PKG_CONFIG_LIBDIR`, and `PKG_CONFIG_SYSROOT_DIR` for the *default*
24`pkg-config`. It's also necessary to set `PKG_CONFIG_ALLOW_CROSS` to tell Rust's `pkg-config` helper
25that it's okay to proceed with a cross-compile.
26
27To adapt the `pkg-config` wrapper in the Autotools Mythbuster guide so that it works with Rust, one
28will end up with a script similar to the following:
29
30```sh
31#!/bin/sh
32
33SYSROOT=/build/root
34
35export PKG_CONFIG_DIR=
36export PKG_CONFIG_LIBDIR=${SYSROOT}/usr/lib/pkgconfig:${SYSROOT}/usr/share/pkgconfig
37export PKG_CONFIG_SYSROOT_DIR=${SYSROOT}
38export PKG_CONFIG_ALLOW_CROSS=1
39
40cargo build
41```
42
43## Usage
44Add `libusb1-sys` as a dependency in `Cargo.toml`:
45
46```toml
47[dependencies]
48libusb1-sys = "0.6"
49```
50
51Import the `libusb1_sys` crate and use the functions as they're defined in the native `libusb`
52library. See the [`libusb` 1.0 API documention](http://libusb.sourceforge.net/api-1.0/) for more
53usage information.
54
55```rust
56extern crate libusb1_sys as ffi;
57
58fn main() {
59  let version = unsafe { ffi::libusb_get_version() };
60
61  println!("libusb v{}.{}.{}.{}", version.major, version.minor, version.micro, version.nano);
62}
63```
64
65### Native dependencies
66
67`libusb1-sys` exports [metadata] so that dependent crates can find the correct `libusb.h` header
68and compile native code that depends on `libusb`. If a crate has a direct dependency on `libusb1-sys`,
69its build script has access to the following environment variables:
70
71* `DEP_USB_1.0_INCLUDE` contains the include path with the correct `libusb.h`
72* `DEP_USB_1.0_VENDORED` is set with a value of `1` if `libusb1-sys` compiled and linked to
73its vendored copy of `libusb`
74* `DEP_USB_1.0_STATIC`  is set with a value of `1` if static linkage has been used instead of
75dynamic.
76
77[metadata]: https://doc.rust-lang.org/cargo/reference/build-scripts.html#the-links-manifest-key
78
79### Finding Help
80Since `libusb1-sys` is no more than a wrapper around the native `libusb` library, the best source for
81help is the information already available for `libusb`:
82
83* [Home Page](http://libusb.info/)
84* [API Documentation](http://libusb.sourceforge.net/api-1.0/)
85* [Source](https://github.com/libusb/libusb)
86
87
88## License
89Distributed under the [MIT License](LICENSE).
90
91### License note.
92If you link native `libusb` library statically then you must follow [GNU LGPL](https://github.com/libusb/libusb/blob/master/COPYING) from libusb.
93