11 releases
Uses old Rust 2015
0.5.2 | Jun 5, 2023 |
---|---|
0.5.0 | Feb 25, 2021 |
0.4.2 | May 28, 2020 |
0.4.1 | Mar 13, 2018 |
0.2.0 | Nov 9, 2015 |
#77 in Rust patterns
575,066 downloads per month
Used in 1,955 crates
(8 directly)
21KB
190 lines
dlib
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 a certain feature is enabled.
Usage
dlib defines the external_library!
macro, which can be invoked in this way:
external_library!(feature="dlopen-foo", 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 named by the feature
argument (in this example, dlopen-foo
) is absent on your crate,
this macro will expand to an extern block defining each of the items, using the third 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 named by the feature
argument is present on your crate, it will expand to a
struct
named by the second 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 an 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 unsafe 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 openened, it returns Err(DlError::CantOpen(e))
, with
e
the error reported by libloading
(see [LibLoadingError]);
It will also fail on the first missing symbol, with Err(DlError::MissingSymbol(symb))
where symb
is a &str
containing the missing symbol name.
Note that this method is unsafe, as loading (and unloading on drop) an external C library can run arbitrary code. As such, you need to ensure that the specific library you want to load is safe to load in the context you want to load it.
Remaining generic in your crate
If you want your crate to remain generic over dlopen vs. linking, simply add a feature to your Cargo.toml
:
[dependencies]
dlib = "0.5"
[features]
dlopen-foo = []
Then give the name of that feature as the feature
argument to dlib's macros:
external_library!(feature="dlopen-foo", Foo, "foo",
functions:
fn foo() -> c_int,
);
dlib
provides helper macros to dispatch the access to foreign symbols:
ffi_dispatch!(feature="dlopen-foo", Foo, function, arg1, arg2);
ffi_dispatch_static!(feature="dlopen-foo", Foo, my_static_var);
These will expand to the appropriate value or function call depending on the presence or absence of the
dlopen-foo
feature on your crate.
You must still ensure that the functions/statics or the wrapper struct Foo
are in scope. For example,
you could use the lazy_static
crate to do the initialization,
and store the wrapper struct in a static variable that you import wherever needed:
#[cfg(feature = "dlopen-foo")]
lazy_static::lazy_static! {
pub static ref FOO_STATIC: Foo =
Foo::open("libfoo.so").ok().expect("could not find libfoo");
}
Then, it can become as simple as putting this on top of all modules using the FFI:
#[cfg(feature = "dlopen-foo")]
use ffi::FOO_STATIC;
#[cfg(not(feature = "dlopen-foo"))]
use ffi::*;
License: MIT
Dependencies
~0–4.5MB