merge #2: bindgen, Windows, bump to 1.4, Rust 2018

- support bindgen for on-the-fly bindings generation,
- stop using enums to avoid UB on possible unknown values,
- bump libftdi1 version to 1.4,
- add Windows support

Cargo.toml

@@ -11,11 +11,22 @@ edition = "2018"
 
 build = "build.rs"
 
+[features]
+default = ["bindgen"]
+
 [dependencies]
+cfg-if = "0.1.10"
 libc = "0.2"
 
-[target.'cfg(not(windows))'.build-dependencies]
+[build-dependencies]
+cfg-if = "0.1.10"
+
+[target.'cfg(not(all(windows, target_env="msvc")))'.build-dependencies]
 pkg-config = "0.3"
 
-[target.'cfg(windows)'.build-dependencies]
-vcpkg = "0.2"
+[target.'cfg(all(windows, target_env="msvc"))'.build-dependencies]
+vcpkg = "0.2"
+
+[build-dependencies.bindgen]
+version = "0.53.2"
+optional = true

README.md

@@ -0,0 +1,42 @@
+# `libftdi1-sys`
+`libftdi1-sys` is a crate providing Rust bindings to the C library
+[`libftdi1`](https://www.intra2net.com/en/developer/libftdi/index.php).
+
+## Prerequisites
+By default, the libftdi1 bindings are generated at compile-time, per bindgen's
+[recommended usage](https://rust-lang.github.io/rust-bindgen/library-usage.html).
+
+* `libclang` must be installed and visible on your path. If you are using a
+  `gcc`-toolchain and don't want to install the entirity of LLVM just for
+  `libclang`, you can use the following procedure (using a Debian-based
+  ARM system as an example):
+
+  ```
+  sudo apt-get install libclang-dev
+  export LIBCLANG_PATH=/usr/lib/llvm-7/lib
+  export C_INCLUDE_PATH=/usr/lib/gcc/arm-linux-gnueabihf/8/include
+  cargo build
+  ```
+
+* `libftdi` version 1.4 (the most recent version as of 2017) is required.
+
+### MSRV
+The Minimum Supported Rust Version (MSRV) is stable `1.34` when default
+features are enabled (i.e. generating bindings at compile-time). If support for
+older Rust versions is required, the pre-generated bindings
+(down to `1.31`, Rust 2018) must be used instead.
+
+## Pre-Generated Bindings
+`libftdi1-sys` provides some bindings generated ahead-of-time from `bindgen`
+as a fallback for users lacking `libclang`, requiring Rust 2018 support, or
+otherwise. To use these pre-generated bindings, add the following to your
+`Cargo.toml`:
+
+```
+[dependencies.libftdi1-sys]
+default-features="false"
+```
+
+## Features
+* `bindgen`: Generate bindings to `libftdi` at compile time.
+  Enabled by default.

build.rs

@@ -1,9 +1,42 @@
-#[cfg(not(windows))]
-fn main() {
-    pkg_config::find_library("libftdi1").unwrap();
+cfg_if::cfg_if! {
+    if #[cfg(feature = "bindgen")] {
+        use bindgen;
+
+        use std::env;
+        use std::path::PathBuf;
+    }
 }
 
-#[cfg(windows)]
 fn main() {
-    vcpkg::find_package("libftdi1").unwrap();
+    cfg_if::cfg_if! {
+        if #[cfg(all(windows, target_env="msvc"))] {
+            vcpkg::find_package("libftdi1").unwrap();
+        } else {
+            pkg_config::Config::new().atleast_version("1.4").probe("libftdi1").unwrap();
+        }
+    }
+
+    cfg_if::cfg_if! {
+        if #[cfg(feature = "bindgen")] {
+            let bindings = bindgen::Builder::default()
+                .header("wrapper.h")
+                .default_enum_style(bindgen::EnumVariation::NewType{ is_bitfield : false })
+                .rustfmt_bindings(true)
+                .whitelist_function("ftdi_.*")
+                .whitelist_type("ftdi_.*")
+                .whitelist_type("libusb_.*")
+                .blacklist_type("timeval")
+                .blacklist_type("__.*")
+                .raw_line("pub type timeval = libc::timeval;")
+                .generate()
+                .expect("Unable to generate bindings");
+
+            let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
+            bindings
+                .write_to_file(out_path.join("bindings.rs"))
+                .expect("Couldn't write bindings!");
+        } else {
+            // Anything not depending on bindgen feature goes here.
+        }
+    }
 }