3.6 KiB
dlib, making native libraries optional
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.
Usage
dlib defines the external_library!
macro, which can be invoked with way:
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:
#[link(name = "foo")]
extern "C" {
pub static me: c_int;
pub static you: c_float;
pub fn foo() -> c_int;
pub fn bar(_: c_int, _: c_float) -> ();
pub fn baz(_: *const c_int) -> c_int;
pub fn blah(_: c_int, _: c_int, ...) -> *const c_void;
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
pub struct Foo {
pub me: &'static c_int,
pub you: &'static c_float,
pub foo: unsafe extern "C" fn() -> c_int,
pub bar: unsafe extern "C" fn(c_int, c_float) -> (),
pub baz: unsafe extern "C" fn(*const c_int) -> c_int,
pub blah: unsafe extern "C" fn(c_int, c_int, ...) -> *const c_void,
pub bleh: unsafe extern "C" fn(c_int, ...) -> (),
}
impl Foo {
pub fn open(name: &str) -> Result<Foo, DlError> { /* ... */ }
}
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.
Remaining generic in your crate
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:
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:
#[cfg(features = "dlopen")]
use ffi::FOO_STATIC;
#[cfg(not(features = "dlopen"))]
use ffi::*;