/*!
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.
// #![deny(clippy::missing_const_for_fn)]
extern crate serde_derive;
extern crate abi_stable_derive;
extern crate self as abi_stable;
include!
include!
include!
include!
include!
pub use ;
use impl_InterfaceType;
pub use get_root_module_static;
// `pmr` is what I call "private" reexport for macros in newer crates.
pub use derive_macro_reexports as pmr;
/// The header used to identify the version number of abi_stable
/// that a dynamic libraries uses.
pub static LIB_HEADER: AbiHeader = VALUE;
/// Miscelaneous items re-exported from core_extensions.
pub const ABI_STABLE_VERSION: 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 AtomicUsize;
static EXECUTABLE_IDENTITY: AtomicUsize = new;
pub use crate::;
compile_error!
extern "Rust"
;