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
/*!
This document describes what changes are valid/invalid for a library using `abi_stable`,
Note that all of these only applies to types that implement `StableAbi`,
and are checked when loading the dynamic libraries using
the functions in `abi_stable::library::RootModule`.
Those dynamic libraries use the `export_root_module` attribute on some function
that export the root module
([a struct of function pointers and other nested modules](../prefix_types/index.html)).
# Semver in/compatible changes
These are the changes to pre-existing data structures that are
allowed/disallowed in semver compatible versions
(0.y.z < 0.(y+1).0 , x.y.z < (x+1).0.0).
It is never allowed to remove fields or variants in newer versions of a library.
Types cannot be renamed.
A type cannot be replaced with a `#[repr(transparent)]` types wrappig it.
If you rename a field,remember to use the `#[sabi(rename="the_old_name")]` attribute,
field names are part of the ABI of a type.
### Structs
It's only valid to add fields to structs if they are
[prefix types (vtables or modules)](../prefix_types/index.html),
and only after the last field.
### Exhaustive Enums
It is not possible to add variants or fields to exhaustive enums.
Exhaustive enums being ones that are declared like this:
```rust
use abi_stable::{std_types::RString, StableAbi};
#[repr(u8)]
#[derive(StableAbi)]
enum Exhaustive {
A,
B(RString),
C,
D { hello: u32, world: i64 },
}
# fn main(){}
```
### Non-exhaustive enums
It's possible to add variants with either:
- Field-less enums implemented as a struct wrapping an integer,
with associated constants as the variants.
- [Enums which use the
`#[sabi(kind(WithNonExhaustive())]` attribute
](../sabi_nonexhaustive/index.html),
wrapped inside `NonExhaustive<>`.
Neither one allow enums to change their size or alignment.
<br>
Example field-less enum implemented as a struct wrapping an integer:
```
use abi_stable::StableAbi;
#[repr(transparent)]
#[derive(StableAbi, Eq, PartialEq)]
pub struct Direction(u8);
impl Direction {
pub const LEFT: Self = Direction(0);
pub const RIGHT: Self = Direction(1);
pub const UP: Self = Direction(2);
pub const DOWN: Self = Direction(3);
}
# fn main(){}
```
### Unions
It's not possible to add fields to unions,this is not currently possible
because the original author of`abi_stable` didn't see any need for it
(if you need it create an issue for it).
# Semver in/compatible additions
It is always valid to declare new types in a library.
### Wrapping non-StableAbi types
You must be very careful when wrapping types which don't implement StableAbi
from external libraries,
since they might not guarantee any of these properties:
- Their size,alignment,representation attribute,layout in general.
- Their dependence on global state,
which could cause undefined behavior if passed between dynamic libraries,
or just be unpredictable.
The potential dependence on global state is why `abi_stable` uses dynamic dispatch
for all the types it wraps in `abi_stable::external_types`
# abi_stable specific
If you add StableAbi types to abi_stable,make sure to add them to the list of types in
`version_compatibility_interface::ManyTypes`
(the crate is in testing/version_compatibility/interface/)
*/