1# Rusb
2This crate provides a safe wrapper around the native `libusb` library. It applies the RAII pattern
3and Rust lifetimes to ensure safe usage of all `libusb` functionality. The RAII pattern ensures that
4all acquired resources are released when they're no longer needed, and Rust lifetimes ensure that
5resources are released in a proper order.
6
7* [Documentation](https://docs.rs/rusb)
8
9## Dependencies
10To use rusb no extra setup is required as rusb will automatically download the source for libusb and build it.
11
12However if building libusb fails you can also try setting up the native `libusb` library where it can
13be found by `pkg-config` or `vcpkg`.
14
15All systems supported by the native `libusb` library are also supported by the `libusb` crate. It's
16been tested on Linux, OS X, and Windows.
17
18### Cross-Compiling
19The `rusb` crate can be used when cross-compiling to a foreign target. Details on how to
20cross-compile `rusb` are explained in the [`libusb1-sys` crate's
21README](libusb1-sys/README.md#cross-compiling).
22
23## Usage
24Add `rusb` as a dependency in `Cargo.toml`:
25
26```toml
27[dependencies]
28rusb = "0.9"
29```
30
31Import the `rusb` crate. The starting point for nearly all `rusb` functionality is to create a
32context object. With a context object, you can list devices, read their descriptors, open them, and
33communicate with their endpoints:
34
35```rust
36fn main() {
37    for device in rusb::devices().unwrap().iter() {
38        let device_desc = device.device_descriptor().unwrap();
39
40        println!("Bus {:03} Device {:03} ID {:04x}:{:04x}",
41            device.bus_number(),
42            device.address(),
43            device_desc.vendor_id(),
44            device_desc.product_id());
45    }
46}
47```
48
49## License
50Distributed under the [MIT License](LICENSE).
51
52### License note.
53If you link native `libusb` (by example using `vendored` features) library statically then
54you must follow [GNU LGPL](https://github.com/libusb/libusb/blob/master/COPYING) from libusb.
55