README.md
1[](https://crates.io/crates/dlib)
2[](https://docs.rs/dlib)
3
4# dlib
5
6dlib is a small crate providing macros to make easy the use of external system libraries that
7can or cannot be optionally loaded at runtime, depending on whether a certain feature is enabled.
8
9### Usage
10
11dlib defines the `external_library!` macro, which can be invoked in this way:
12
13```rust
14external_library!(feature="dlopen-foo", Foo, "foo",
15 statics:
16 me: c_int,
17 you: c_float,
18 functions:
19 fn foo() -> c_int,
20 fn bar(c_int, c_float) -> (),
21 fn baz(*const c_int) -> c_int,
22 varargs:
23 fn blah(c_int, c_int ...) -> *const c_void,
24 fn bleh(c_int ...) -> (),
25);
26```
27
28As you can see, it is required to separate static values from functions and from function
29having variadic arguments. Each of these 3 categories is optional, but the ones used must appear
30in this order. Return types of the functions must all be explicit (hence `-> ()` for void functions).
31
32If the feature named by the `feature` argument (in this example, `dlopen-foo`) is absent on your crate,
33this macro will expand to an extern block defining each of the items, using the third argument
34of the macro as a link name:
35
36```rust
37#[link(name = "foo")]
38extern "C" {
39 pub static me: c_int;
40 pub static you: c_float;
41 pub fn foo() -> c_int;
42 pub fn bar(_: c_int, _: c_float) -> ();
43 pub fn baz(_: *const c_int) -> c_int;
44 pub fn blah(_: c_int, _: c_int, ...) -> *const c_void;
45 pub fn bleh(_: c_int, ...) -> ();
46}
47
48```
49
50If the feature named by the `feature` argument is present on your crate, it will expand to a
51`struct` named by the second argument of the macro, with one field for each of the symbols defined;
52and a method `open`, which tries to load the library from the name or path given as an argument.
53
54```rust
55pub struct Foo {
56 pub me: &'static c_int,
57 pub you: &'static c_float,
58 pub foo: unsafe extern "C" fn() -> c_int,
59 pub bar: unsafe extern "C" fn(c_int, c_float) -> (),
60 pub baz: unsafe extern "C" fn(*const c_int) -> c_int,
61 pub blah: unsafe extern "C" fn(c_int, c_int, ...) -> *const c_void,
62 pub bleh: unsafe extern "C" fn(c_int, ...) -> (),
63}
64
65
66impl Foo {
67 pub unsafe fn open(name: &str) -> Result<Foo, DlError> { /* ... */ }
68}
69```
70
71This method returns `Ok(..)` if the loading was successful. It contains an instance of the defined struct
72with all of its fields pointing to the appropriate symbol.
73
74If the library specified by `name` could not be openened, it returns `Err(DlError::CantOpen(e))`, with
75`e` the error reported by `libloading` (see [LibLoadingError]);
76
77It will also fail on the first missing symbol, with `Err(DlError::MissingSymbol(symb))` where `symb`
78is a `&str` containing the missing symbol name.
79
80Note that this method is unsafe, as loading (and unloading on drop) an external C library can run arbitrary
81code. As such, you need to ensure that the specific library you want to load is safe to load in the context
82you want to load it.
83
84### Remaining generic in your crate
85
86If you want your crate to remain generic over dlopen vs. linking, simply add a feature to your `Cargo.toml`:
87
88```toml
89[dependencies]
90dlib = "0.5"
91
92[features]
93dlopen-foo = []
94```
95
96Then give the name of that feature as the `feature` argument to dlib's macros:
97
98```rust
99external_library!(feature="dlopen-foo", Foo, "foo",
100 functions:
101 fn foo() -> c_int,
102);
103```
104
105`dlib` provides helper macros to dispatch the access to foreign symbols:
106
107```rust
108ffi_dispatch!(feature="dlopen-foo", Foo, function, arg1, arg2);
109ffi_dispatch_static!(feature="dlopen-foo", Foo, my_static_var);
110```
111
112These will expand to the appropriate value or function call depending on the presence or absence of the
113`dlopen-foo` feature on your crate.
114
115You must still ensure that the functions/statics or the wrapper struct `Foo` are in scope. For example,
116you could use the [`lazy_static`](https://crates.io/crates/lazy_static) crate to do the initialization,
117and store the wrapper struct in a static variable that you import wherever needed:
118
119```rust
120#[cfg(feature = "dlopen-foo")]
121lazy_static::lazy_static! {
122 pub static ref FOO_STATIC: Foo =
123 Foo::open("libfoo.so").ok().expect("could not find libfoo");
124}
125```
126
127Then, it can become as simple as putting this on top of all modules using the FFI:
128
129```rust
130#[cfg(feature = "dlopen-foo")]
131use ffi::FOO_STATIC;
132#[cfg(not(feature = "dlopen-foo"))]
133use ffi::*;
134```
135
136License: MIT
137
){kind=link}