Implement mix-in #[methods] blocks

Adds the `#[methods(mixin = "Name")]` syntax for declaring mix-in
blocks. Mix-in blocks have a many-to-many relationship with
`NativeClass` types. Both `impl Type` and `impl Trait for Type` blocks
are accepted.

All mix-in blocks have to be manually registered for gdnative v0.11.x.
This can be relaxed in the future with a redesign of the `NativeClass`
hierarchy of traits.

Author: chitoyuu

check.sh

@@ -62,7 +62,7 @@ function findGodot() {
     fi
 }
 
-features="gdnative/async,gdnative/serde"
+features="gdnative/async,gdnative/serde,gdnative/inventory"
 cmds=()
 
 for arg in "${args[@]}"; do

gdnative-core/src/export/class_builder.rs

@@ -1,3 +1,6 @@
+use std::any::TypeId;
+use std::cell::RefCell;
+use std::collections::HashSet;
 use std::ffi::CString;
 use std::marker::PhantomData;
 use std::ptr;
@@ -20,6 +23,7 @@ use crate::private::get_api;
 pub struct ClassBuilder<C> {
     pub(super) init_handle: *mut libc::c_void,
     pub(super) class_name: CString,
+    mixins: RefCell<HashSet<TypeId, ahash::RandomState>>,
     _marker: PhantomData<C>,
 }
 
@@ -28,6 +32,7 @@ impl<C: NativeClass> ClassBuilder<C> {
         Self {
             init_handle,
             class_name,
+            mixins: RefCell::default(),
             _marker: PhantomData,
         }
     }
@@ -241,4 +246,48 @@ impl<C: NativeClass> ClassBuilder<C> {
             );
         }
     }
+
+    /// Add a mixin to the class being registered.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use gdnative::prelude::*;
+    ///
+    /// #[derive(NativeClass)]
+    /// #[inherit(Node)]
+    /// #[register_with(my_register)]
+    /// #[no_constructor]
+    /// struct MyType {}
+    ///
+    /// // This creates a opaque type `MyMixin` in the current scope that implements
+    /// // the `Mixin` trait. Mixin types have no public interface or stable layout.
+    /// #[methods(mixin = "MyMixin")]
+    /// impl MyType {
+    ///     #[method]
+    ///     fn my_method(&self) -> i64 { 42 }
+    /// }
+    ///
+    /// fn my_register(builder: &ClassBuilder<MyType>) {
+    ///     builder.mixin::<MyMixin>();
+    /// }
+    /// ```
+    #[inline]
+    pub fn mixin<M: Mixin<C>>(&self) {
+        if self.mixins.borrow_mut().insert(TypeId::of::<M>()) {
+            M::register(self);
+        }
+    }
+}
+
+/// Trait for mixins, manually registered `#[methods]` blocks that may be applied to multiple types.
+///
+/// This trait is implemented on generated types by the `#[methods]` proc-macro only, and has no public interface.
+/// Use [`ClassBuilder::mixin`] to register mixins to [`NativeClass`] types.    
+pub trait Mixin<C>: crate::private::mixin::Sealed + 'static
+where
+    C: NativeClass,
+{
+    #[doc(hidden)]
+    fn register(builder: &ClassBuilder<C>);
 }

gdnative-core/src/private.rs

@@ -202,31 +202,42 @@ pub(crate) fn print_panic_error(err: Box<dyn std::any::Any + Send>) {
     }
 }
 
-/// Plugin type to be used by macros for auto registration.
+/// Plugin type to be used by macros for auto class registration.
 pub struct AutoInitPlugin {
     pub f: fn(init_handle: crate::init::InitHandle),
 }
 
 #[cfg(feature = "inventory")]
-pub use inventory::submit as inventory_submit;
+pub mod inventory {
+    pub use inventory::{collect, submit};
 
-#[cfg(feature = "inventory")]
-inventory::collect!(AutoInitPlugin);
-
-#[cfg(not(feature = "inventory"))]
-pub use crate::_gdnative_inventory_submit as inventory_submit;
+    inventory::collect!(super::AutoInitPlugin);
+}
 
 #[cfg(not(feature = "inventory"))]
-#[macro_export]
-#[doc(hidden)]
-macro_rules! _gdnative_inventory_submit {
-    ($($tt:tt)*) => {};
+pub mod inventory {
+    pub use crate::_inventory_discard as submit;
+    pub use crate::_inventory_discard as collect;
+
+    #[macro_export]
+    #[doc(hidden)]
+    macro_rules! _inventory_discard {
+        ($($tt:tt)*) => {};
+    }
 }
 
 pub mod godot_object {
     pub trait Sealed {}
 }
 
+pub mod mixin {
+    pub trait Sealed {}
+
+    pub struct Opaque {
+        _private: (),
+    }
+}
+
 pub(crate) struct ManuallyManagedClassPlaceholder;
 
 unsafe impl crate::object::GodotObject for ManuallyManagedClassPlaceholder {

gdnative-derive/src/lib.rs

@@ -8,12 +8,12 @@ extern crate quote;
 use proc_macro::TokenStream;
 use proc_macro2::TokenStream as TokenStream2;
 use quote::ToTokens;
-use syn::{AttributeArgs, DeriveInput, ItemFn, ItemImpl, ItemType};
+use syn::{parse::Parser, AttributeArgs, DeriveInput, ItemFn, ItemImpl, ItemType};
 
-mod extend_bounds;
 mod methods;
 mod native_script;
 mod profiled;
+mod utils;
 mod varargs;
 mod variant;
 
@@ -44,13 +44,13 @@ mod variant;
 /// ```
 #[proc_macro_attribute]
 pub fn methods(meta: TokenStream, input: TokenStream) -> TokenStream {
-    if syn::parse::<syn::parse::Nothing>(meta.clone()).is_err() {
-        let err = syn::Error::new_spanned(
-            TokenStream2::from(meta),
-            "#[methods] does not take parameters.",
-        );
-        return error_with_input(input, err);
-    }
+    let args =
+        match syn::punctuated::Punctuated::<syn::NestedMeta, syn::Token![,]>::parse_terminated
+            .parse(meta)
+        {
+            Ok(args) => args.into_iter().collect::<Vec<_>>(),
+            Err(err) => return error_with_input(input, err),
+        };
 
     let impl_block = match syn::parse::<ItemImpl>(input.clone()) {
         Ok(impl_block) => impl_block,
@@ -63,7 +63,10 @@ pub fn methods(meta: TokenStream, input: TokenStream) -> TokenStream {
         err
     }
 
-    TokenStream::from(methods::derive_methods(impl_block))
+    match methods::derive_methods(args, impl_block) {
+        Ok(ts) => ts.into(),
+        Err(err) => error_with_input(input, err),
+    }
 }
 
 /// Makes a function profiled in Godot's built-in profiler. This macro automatically
@@ -593,7 +596,16 @@ fn crate_gdnative_core() -> proc_macro2::TokenStream {
         .expect("crate not found");
 
     match found_crate {
-        proc_macro_crate::FoundCrate::Itself => quote!(crate),
+        proc_macro_crate::FoundCrate::Itself => {
+            // Workaround: `proc-macro-crate` returns `Itself` in doc-tests, and refuses to use unstable env
+            // variables for detection.
+            // See https://github.com/bkchr/proc-macro-crate/issues/11
+            if std::env::var_os("UNSTABLE_RUSTDOC_TEST_PATH").is_some() {
+                quote!(gdnative_core)
+            } else {
+                quote!(crate)
+            }
+        }
         proc_macro_crate::FoundCrate::Name(name) => {
             let ident = proc_macro2::Ident::new(&name, proc_macro2::Span::call_site());
             ident.to_token_stream()
@@ -625,6 +637,29 @@ fn crate_gdnative_async() -> proc_macro2::TokenStream {
     }
 }
 
+/// Returns the (possibly renamed or imported as `gdnative`) identifier of the `gdnative_bindings` crate.
+fn crate_gdnative_bindings() -> proc_macro2::TokenStream {
+    if let Ok(found_crate) = proc_macro_crate::crate_name("gdnative-bindings") {
+        return match found_crate {
+            proc_macro_crate::FoundCrate::Itself => quote!(crate),
+            proc_macro_crate::FoundCrate::Name(name) => {
+                let ident = proc_macro2::Ident::new(&name, proc_macro2::Span::call_site());
+                ident.to_token_stream()
+            }
+        };
+    }
+
+    let found_crate = proc_macro_crate::crate_name("gdnative").expect("crate not found");
+
+    match found_crate {
+        proc_macro_crate::FoundCrate::Itself => quote!(crate::api),
+        proc_macro_crate::FoundCrate::Name(name) => {
+            let ident = proc_macro2::Ident::new(&name, proc_macro2::Span::call_site());
+            quote!( #ident::api )
+        }
+    }
+}
+
 /// Hack to emit a warning in expression position through `deprecated`.
 /// This is because there is no way to emit warnings from macros in stable Rust.
 fn emit_warning<S: std::fmt::Display>(

gdnative-derive/src/methods.rs

@@ -1,9 +1,18 @@
-use syn::{spanned::Spanned, FnArg, Generics, ImplItem, ItemImpl, Pat, PatIdent, Signature, Type};
+use syn::{
+    spanned::Spanned, visit::Visit, FnArg, Generics, ImplItem, ItemImpl, Meta, NestedMeta, Pat,
+    PatIdent, Signature, Type,
+};
 
 use proc_macro2::TokenStream as TokenStream2;
 use quote::{quote, ToTokens};
 use std::boxed::Box;
 
+use crate::utils::find_non_concrete;
+
+use self::mixin_args::{MixinArgsBuilder, MixinKind};
+
+mod mixin_args;
+
 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
 pub enum RpcMode {
     Disabled,
@@ -322,15 +331,57 @@ pub(crate) struct ExportArgs {
     pub(crate) is_async: bool,
 }
 
-pub(crate) fn derive_methods(item_impl: ItemImpl) -> TokenStream2 {
+pub(crate) fn derive_methods(
+    args: Vec<NestedMeta>,
+    item_impl: ItemImpl,
+) -> Result<TokenStream2, syn::Error> {
     let derived = crate::automatically_derived();
+    let gdnative_core = crate::crate_gdnative_core();
     let (impl_block, export) = impl_gdnative_expose(item_impl);
     let (impl_generics, _, where_clause) = impl_block.generics.split_for_impl();
 
     let class_name = export.class_ty;
 
     let builder = syn::Ident::new("builder", proc_macro2::Span::call_site());
 
+    let args = {
+        let mut attr_args_builder = MixinArgsBuilder::new();
+
+        for arg in args {
+            if let NestedMeta::Meta(Meta::NameValue(ref pair)) = arg {
+                attr_args_builder.add_pair(pair)?;
+            } else if let NestedMeta::Meta(Meta::Path(ref path)) = arg {
+                attr_args_builder.add_path(path)?;
+            } else {
+                let msg = format!("Unexpected argument: {arg:?}");
+                return Err(syn::Error::new(arg.span(), msg));
+            }
+        }
+
+        attr_args_builder.done()?
+    };
+
+    let non_concrete = find_non_concrete::with_visitor(&impl_block.generics, |v| {
+        v.visit_type(&impl_block.self_ty)
+    });
+
+    let non_concrete = if non_concrete.is_empty() {
+        None
+    } else if non_concrete.len() == 1 {
+        Some(non_concrete[0])
+    } else {
+        Some(impl_block.self_ty.span())
+    };
+
+    if let Some(span) = non_concrete {
+        if matches!(args.mixin, Some(MixinKind::Auto(_))) {
+            return Err(syn::Error::new(
+                span,
+                "non-concrete mixins must be named and manually registered",
+            ));
+        }
+    }
+
     let methods = export
         .methods
         .into_iter()
@@ -402,19 +453,66 @@ pub(crate) fn derive_methods(item_impl: ItemImpl) -> TokenStream2 {
         })
         .collect::<Vec<_>>();
 
-    quote::quote!(
-        #impl_block
+    match args.mixin {
+        Some(mixin_kind) => {
+            let vis = args.pub_.then(|| quote!(pub));
+
+            let mixin_name = match &mixin_kind {
+                MixinKind::Named(ident) => ident.clone(),
+                MixinKind::Auto(span) => {
+                    return Err(syn::Error::new(
+                        *span,
+                        "mixins must be named in gdnative v0.11.x",
+                    ))
+                }
+            };
 
-        #derived
-        impl #impl_generics gdnative::export::NativeClassMethods for #class_name #where_clause {
-            fn nativeclass_register(#builder: &::gdnative::export::ClassBuilder<Self>) {
-                use gdnative::export::*;
+            let body = quote! {
+                #derived
+                #vis struct #mixin_name {
+                    _opaque: #gdnative_core::private::mixin::Opaque,
+                }
 
-                #(#methods)*
-            }
+                #derived
+                impl #gdnative_core::private::mixin::Sealed for #mixin_name {}
+                #derived
+                impl #impl_generics #gdnative_core::export::Mixin<#class_name> for #mixin_name #where_clause {
+                    fn register(#builder: &#gdnative_core::export::ClassBuilder<#class_name>) {
+                        use #gdnative_core::export::*;
+
+                        #(#methods)*
+                    }
+                }
+            };
+
+            let body = match &mixin_kind {
+                MixinKind::Named(_) => body,
+                MixinKind::Auto(_) => quote! {
+                    const _: () = {
+                        #body
+                    }
+                },
+            };
+
+            Ok(quote::quote!(
+                #impl_block
+                #body
+            ))
         }
+        None => Ok(quote::quote!(
+            #impl_block
 
-    )
+            #derived
+            impl #impl_generics #gdnative_core::export::NativeClassMethods for #class_name #where_clause {
+                fn nativeclass_register(#builder: &#gdnative_core::export::ClassBuilder<Self>) {
+                    use #gdnative_core::export::*;
+
+                    #(#methods)*
+                }
+            }
+
+        )),
+    }
 }
 
 /// Extract the data to export from the impl block.
@@ -464,7 +562,7 @@ fn impl_gdnative_expose(ast: ItemImpl) -> (ItemImpl, ClassMethodExport) {
                             };
 
                         if is_export {
-                            use syn::{punctuated::Punctuated, Lit, Meta, NestedMeta};
+                            use syn::{punctuated::Punctuated, Lit};
                             let mut export_args =
                                 export_args.get_or_insert_with(ExportArgs::default);
                             export_args.is_old_syntax = is_old_syntax;