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

/*!

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`/`SharedStableAbi`,
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 way 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 change of layout is why crossbeam channels are implemented as
ffi-safe trait objects.

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/)


*/