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
/*!
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/)
[`export_root_module`]: crate::export_root_module
*/