Google Git
Sign in
android / platform / external / rust / crates / libusb1-sys / refs/heads/main
commit2c86fd081f2b2b5bc4bd66d47e2954ff4e90f61f[log] [tgz]
authorJames Farrell <[email protected]>Tue Dec 03 20:15:31 2024 +0000
committerAutomerger Merge Worker <[email protected]>Tue Dec 03 20:15:31 2024 +0000
tree85f15dcf536821e9f706ba4b25e98884f79f526f
parent1aaf223ac0c038d34ca931a4815f43cdeab70fc7 [diff]
parent724510b474fb4974892ce8014f971f0b8b52e06a [diff]
Migrate 9 newly imported crates to monorepo am: 724510b474

Original change: https://android-review.googlesource.com/c/platform/external/rust/crates/libusb1-sys/+/3387097

Change-Id: I208d3cada437667b73b17a3bbd555835b25dbab0
Signed-off-by: Automerger Merge Worker <[email protected]>
tree: 85f15dcf536821e9f706ba4b25e98884f79f526f
  1. src/
  2. tests/
  3. Android.bp
  4. build.rs
  5. Cargo.lock
  6. Cargo.toml
  7. Cargo.toml.orig
  8. CHANGELOG.md
  9. LICENSE
  10. METADATA
  11. module_block.bp.fragment
  12. module_block_platform.bp.fragment
  13. MODULE_LICENSE_MIT
  14. OWNERS
  15. README.md
README.md

Libusb Rust Bindings

The libusb1-sys crate provides declarations and linkage for the libusb C library. Following the *-sys package conventions, the libusb1-sys crate does not define higher-level abstractions over the native libusb library functions.

Dependencies

In order to use the libusb1-sys crate, you must have the libusb library installed where it can be found by pkg-config.

All systems supported by libusb are also supported by the libusb1-sys crate. It's been tested on Linux, OS X, and Windows.

Cross-Compiling

To link to a cross-compiled version of the native libusb library, it‘s necessary to set several environment variables to configure pkg-config to work with a cross-compiler’s sysroot. Autotools Mythbuster has a good explanation of supporting cross-compilation with pkg-config.

However, Rust‘s pkg-config build helper doesn’t support calling a $CHOST-prefixed pkg-config. It will always call pkg-config without a prefix. To cross-compile libusb1-sys with the pkg-config build helper, one must define the environment variables PKG_CONFIG_DIR, PKG_CONFIG_LIBDIR, and PKG_CONFIG_SYSROOT_DIR for the default pkg-config. It‘s also necessary to set PKG_CONFIG_ALLOW_CROSS to tell Rust’s pkg-config helper that it's okay to proceed with a cross-compile.

To adapt the pkg-config wrapper in the Autotools Mythbuster guide so that it works with Rust, one will end up with a script similar to the following:

#!/bin/sh

SYSROOT=/build/root

export PKG_CONFIG_DIR=
export PKG_CONFIG_LIBDIR=${SYSROOT}/usr/lib/pkgconfig:${SYSROOT}/usr/share/pkgconfig
export PKG_CONFIG_SYSROOT_DIR=${SYSROOT}
export PKG_CONFIG_ALLOW_CROSS=1

cargo build

Usage

Add libusb1-sys as a dependency in Cargo.toml:

[dependencies]
libusb1-sys = "0.6"

Import the libusb1_sys crate and use the functions as they're defined in the native libusb library. See the libusb 1.0 API documention for more usage information.

extern crate libusb1_sys as ffi;

fn main() {
  let version = unsafe { ffi::libusb_get_version() };

  println!("libusb v{}.{}.{}.{}", version.major, version.minor, version.micro, version.nano);
}

Native dependencies

libusb1-sys exports metadata so that dependent crates can find the correct libusb.h header and compile native code that depends on libusb. If a crate has a direct dependency on libusb1-sys, its build script has access to the following environment variables:

  • DEP_USB_1.0_INCLUDE contains the include path with the correct libusb.h
  • DEP_USB_1.0_VENDORED is set with a value of 1 if libusb1-sys compiled and linked to its vendored copy of libusb
  • DEP_USB_1.0_STATIC is set with a value of 1 if static linkage has been used instead of dynamic.

Finding Help

Since libusb1-sys is no more than a wrapper around the native libusb library, the best source for help is the information already available for libusb:

License

Distributed under the MIT License.

License note.

If you link native libusb library statically then you must follow GNU LGPL from libusb.