Derive Macro KnownLayout

#[derive(KnownLayout)]

Implements KnownLayout.

This derive analyzes various aspects of a type’s layout that are needed for some of zerocopy’s APIs. It can be applied to structs, enums, and unions; e.g.:

#[derive(KnownLayout)]
struct MyStruct {
    ...
}

#[derive(KnownLayout)]
enum MyEnum {
    ...
}

#[derive(KnownLayout)]
union MyUnion {
    ...
}

Limitations

This derive cannot currently be applied to unsized structs without an explicit repr attribute.

Some invocations of this derive run afoul of a known bug in Rust’s type privacy checker. For example, this code:

use zerocopy::*;

#[derive(KnownLayout)]
#[repr(C)]
pub struct PublicType {
    leading: Foo,
    trailing: Bar,
}

#[derive(KnownLayout)]
struct Foo;

#[derive(KnownLayout)]
struct Bar;

…results in a compilation error:

error[E0446]: private type `Bar` in public interface
 --> examples/bug.rs:3:10
   |
3  | #[derive(KnownLayout)]
   |          ^^^^^^^^^^^ can't leak private type
...
14 | struct Bar;
   | ---------- `Bar` declared as private
   |
   = note: this error originates in the derive macro `KnownLayout` (in Nightly builds, run with -Z macro-backtrace for more info)

This issue arises when #[derive(KnownLayout)] is applied to repr(C) structs whose trailing field type is less public than the enclosing struct.

To work around this, mark the trailing field type pub and annotate it with #[doc(hidden)]; e.g.:

use zerocopy::*;

#[derive(KnownLayout)]
#[repr(C)]
pub struct PublicType {
    leading: Foo,
    trailing: Bar,
}

#[derive(KnownLayout)]
struct Foo;

#[doc(hidden)]
#[derive(KnownLayout)]
pub struct Bar; // <- `Bar` is now also `pub`