1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
/*!

For Rust-to-Rust ffi,
with a focus on creating libraries loaded at program startup,
and with load-time type-checking.

This library allows defining Rust libraries that can be loaded at runtime,
even if they were built with a different Rust version than the crate that depends on it.

These are some usecases for this library:

- Converting a Rust dependency tree from compiling statically into a single binary,
    into one binary (and potentially) many dynamic libraries,
    allowing separate re-compilation on changes.

- Creating a plugin system (without support for unloading).

# Features

Currently this library has these features:

- Features the [`sabi_trait`] attribute macro, for creating ffi-safe trait objects.

- Ffi-safe equivalent of some trait objects with [`DynTrait`].

- Provides ffi-safe alternatives/wrappers for many standard library types,
    in the [`std_types`] module.

- Provides ffi-safe wrappers for some types defined in external crates,
    in the [`external_types`] module.

- Provides the [`StableAbi`] trait for asserting that types are ffi-safe.

- The [prefix types] feature for building extensible modules and vtables,
without breaking ABI compatibility.

- Supports ffi-safe [nonexhaustive enums], wrapped in [`NonExhaustive`].

- Checking at load-time that the types in the dynamic library have the expected layout,
    allowing for semver compatible changes while checking the layout of types.

- Provides the [`StableAbi` derive] macro
    to both assert that the type is ffi compatible,
    and to get the layout of the type at load-time to check that it is still compatible.

# Examples

For **examples** of using `abi_stable` you can look at [the readme example],
or for the crates in the examples directory in the repository for this crate.
This crate also has examples in the docs for most features.

To run the example crates you'll generally have to build the `*_impl` crate,
then run the `*_user` crate (all `*_user` crates should have a help message and a readme.md).


# Minimum Rust version

This crate support Rust back to 1.61.0

You can manually enable support for Rust past 1.61.0 with the `rust_*_*` cargo features.

# Crate Features

These are default cargo features that enable optional crates :

- "channels":
    Depends on `crossbeam-channel`,
    wrapping channels from it for ffi in `abi_stable::external_types::crossbeam_channel` .

- "serde_json":
    Depends on `serde_json`,
    providing ffi-safe equivalents of
    `&serde_json::value::RawValue` and `Box<serde_json::value::RawValue>`,
    in `abi_stable::external_types::serde_json` .


To disable the default features use:
```text
[dependencies.abi_stable]
version = "<current_version>"
default-features = false
features = [  ]
```
enabling the features you need in the `features` array.

### Manually enabled

These are crate features to manually enable support for newer language features:

- "rust_1_64": Turns many functions for converting types to slices into const fns.

- "rust_latest_stable":
Enables the "rust_1_*" features for all the stable releases.

# Glossary

`interface crate`: the crate that declares the public functions, types, and traits that
are necessary to load a library at runtime.

`ìmplementation crate`: A crate that implements all the functions in a interface crate.

`user crate`: A crate that depends on an `interface crate` and
loads 1 or more `ìmplementation crate`s for it.

`module`: refers to a struct of function pointers and other static values.
The root module of a library implements the [`RootModule`] trait.
These are declared in the `interface crate`,exported in the `implementation crate`,
and loaded in the `user crate`.

# Rust-to-Rust FFI types.

Types must implement [`StableAbi`] to be safely passed through the FFI boundary,
which can be done using the [`StableAbi` derive] macro.

For how to evolve dynamically loaded libraries you can look at the [library_evolution] module.

These are the kinds of types passed through FFI:

- Value kind:<br>
    This is the default kind when deriving StableAbi.
    The layout of these types must not change in a minor versions.

- [Nonexhaustive enums] :<br>
    Enums wrapped inside [`NonExhaustive`],
    which can add variants in minor versions of the library.

- [Trait objects] :<br>
    Trait object-like types generated using the [`sabi_trait`] attribute macro,
    which erase the type of the value they wrap,implements the methods of the trait,
    and can only be unwrapped back to the original type in the dynamic library/binary
    that created it.

- Opaque kind:<br>
    Types wrapped in [`DynTrait`],
    whose layout can change in any version of the library,
    and can only be unwrapped back to the original type in the dynamic library/binary
    that created it.

- [Prefix types] :<br>
    Types only accessible through some custom pointer types,
    most commonly vtables and modules,
    which can be extended in minor versions while staying ABI compatible,
    by adding fields at the end.

# Extra documentation

- [Unsafe code guidelines] :<br>
    Describes how to write unsafe code ,relating to this library.

- [Troubleshooting] :<br>
    Some problems and their solutions.

# Macros (derive and attribute)

- [`sabi_trait`] attribute macro:<br>
    For generating ffi-safe trait objects.

- [`StableAbi` derive] :<br>
    For asserting abi-stability of a type,
    and obtaining the layout of the type at runtime.

- [Nonexhaustive enums] :<br>
    Details for how to declare nonexhaustive enums.

- [Prefix types] \(using the StableAbi derive macro):<br>
    The way that *vtables* and *modules* are implemented,
    allowing extending them in minor versions of a library.

[`std_types`]: ./std_types/index.html
[`external_types`]: ./external_types/index.html
[prefix types]: ./docs/prefix_types/index.html
[Prefix types]: ./docs/prefix_types/index.html
[nonexhaustive enums]: ./docs/sabi_nonexhaustive/index.html
[Nonexhaustive enums]: ./docs/sabi_nonexhaustive/index.html
[library_evolution]: ./docs/library_evolution/index.html
[`NonExhaustive`]: ./nonexhaustive_enum/struct.NonExhaustive.html

[the readme example]:
https://github.com/rodrimati1992/abi_stable_crates/blob/master/readme.md#readme_example

[`RootModule`]: ./library/trait.RootModule.html
[`StableAbi`]: ./abi_stability/stable_abi_trait/trait.StableAbi.html
[`sabi_trait`]: ./attr.sabi_trait.html
[Trait objects]: ./attr.sabi_trait.html
[`StableAbi` derive]: ./derive.StableAbi.html
[`DynTrait`]: ./struct.DynTrait.html
[Troubleshooting]: ./docs/troubleshooting/index.html
[Unsafe code guidelines]: ./docs/unsafe_code_guidelines/index.html

*/

// `improper_ctypes` is way too noisy of a lint,
// every single warning was a false positive.
// the true positives are caught by the StableAbi trait.
#![allow(improper_ctypes)]
#![allow(improper_ctypes_definitions)]
#![allow(non_camel_case_types)]
#![deny(unused_must_use)]
#![warn(rust_2018_idioms)]
#![allow(clippy::needless_doctest_main)]
#![allow(clippy::bool_assert_comparison)]
#![allow(clippy::zero_prefixed_literal)]
#![allow(clippy::type_complexity)]
#![allow(clippy::ptr_offset_with_cast)]
#![allow(clippy::assertions_on_constants)]
#![deny(missing_docs)]
#![deny(clippy::missing_safety_doc)]
// #![deny(clippy::missing_const_for_fn)]
#![deny(unsafe_op_in_unsafe_fn)]
#![cfg_attr(feature = "docsrs", feature(doc_cfg))]

#[macro_use]
extern crate serde_derive;

#[macro_use(StableAbi)]
extern crate abi_stable_derive;

extern crate self as abi_stable;

include! {"./proc_macro_reexports/get_static_equivalent.rs"}
include! {"./proc_macro_reexports/export_root_module.rs"}
include! {"./proc_macro_reexports/sabi_extern_fn.rs"}
include! {"./proc_macro_reexports/sabi_trait_attribute.rs"}
include! {"./proc_macro_reexports/stable_abi_derive.rs"}

#[doc(no_inline)]
pub use abi_stable::sabi_types::{RMut, RRef};

use abi_stable_derive::impl_InterfaceType;

#[doc(hidden)]
pub use abi_stable_derive::get_root_module_static;

#[macro_use]
mod impls;

#[macro_use]
mod internal_macros;

#[macro_use]
mod macros;

#[cfg(test)]
#[macro_use]
mod test_macros;

#[allow(missing_docs)]
#[cfg(feature = "testing")]
#[macro_use]
pub mod test_utils;

#[cfg(test)]
mod misc_tests;

#[macro_use]
pub mod utils;

#[macro_use]
pub mod const_utils;

#[macro_use]
pub mod traits;

pub mod for_examples;

#[macro_use]
pub mod abi_stability;
#[macro_use]
pub mod erased_types;
pub mod external_types;
#[macro_use]
pub mod library;
pub mod inline_storage;
pub mod marker_type;
mod multikey_map;
pub mod nonexhaustive_enum;
pub mod pointer_trait;
pub mod prefix_type;
pub mod type_layout;

#[doc(hidden)]
pub mod derive_macro_reexports;

// `pmr` is what I call "private" reexport for macros in newer crates.
#[doc(hidden)]
pub use self::derive_macro_reexports as pmr;

pub mod sabi_types;
pub mod std_types;

pub mod reflection;
pub mod type_level;

pub mod docs;

pub mod sabi_trait;

/// The header used to identify the version number of abi_stable
/// that a dynamic libraries uses.
pub static LIB_HEADER: library::AbiHeader = library::AbiHeader::VALUE;

/// Miscelaneous items re-exported from core_extensions.
pub mod reexports {
    pub use core_extensions::{
        type_level_bool::{False, True},
        utils::transmute_ignore_size,
        SelfOps,
    };
}

#[doc(hidden)]
pub const ABI_STABLE_VERSION: sabi_types::VersionStrings = package_version_strings!();

/*
I am using this static as the `identity` of this dynamic library/executable,
this assumes that private static variables don't get merged between
Rust dynamic libraries that have a different global allocator.

If the address of this is the same among dynamic libraries that have *different*
allocators,please create an issue for this.
*/
use std::sync::atomic::AtomicUsize;
static EXECUTABLE_IDENTITY: AtomicUsize = AtomicUsize::new(1);

#[doc(inline)]
pub use crate::{
    abi_stability::StableAbi,
    erased_types::{dyn_trait::DynTrait, InterfaceType},
};

#[doc(hidden)]
pub mod globals {
    use crate::{
        abi_stability::abi_checking::check_layout_compatibility_for_ffi,
        sabi_types::LateStaticRef,
        std_types::{RBoxError, RResult},
        type_layout::TypeLayout,
        utils::leak_value,
    };

    #[repr(C)]
    #[derive(StableAbi)]
    // #[sabi(debug_print)]
    pub struct Globals {
        pub layout_checking:
            extern "C" fn(&'static TypeLayout, &'static TypeLayout) -> RResult<(), RBoxError>,
    }

    impl Globals {
        pub fn new() -> &'static Self {
            leak_value(Globals {
                layout_checking: check_layout_compatibility_for_ffi,
            })
        }
    }

    pub(crate) static GLOBALS: LateStaticRef<&Globals> = LateStaticRef::new();

    #[inline(never)]
    pub fn initialized_globals() -> &'static Globals {
        GLOBALS.init(Globals::new)
    }

    #[inline(never)]
    pub extern "C" fn initialize_globals_with(globs: &'static Globals) {
        GLOBALS.init(|| globs);
    }
}

#[cfg(all(test, not(feature = "testing")))]
compile_error! { "tests must be run with the \"testing\" feature" }

#[cfg(miri)]
extern "Rust" {
    /// Miri-provided extern function to mark the block `ptr` points to as a "root"
    /// for some static memory. This memory and everything reachable by it is not
    /// considered leaking even if it still exists when the program terminates.
    ///
    /// `ptr` has to point to the beginning of an allocated block.
    fn miri_static_root(ptr: *const u8);
}

// Removed readme testing, now the readme code is tested with actual crates.
// #[cfg(doctest)]
// #[doc = include_str!("../../readme.md")]
// pub struct ReadmeTest;