abi_stable/docs/
library_evolution.rs

Help
1/*!
2
3This document describes what changes are valid/invalid for a library using `abi_stable`,
4
5Note that all of these only applies to types that implement `StableAbi`,
6and are checked when loading the dynamic libraries using
7the functions in `abi_stable::library::RootModule`.
8Those dynamic libraries use the [`export_root_module`] attribute on some function
9that export the root module
10([a struct of function pointers and other nested modules](../prefix_types/index.html)).
11
12
13# Semver in/compatible changes
14
15These are the changes to pre-existing data structures that are
16allowed/disallowed in semver compatible versions
17(0.y.z < 0.(y+1).0 , x.y.z < (x+1).0.0).
18
19It is never allowed to remove fields or variants in newer versions of a library.
20
21Types cannot be renamed.
22
23A type cannot be replaced with a `#[repr(transparent)]` types wrappig it.
24
25If you rename a field,remember to use the `#[sabi(rename=the_old_name)]` attribute,
26field names are part of the ABI of a type.
27
28
29### Structs
30
31It's only valid to add fields to structs if they are
32[prefix types (vtables or modules)](../prefix_types/index.html),
33and only after the last field.
34
35
36### Exhaustive Enums
37
38It is not possible to add variants or fields to exhaustive enums.
39
40Exhaustive enums being ones that are declared like this:
41```rust
42use abi_stable::{std_types::RString, StableAbi};
43
44#[repr(u8)]
45#[derive(StableAbi)]
46enum Exhaustive {
47    A,
48    B(RString),
49    C,
50    D { hello: u32, world: i64 },
51}
52
53# fn main(){}
54
55```
56
57### Non-exhaustive enums
58
59It's possible to add variants with either:
60
61- Field-less enums implemented as a struct wrapping an integer,
62    with associated constants as the variants.
63
64- [Enums which use the
65    `#[sabi(kind(WithNonExhaustive())]` attribute
66    ](../sabi_nonexhaustive/index.html),
67    wrapped inside `NonExhaustive<>`.
68
69Neither one allow enums to change their size or alignment.
70
71<br>
72
73Example field-less enum implemented as a struct wrapping an integer:
74
75```
76
77use abi_stable::StableAbi;
78
79#[repr(transparent)]
80#[derive(StableAbi, Eq, PartialEq)]
81pub struct Direction(u8);
82
83impl Direction {
84    pub const LEFT: Self = Direction(0);
85    pub const RIGHT: Self = Direction(1);
86    pub const UP: Self = Direction(2);
87    pub const DOWN: Self = Direction(3);
88}
89
90# fn main(){}
91
92
93```
94
95
96### Unions
97
98It's not possible to add fields to unions,this is not currently possible
99because the original author of`abi_stable` didn't see any need for it
100(if you need it create an issue for it).
101
102# Semver in/compatible additions
103
104It is always valid to declare new types in a library.
105
106### Wrapping non-StableAbi types
107
108You must be very careful when wrapping types which don't implement StableAbi
109from external libraries,
110since they might not guarantee any of these properties:
111
112- Their size,alignment,representation attribute,layout in general.
113
114- Their dependence on global state,
115    which could cause undefined behavior if passed between dynamic libraries,
116    or just be unpredictable.
117
118The potential dependence on global state is why `abi_stable` uses dynamic dispatch
119for all the types it wraps in `abi_stable::external_types`
120
121# abi_stable specific
122
123If you add StableAbi types to abi_stable,make sure to add them to the list of types in
124`version_compatibility_interface::ManyTypes`
125(the crate is in testing/version_compatibility/interface/)
126
127
128
129[`export_root_module`]: crate::export_root_module
130*/
abi_stable/docs/library_evolution.rs

abi_stable/docs/
library_evolution.rs
