dlib is a small crate providing macros to make easy the use of external system libraries
that can or cannot be optionally loaded at runtime, depending on whether the dlopen cargo
feature is enabled.
dlib defines the external_library! macro, which can be invoked with way:
rust
external_library!(Foo, "foo",
statics:
me: c_int,
you: c_float,
functions:
fn foo() -> c_int,
fn bar(c_int, c_float) -> (),
fn baz(*const c_int) -> c_int,
varargs:
fn blah(c_int, c_int ...) -> *const c_void,
fn bleh(c_int ...) -> (),
);
As you can see, it is required to separate static values from functions and from function
having variadic arguments. Each of these 3 categories is optional, but the ones used must appear
in this order. Return types of the functions must all be explicit (hence -> () for void functions).
If the feature dlopen is absent, this macro will expand to an extern block defining each of the
items, using the second argument of the macro as a link name:
```rust
extern "C" { pub static me: cint; pub static you: cfloat; pub fn foo() -> cint; pub fn bar(: cint, _: cfloat) -> (); pub fn baz(: *const cint) -> cint; pub fn blah(: cint, _: cint, ...) -> *const cvoid; pub fn bleh(: c_int, ...) -> (); }
```
If the feature dlopen is present, it will expand to a struct named by the first argument of the macro,
with one field for each of the symbols defined, and a method open, which tries to load the library
from the name or path given as argument
```rust pub struct Foo { pub me: &'static cint, pub you: &'static cfloat, pub foo: unsafe extern "C" fn() -> cint, pub bar: unsafe extern "C" fn(cint, cfloat) -> (), pub baz: unsafe extern "C" fn(*const cint) -> cint, pub blah: unsafe extern "C" fn(cint, cint, ...) -> *const cvoid, pub bleh: unsafe extern "C" fn(c_int, ...) -> (), }
impl Foo {
pub fn open(name: &str) -> Result
This method returns Ok(..) if the loading was successful. It contains an instance of the defined struct
with all of its fields pointing to the appropriate symbol.
If the library specified by name could not be found, it returns Err(DlError::NotFount).
It will also fail on the first missing symbol, with Err(DlError::MissingSymbol(symb)) where symb is a &str
containing the missing symbol name.
If you want your crate to remain generic over the dlopen cargo feature, simply add this to your Cargo.toml
``` [dependencies] dlib = "0.2"
[features] dlopen = ["dlib/dlopen"] ```
And the library also provides helper macros to dispatch the access to foreign symbols:
rust
ffi_dispatch!(Foo, function, arg1, arg2);
ffi_dispatch_static!(Foo, static);
These will expand to the appropriate value or function call depending on the presence of the dlopen feature.
You must still ensure that the functions/statics or the wrapper struct Foo are in scope. A simple pattern would be
for example to use the lazy_static! crate to do the initialization and store the wrapper struct in a static, that you then
just need to import everywhere needed. Then, it can become as simple as putting this on top of all modules using the FFI:
```rust
use ffi::FOO_STATIC;
use ffi::*; ```