abi_stable/proc_macro_reexports/
export_root_module.rs

Help
1/**
2This attribute is used for functions which export a module in an `implementation crate`.
3
4This is applied to functions like this:
5
6```rust
7
8use abi_stable::prefix_type::PrefixTypeTrait;
9
10#[abi_stable::export_root_module]
11pub fn get_hello_world_mod() -> TextOperationsMod_Ref {
12    TextOperationsMod { reverse_string }.leak_into_prefix()
13}
14
15# #[repr(C)]
16# #[derive(abi_stable::StableAbi)]
17# #[sabi(kind(Prefix(prefix_ref= TextOperationsMod_Ref)))]
18# #[sabi(missing_field(panic))]
19# pub struct TextOperationsMod {
20#     #[sabi(last_prefix_field)]
21#     pub reverse_string: extern "C" fn(),
22# }
23# 
24# extern "C" fn reverse_string() {}
25
26# impl abi_stable::library::RootModule for TextOperationsMod_Ref {
27#     abi_stable::declare_root_module_statics!{TextOperationsMod_Ref}
28#     const BASE_NAME: &'static str = "stuff";
29#     const NAME: &'static str = "stuff";
30#     const VERSION_STRINGS: abi_stable::sabi_types::VersionStrings =
31#           abi_stable::package_version_strings!();
32# }
33
34# fn main(){}
35
36
37```
38
39# Return Type
40
41The return type of the annotated function can be one of:
42
43- Any type that implements `abi_stable::library::RootModule`
44
45- `Result<M, RBoxError>`, where `M` is any type that implements 
46`abi_stable::library::RootModule`
47
48- `RResult<M, RBoxError>`, where `M` is any type that implements 
49`abi_stable::library::RootModule`
50
51All those types are supported through the [`IntoRootModuleResult`] trait,
52which you can implement if you want to return some other type.
53
54# Generated code
55
56Exporting the root module creates a 
57`static THE_NAME_USED_FOR_ALL_ROOT_MODULES: `[`LibHeader`]` = ... ;` 
58with these things:
59
60- The version of `abi_stable` used.
61
62- A `#[no_mangle]` function that wraps the annotated root-module constructor function,
63converting the return value to [`RootModuleResult`](./library/type.RootModuleResult.html).
64
65- The type layout of the root module,
66for checking that the types are compatible with whatever loads that library.
67
68- The version number of the library.
69
70- A [`LateStaticRef`] of the root module.
71
72
73The name used for generated static is the value of 
74[`abi_stable::library::ROOT_MODULE_LOADER_NAME`](./library/constant.ROOT_MODULE_LOADER_NAME.html).
75
76# Remove type layout constant
77
78One can avoid generating the type layout constant for the exported root module by using the
79`#[unsafe_no_layout_constant]` attribute,
80with the downside that if the layout changes(in an incompatible way)
81it could be Undefined Behavior.
82
83This attribute is useful if one wants to minimize the size of the dynamic library when 
84doing a public release.
85
86This attribute should not be used unconditionally,
87it should be disabled in Continuous Integration so that the 
88binary compatibility of a dynamic library is checked at some point before releasing it.
89
90# More examples
91
92For a more detailed example look in the README in the repository for this crate.
93
94
95
96[`IntoRootModuleResult`]: ./library/trait.IntoRootModuleResult.html
97[`LateStaticRef`]: ./sabi_types/struct.LateStaticRef.html
98[`LibHeader`]: ./library/struct.LibHeader.html
99
100*/
101#[doc(inline)]
102pub use abi_stable_derive::export_root_module;
abi_stable/proc_macro_reexports/export_root_module.rs

abi_stable/proc_macro_reexports/
export_root_module.rs
