Add support for transparent enum

docs.md

@@ -133,10 +133,12 @@ You can learn about all of the different repr attributes [by reading Rust's refe
 
 * `#[repr(C)]`: give this struct/union/enum the same layout and ABI C would
 * `#[repr(u8, u16, ... etc)]`: give this enum the same layout and ABI as the given integer type
-* `#[repr(transparent)]`: give this single-field struct the same ABI as its field (useful for newtyping integers but keeping the integer ABI)
+* `#[repr(transparent)]`: give this single-field struct or enum the same ABI as its field (useful for newtyping integers but keeping the integer ABI)
 
 cbindgen supports the `#[repr(align(N))]` and `#[repr(packed)]` attributes, but currently does not support `#[repr(packed(N))]`.
 
+cbindgen supports using `repr(transparent)` on single-field structs and single-variant enums with fields. Transparent structs and enums are exported as typedefs that alias the underlying single field's type.
+
 cbindgen also supports using `repr(C)`/`repr(u8)` on non-C-like enums (enums with fields). This gives a C-compatible tagged union layout, as [defined by this RFC 2195][really-tagged-unions]. `repr(C)` will give a simpler layout that is perhaps more intuitive, while `repr(u8)` will produce a more compact layout.
 
 If you ensure everything has a guaranteed repr, then cbindgen will generate definitions for:
@@ -407,9 +409,17 @@ The rest are just local overrides for the same options found in the cbindgen.tom
 
 ### Enum Annotations
 
-* enum-trailing-values=\[variant1, variant2, ...\] -- add the following fieldless enum variants to the end of the enum's definition. These variant names *will* have the enum's renaming rules applied.
+* enum-trailing-values=\[variant1, variant2, ...\] -- add the following fieldless enum variants to
+ the end of the enum's definition. These variant names *will* have the enum's renaming rules
+ applied.
+
+ WARNING: if any of these values are ever passed into Rust, behaviour will be Undefined. Rust does
+ not know about them, and will assume they cannot happen.
 
-WARNING: if any of these values are ever passed into Rust, behaviour will be Undefined. Rust does not know about them, and will assume they cannot happen.
+* transparent-typedef -- when emitting the typedef for a transparent enum, mark it as
+ transparent. All references to the enum will be replaced with the type of its underlying NZST
+ variant field, effectively making the enum invisible on the FFI side. For exmaples of how this
+ works, see [Struct Annotations](#struct-annotations).
 
 The rest are just local overrides for the same options found in the cbindgen.toml:
 

src/bindgen/ir/enumeration.rs

@@ -12,7 +12,7 @@ use crate::bindgen::dependencies::Dependencies;
 use crate::bindgen::ir::{
  AnnotationSet, AnnotationValue, Cfg, ConditionWrite, DeprecatedNoteKind, Documentation, Field,
  GenericArgument, GenericParams, GenericPath, Item, ItemContainer, Literal, Path, Repr,
- ReprStyle, Struct, ToCondition, TransparentTypeEraser, Type,
+ ReprStyle, Struct, ToCondition, TransparentTypeEraser, Type, Typedef,
 };
 use crate::bindgen::language_backend::LanguageBackend;
 use crate::bindgen::library::Library;
@@ -308,7 +308,12 @@ impl Enum {
 
  /// Enum with data turns into a union of structs with each struct having its own tag field.
  pub(crate) fn inline_tag_field(repr: &Repr) -> bool {
- repr.style != ReprStyle::C
+ // NOTE: repr(C) requires an out of line tag field, and repr(transparent) doesn't use tags.
+ repr.style == ReprStyle::Rust
+ }
+
+ pub fn is_transparent(&self) -> bool {
+ self.repr.style == ReprStyle::Transparent
  }
 
  pub fn add_monomorphs(&self, library: &Library, out: &mut Monomorphs) {
@@ -345,7 +350,7 @@ impl Enum {
  ) -> Result<Enum, String> {
  let repr = Repr::load(&item.attrs)?;
  if repr.style == ReprStyle::Rust && repr.ty.is_none() {
- return Err("Enum is not marked with a valid #[repr(prim)] or #[repr(C)].".to_owned());
+ return Err("Enum is not marked with a valid #[repr(prim)] or #[repr(C)] or #[repr(transparent)].".to_owned());
  }
  // TODO: Implement translation of aligned enums.
  if repr.align.is_some() {
@@ -418,13 +423,35 @@ impl Enum {
  pub fn new(
  path: Path,
  generic_params: GenericParams,
- repr: Repr,
+ mut repr: Repr,
  variants: Vec<EnumVariant>,
  tag: Option<String>,
  cfg: Option<Cfg>,
  annotations: AnnotationSet,
  documentation: Documentation,
  ) -> Self {
+ // WARNING: A transparent enum with no fields (or whose fields are all 1-ZST) is legal rust
+ // [1], but it is a zero-sized type and as such is "best avoided entirely" [2] because it
+ // "will be nonsensical or problematic if passed through the FFI boundary" [1]. Further,
+ // because no well-defined underlying native type exists for a 1-ZST, we cannot emit a
+ // typedef and must fall back to repr(C) behavior that defines a tagged enum.
+ //
+ // [1] https://doc.rust-lang.org/nomicon/other-reprs.html
+ // [2] https://github.com/rust-lang/rust/issues/77841#issuecomment-716796313
+ if repr.style == ReprStyle::Transparent {
+ let zero_sized = match variants.first() {
+ Some(EnumVariant {
+ body: VariantBody::Body { ref body, .. },
+ ..
+ }) => body.fields.is_empty(),
+ _ => true,
+ };
+ if zero_sized {
+ warn!("Passing zero-sized transparent enum {} across the FFI boundary is undefined behavior", &path);
+ repr.style = ReprStyle::C;
+ }
+ }
+
  let export_name = path.name().to_owned();
  Self {
  path,
@@ -438,6 +465,28 @@ impl Enum {
  documentation,
  }
  }
+
+ /// Attempts to convert this enum to a typedef (only works for transparent enums).
+ pub fn as_typedef(&self) -> Option<Typedef> {
+ if self.is_transparent() {
+ if let Some(EnumVariant {
+ body: VariantBody::Body { ref body, .. },
+ ..
+ }) = self.variants.first()
+ {
+ if let Some(field) = body.fields.first() {
+ return Some(Typedef::new_from_item_field(self, field));
+ }
+ }
+ }
+ None
+ }
+
+ // Transparent enums become typedefs, so try converting to typedef and recurse on that.
+ pub fn as_transparent_alias(&self, generics: &[GenericArgument]) -> Option<Type> {
+ self.as_typedef()
+ .and_then(|t| t.as_transparent_alias(generics))
+ }
 }
 
 impl Item for Enum {
@@ -470,7 +519,9 @@ impl Item for Enum {
  }
 
  fn collect_declaration_types(&self, resolver: &mut DeclarationTypeResolver) {
- if self.tag.is_some() {
+ if self.repr.style == ReprStyle::Transparent {
+ resolver.add_none(&self.path);
+ } else if self.tag.is_some() {
  if self.repr.style == ReprStyle::C {
  resolver.add_struct(&self.path);
  } else {

src/bindgen/ir/structure.rs

@@ -136,10 +136,12 @@ impl Struct {
  // [2] https://github.com/rust-lang/rust/issues/77841#issuecomment-716796313
  // [3] https://doc.rust-lang.org/nomicon/other-reprs.html
  if fields.is_empty() {
- warn!(
- "Passing zero-sized struct {} across the FFI boundary is undefined behavior",
- &path
- );
+ if !is_enum_variant_body {
+ warn!(
+ "Passing zero-sized struct {} across the FFI boundary is undefined behavior",
+ &path
+ );
+ }
  is_transparent = false;
  }
 
@@ -163,7 +165,7 @@ impl Struct {
  /// Attempts to convert this struct to a typedef (only works for transparent structs).
  pub fn as_typedef(&self) -> Option<Typedef> {
  match self.fields.first() {
- Some(field) if self.is_transparent => Some(Typedef::new_from_struct_field(self, field)),
+ Some(field) if self.is_transparent => Some(Typedef::new_from_item_field(self, field)),
  _ => None,
  }
  }

src/bindgen/ir/ty.rs

@@ -569,6 +569,7 @@ impl Type {
  ItemContainer::OpaqueItem(o) => o.as_transparent_alias(&generics),
  ItemContainer::Typedef(t) => t.as_transparent_alias(&generics),
  ItemContainer::Struct(s) => s.as_transparent_alias(&generics),
+ ItemContainer::Enum(e) => e.as_transparent_alias(&generics),
  _ => None,
  };
  if let Some(mut ty) = aliased_ty {

src/bindgen/ir/typedef.rs

@@ -11,7 +11,7 @@ use crate::bindgen::declarationtyperesolver::DeclarationTypeResolver;
 use crate::bindgen::dependencies::Dependencies;
 use crate::bindgen::ir::{
  AnnotationSet, Cfg, Documentation, Field, GenericArgument, GenericParams, Item, ItemContainer,
- Path, Struct, TransparentTypeEraser, Type,
+ Path, TransparentTypeEraser, Type,
 };
 use crate::bindgen::library::Library;
 use crate::bindgen::mangle;
@@ -69,12 +69,12 @@ impl Typedef {
  }
  }
 
- // Used to convert a transparent Struct to a Typedef.
- pub fn new_from_struct_field(item: &Struct, field: &Field) -> Self {
+ // Used to convert a transparent Struct or Enum to a Typedef.
+ pub fn new_from_item_field(item: &impl Item, field: &Field) -> Self {
  Self {
  path: item.path().clone(),
  export_name: item.export_name().to_string(),
- generic_params: item.generic_params.clone(),
+ generic_params: item.generic_params().clone(),
  aliased: field.ty.clone(),
  cfg: item.cfg().cloned(),
  annotations: item.annotations().clone(),

src/bindgen/language_backend/mod.rs

@@ -157,6 +157,27 @@ pub trait LanguageBackend: Sized {
  }
  }
 
+ /// If the enum is transparent, emit a typedef of its NZST field type instead.
+ fn write_enum_or_typedef<W: Write>(
+ &mut self,
+ out: &mut SourceWriter<W>,
+ e: &Enum,
+ _b: &Bindings,
+ ) {
+ if let Some(typedef) = e.as_typedef() {
+ self.write_type_def(out, &typedef);
+ // TODO: Associated constants are not supported for enums. Should they be? Rust
+ // enum exports as a union, and C/C++ at least supports static union members?
+ //
+ //for constant in &e.associated_constants {
+ // out.new_line();
+ // constant.write(b.config, self, out, Some(e));
+ //}
+ } else {
+ self.write_enum(out, e);
+ }
+ }
+
  fn write_items<W: Write>(&mut self, out: &mut SourceWriter<W>, b: &Bindings) {
  for item in &b.items {
  if item
@@ -172,7 +193,7 @@ pub trait LanguageBackend: Sized {
  match *item {
  ItemContainer::Constant(..) => unreachable!(),
  ItemContainer::Static(..) => unreachable!(),
- ItemContainer::Enum(ref x) => self.write_enum(out, x),
+ ItemContainer::Enum(ref x) => self.write_enum_or_typedef(out, x, b),
  ItemContainer::Struct(ref x) => self.write_struct_or_typedef(out, x, b),
  ItemContainer::Union(ref x) => self.write_union(out, x),
  ItemContainer::OpaqueItem(ref x) => self.write_opaque_item(out, x),

tests/expectations/const_transparent.compat.c

@@ -3,17 +3,29 @@
 #include <stdint.h>
 #include <stdlib.h>
 
+#define TransparentEnum_ASSOC_ENUM_FOO 8
+
 typedef uint8_t TransparentStruct;
 #define TransparentStruct_ASSOC_STRUCT_FOO 1
 #define TransparentStruct_ASSOC_STRUCT_BAR 2
 
 
 typedef uint8_t TransparentTupleStruct;
 
+typedef uint8_t TransparentEnum;
+
 #define STRUCT_FOO 4
 
 #define STRUCT_BAR 5
 
 
 
 
+
+
+
+
+
+
+
+

tests/expectations/const_transparent.cpp

@@ -4,6 +4,8 @@
 #include <ostream>
 #include <new>
 
+constexpr static const int64_t TransparentEnum_ASSOC_ENUM_FOO = 8;
+
 template<typename T>
 using Wrapper = T;
 
@@ -17,10 +19,23 @@ using TransparentTupleStruct = uint8_t;
 template<typename T>
 using TransparentStructWithErasedField = T;
 
+using TransparentEnum = uint8_t;
+
+template<typename T>
+using TransparentWrapperEnum = T;
+
 constexpr static const TransparentStruct STRUCT_FOO = 4;
 
 constexpr static const TransparentTupleStruct STRUCT_BAR = 5;
 
 constexpr static const TransparentStruct STRUCT_BAZ = 6;
 
 constexpr static const TransparentStructWithErasedField<TransparentStruct> COMPLEX = 7;
+
+
+
+
+
+
+
+

tests/expectations/const_transparent.pyx

@@ -6,17 +6,29 @@ cdef extern from *:
 
 cdef extern from *:
 
+ const int64_t TransparentEnum_ASSOC_ENUM_FOO # = 8
+
  ctypedef uint8_t TransparentStruct;
  const int64_t TransparentStruct_ASSOC_STRUCT_FOO # = 1
  const TransparentStruct TransparentStruct_ASSOC_STRUCT_BAR # = 2
 
 
  ctypedef uint8_t TransparentTupleStruct;
 
+ ctypedef uint8_t TransparentEnum;
+
  const TransparentStruct STRUCT_FOO # = 4
 
  const TransparentTupleStruct STRUCT_BAR # = 5
 
 
 
 
+
+
+
+
+
+
+
+