Explicitly instantiate function return values that are template classes

src/bindgen/config.rs

@@ -341,6 +341,15 @@ pub struct ExportConfig {
     pub renaming_overrides_prefixing: bool,
     /// Mangling configuration.
     pub mangle: MangleConfig,
+    /// Whether to instantiate the monomorphs of template types used as function return values. This
+    /// is needed for C compatibility, because otherwise compilers warn (`-Wreturn-type-c-linkage`
+    /// on gcc/clang) or even reject (MSVC) those function definitions. The compensation is made by
+    /// emitting a single struct with one field for each monomorphized type. The emitted wrapper
+    /// struct's name can optionally be overridden by [`return_value_monomorphs_struct_name`].
+    pub instantiate_return_value_monomorphs: bool,
+    /// Overrides the struct name to use when [`instantiate_return_value_monomorphs`] is enabled
+    /// (ignored otherwise). If not specified, the default is `__cbindgen_return_value_monomorphs`.
+    pub return_value_monomorphs_struct_name: Option<String>,
 }
 
 /// Mangling-specific configuration.

src/bindgen/ir/documentation.rs

@@ -4,7 +4,7 @@
 
 use crate::bindgen::utilities::SynAttributeHelpers;
 
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, Default)]
 pub struct Documentation {
     pub doc_comment: Vec<String>,
 }
@@ -27,8 +27,6 @@ impl Documentation {
     }
 
     pub fn none() -> Self {
-        Documentation {
-            doc_comment: Vec::new(),
-        }
+        Self::default()
     }
 }

src/bindgen/ir/enumeration.rs

@@ -17,7 +17,7 @@ use crate::bindgen::ir::{
 use crate::bindgen::language_backend::LanguageBackend;
 use crate::bindgen::library::Library;
 use crate::bindgen::mangle;
-use crate::bindgen::monomorph::Monomorphs;
+use crate::bindgen::monomorph::{Monomorphs, ReturnValueMonomorphs};
 use crate::bindgen::rename::{IdentifierType, RenameRule};
 use crate::bindgen::reserved;
 use crate::bindgen::writer::{ListType, SourceWriter};
@@ -317,6 +317,14 @@ impl Enum {
         repr.style != ReprStyle::C
     }
 
+    pub fn find_return_value_monomorphs(&self, monomorphs: &mut ReturnValueMonomorphs<'_>) {
+        for v in &self.variants {
+            if let VariantBody::Body { ref body, .. } = v.body {
+                body.find_return_value_monomorphs(monomorphs);
+            }
+        }
+    }
+
     pub fn add_monomorphs(&self, library: &Library, out: &mut Monomorphs) {
         if self.is_generic() {
             return;

src/bindgen/ir/function.rs

@@ -9,9 +9,11 @@ use syn::ext::IdentExt;
 use crate::bindgen::config::{Config, Language};
 use crate::bindgen::declarationtyperesolver::DeclarationTypeResolver;
 use crate::bindgen::dependencies::Dependencies;
-use crate::bindgen::ir::{AnnotationSet, Cfg, Documentation, GenericPath, Path, Type};
+use crate::bindgen::ir::{
+    AnnotationSet, Cfg, Documentation, GenericParams, GenericPath, Path, Type,
+};
 use crate::bindgen::library::Library;
-use crate::bindgen::monomorph::Monomorphs;
+use crate::bindgen::monomorph::{Monomorphs, ReturnValueMonomorphs};
 use crate::bindgen::rename::{IdentifierType, RenameRule};
 use crate::bindgen::reserved;
 use crate::bindgen::utilities::IterHelpers;
@@ -47,6 +49,12 @@ impl Function {
         attrs: &[syn::Attribute],
         mod_cfg: Option<&Cfg>,
     ) -> Result<Function, String> {
+        if let Ok(GenericParams(generics)) = GenericParams::load(&sig.generics) {
+            if !generics.is_empty() {
+                return Err("Generic functions are not supported".to_owned());
+            }
+        }
+
         let mut args = sig.inputs.iter().try_skip_map(|x| x.as_argument())?;
         if sig.variadic.is_some() {
             args.push(FunctionArgument {
@@ -129,6 +137,9 @@ impl Function {
         }
     }
 
+    pub fn find_return_value_monomorphs(&self, monomorphs: &mut ReturnValueMonomorphs<'_>) {
+        monomorphs.handle_function(&self.ret, self.args.iter().map(|arg| &arg.ty));
+    }
     pub fn add_monomorphs(&self, library: &Library, out: &mut Monomorphs) {
         self.ret.add_monomorphs(library, out);
         for arg in &self.args {

src/bindgen/ir/structure.rs

@@ -15,7 +15,7 @@ use crate::bindgen::ir::{
 };
 use crate::bindgen::library::Library;
 use crate::bindgen::mangle;
-use crate::bindgen::monomorph::Monomorphs;
+use crate::bindgen::monomorph::{Monomorphs, ReturnValueMonomorphs};
 use crate::bindgen::rename::{IdentifierType, RenameRule};
 use crate::bindgen::reserved;
 use crate::bindgen::utilities::IterHelpers;
@@ -168,9 +168,14 @@ 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)),
-            _ => None,
+        let field = self.fields.first()?;
+        self.is_transparent
+            .then(|| Typedef::new_from_struct_field(self, field))
+    }
+
+    pub fn find_return_value_monomorphs(&self, monomorphs: &mut ReturnValueMonomorphs<'_>) {
+        for field in &self.fields {
+            field.ty.find_return_value_monomorphs(monomorphs, false);
         }
     }
 

src/bindgen/ir/ty.rs

@@ -11,7 +11,7 @@ use crate::bindgen::declarationtyperesolver::DeclarationTypeResolver;
 use crate::bindgen::dependencies::Dependencies;
 use crate::bindgen::ir::{GenericArgument, GenericParams, GenericPath, Path};
 use crate::bindgen::library::Library;
-use crate::bindgen::monomorph::Monomorphs;
+use crate::bindgen::monomorph::{Monomorphs, ReturnValueMonomorphs};
 use crate::bindgen::utilities::IterHelpers;
 
 #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
@@ -739,6 +739,22 @@ impl Type {
         self.add_dependencies_ignoring_generics(&GenericParams::default(), library, out)
     }
 
+    pub fn find_return_value_monomorphs(
+        &self,
+        monomorphs: &mut ReturnValueMonomorphs<'_>,
+        is_return_value: bool,
+    ) {
+        match self {
+            Type::Ptr { ty, .. } => ty.find_return_value_monomorphs(monomorphs, false),
+            Type::Path(generic) => monomorphs.handle_return_value_path(generic, is_return_value),
+            Type::Primitive(_) => {}
+            Type::Array(ty, _) => ty.find_return_value_monomorphs(monomorphs, false),
+            Type::FuncPtr { ret, args, .. } => {
+                monomorphs.handle_function(ret, args.iter().map(|(_, arg)| arg))
+            }
+        }
+    }
+
     pub fn add_monomorphs(&self, library: &Library, out: &mut Monomorphs) {
         match *self {
             Type::Ptr { ref ty, .. } => {

src/bindgen/ir/typedef.rs

@@ -15,7 +15,7 @@ use crate::bindgen::ir::{
 };
 use crate::bindgen::library::Library;
 use crate::bindgen::mangle;
-use crate::bindgen::monomorph::Monomorphs;
+use crate::bindgen::monomorph::{Monomorphs, ReturnValueMonomorphs};
 
 /// A type alias that is represented as a C typedef
 #[derive(Debug, Clone)]
@@ -102,6 +102,15 @@ impl Typedef {
         }
     }
 
+    pub fn find_return_value_monomorphs(
+        &self,
+        monomorphs: &mut ReturnValueMonomorphs<'_>,
+        is_return_value: bool,
+    ) {
+        self.aliased
+            .find_return_value_monomorphs(monomorphs, is_return_value);
+    }
+
     pub fn add_monomorphs(&self, library: &Library, out: &mut Monomorphs) {
         // Generic structs can instantiate monomorphs only once they've been
         // instantiated. See `instantiate_monomorph` for more details.

src/bindgen/ir/union.rs

@@ -13,7 +13,7 @@ use crate::bindgen::ir::{
 };
 use crate::bindgen::library::Library;
 use crate::bindgen::mangle;
-use crate::bindgen::monomorph::Monomorphs;
+use crate::bindgen::monomorph::{Monomorphs, ReturnValueMonomorphs};
 use crate::bindgen::rename::{IdentifierType, RenameRule};
 use crate::bindgen::utilities::IterHelpers;
 
@@ -100,6 +100,12 @@ impl Union {
         }
     }
 
+    pub fn find_return_value_monomorphs(&self, monomorphs: &mut ReturnValueMonomorphs<'_>) {
+        for field in &self.fields {
+            field.ty.find_return_value_monomorphs(monomorphs, false);
+        }
+    }
+
     pub fn add_monomorphs(&self, library: &Library, out: &mut Monomorphs) {
         // Generic unions can instantiate monomorphs only once they've been
         // instantiated. See `instantiate_monomorph` for more details.

src/bindgen/library.rs

@@ -10,9 +10,11 @@ use crate::bindgen::config::{Config, Language, SortKey};
 use crate::bindgen::declarationtyperesolver::DeclarationTypeResolver;
 use crate::bindgen::dependencies::Dependencies;
 use crate::bindgen::error::Error;
-use crate::bindgen::ir::{Constant, Enum, Function, Item, ItemContainer, ItemMap};
-use crate::bindgen::ir::{OpaqueItem, Path, Static, Struct, Typedef, Union};
-use crate::bindgen::monomorph::Monomorphs;
+use crate::bindgen::ir::{
+    Constant, Enum, Function, Item, ItemContainer, ItemMap, OpaqueItem, Path, Static, Struct,
+    Typedef, Union,
+};
+use crate::bindgen::monomorph::{Monomorphs, ReturnValueMonomorphs};
 use crate::bindgen::ItemType;
 
 #[derive(Debug, Clone)]
@@ -81,6 +83,12 @@ impl Library {
 
         let mut dependencies = Dependencies::new();
 
+        if self.config.language == Language::Cxx
+            && self.config.export.instantiate_return_value_monomorphs
+        {
+            self.instantiate_return_value_monomorphs(&mut dependencies);
+        }
+
         for function in &self.functions {
             function.add_dependencies(&self, &mut dependencies);
         }
@@ -447,4 +455,28 @@ impl Library {
             x.mangle_paths(&monomorphs);
         }
     }
+
+    fn instantiate_return_value_monomorphs(&mut self, dependencies: &mut Dependencies) {
+        let mut monomorphs = ReturnValueMonomorphs::new(self);
+        self.structs
+            .for_all_items(|x| x.find_return_value_monomorphs(&mut monomorphs));
+        self.unions
+            .for_all_items(|x| x.find_return_value_monomorphs(&mut monomorphs));
+        self.enums
+            .for_all_items(|x| x.find_return_value_monomorphs(&mut monomorphs));
+        self.typedefs
+            .for_all_items(|x| x.find_return_value_monomorphs(&mut monomorphs, false));
+        for x in &self.functions {
+            x.find_return_value_monomorphs(&mut monomorphs);
+        }
+
+        let struct_name = match self.config.export.return_value_monomorphs_struct_name {
+            Some(ref name) => name,
+            _ => "__cbindgen_return_value_monomorphs",
+        };
+        if let Some((struct_name, struct_def)) = monomorphs.into_struct(struct_name) {
+            self.structs.try_insert(struct_def);
+            struct_name.add_dependencies(self, dependencies);
+        }
+    }
 }

src/bindgen/monomorph.rs

@@ -2,11 +2,13 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
+use std::iter::FromIterator as _;
 use std::mem;
 
 use crate::bindgen::ir::{
-    Enum, GenericArgument, GenericPath, Item, OpaqueItem, Path, Struct, Typedef, Union,
+    Documentation, Enum, Field, GenericArgument, GenericPath, Item, ItemContainer, OpaqueItem,
+    Path, Struct, Type, Typedef, Union,
 };
 use crate::bindgen::library::Library;
 
@@ -145,3 +147,109 @@ impl Monomorphs {
         mem::take(&mut self.enums)
     }
 }
+
+/// A helper for collecting all function return value momomorphs -- template types returned by
+/// functions that can lead to compilation warnings/errors if not explicitly instantiated.
+pub struct ReturnValueMonomorphs<'a> {
+    library: &'a Library,
+    monomorphs: HashSet<GenericPath>,
+}
+
+impl<'a> ReturnValueMonomorphs<'a> {
+    pub fn new(library: &'a Library) -> Self {
+        Self {
+            library,
+            monomorphs: HashSet::new(),
+        }
+    }
+
+    /// Resolve a typedef that is a function return value, specializing it first if needed.
+    fn handle_return_value_typedef(&mut self, typedef: Typedef, generic: &GenericPath) {
+        if typedef.is_generic() {
+            let args = generic.generics();
+            let aliased = &typedef.aliased;
+            let mappings = typedef.generic_params.call(typedef.path.name(), args);
+            let aliased = aliased.specialize(&mappings);
+            aliased.find_return_value_monomorphs(self, true);
+        } else {
+            typedef.find_return_value_monomorphs(self, true);
+        }
+    }
+
+    /// Once we find a function return type, what we do with it depends on the type of item it
+    /// resolves to. Typedefs need to be resolved recursively, while generic structs, unions, and
+    /// enums are captured in the set of return value monomorphs.
+    pub fn handle_return_value_path(&mut self, generic: &GenericPath, is_return_value: bool) {
+        if !is_return_value {
+            return;
+        }
+
+        for item in self.library.get_items(generic.path()).into_iter().flatten() {
+            match item {
+                // Constants and statics cannot be function return types
+                ItemContainer::Constant(_) | ItemContainer::Static(_) => {}
+                // Opaque items cannot be instantiated (doomed to compilation failure)
+                ItemContainer::OpaqueItem(_) => {}
+                ItemContainer::Typedef(t) => self.handle_return_value_typedef(t, generic),
+                ItemContainer::Union(_) | ItemContainer::Enum(_) => {
+                    if !generic.generics().is_empty() {
+                        self.monomorphs.insert(generic.clone());
+                    }
+                }
+                ItemContainer::Struct(s) => {
+                    if let Some(t) = s.as_typedef() {
+                        self.handle_return_value_typedef(t, generic);
+                    } else if !generic.generics().is_empty() {
+                        self.monomorphs.insert(generic.clone());
+                    }
+                }
+            }
+        }
+    }
+
+    /// Whenever we encounter a function (or function pointer), we need to check whether its return
+    /// value is an instantiated generic type (monomorph).
+    pub fn handle_function<'i>(&mut self, ret: &Type, args: impl IntoIterator<Item = &'i Type>) {
+        ret.find_return_value_monomorphs(self, true);
+        for arg in args.into_iter() {
+            arg.find_return_value_monomorphs(self, false);
+        }
+    }
+
+    /// Emit all instantiated return value monomorphs as fields of a dummy struct, which silences
+    /// warnings and errors on several compilers.
+    pub fn into_struct(self, struct_name: &str) -> Option<(Type, Struct)> {
+        if self.monomorphs.is_empty() {
+            return None;
+        }
+
+        // Sort the output so that the struct remains stable across runs (tests want that).
+        let mut monomorphs = Vec::from_iter(self.monomorphs);
+        monomorphs.sort();
+        let fields = monomorphs
+            .into_iter()
+            .enumerate()
+            .map(|(i, path)| Field::from_name_and_type(format!("field{}", i), Type::Path(path)))
+            .collect();
+        let doc_comment = vec![
+            " Dummy struct emitted by cbindgen to avoid compiler warnings/errors about",
+            " return type C linkage for template types returned by value from functions",
+        ];
+        let doc_comment = doc_comment.into_iter().map(Into::into).collect();
+        let struct_name = GenericPath::new(Path::new(struct_name), vec![]);
+        let struct_def = Struct::new(
+            struct_name.path().clone(),
+            Default::default(), // no generic params
+            fields,
+            false,              // no tag field
+            false,              // not an enum body
+            None,               // no special alignment requirements
+            false,              // not transparent
+            None,               // no conf
+            Default::default(), // no annotations
+            Documentation { doc_comment },
+        );
+        let struct_name = Type::Path(struct_name);
+        Some((struct_name, struct_def))
+    }
+}

tests/expectations/const_generics_char.cpp

@@ -11,6 +11,12 @@ struct TakeUntil {
   uintptr_t point;
 };
 
+/// Dummy struct emitted by cbindgen to avoid compiler warnings/errors about
+/// return type C linkage for template types returned by value from functions
+struct __cbindgen_return_value_monomorphs {
+  TakeUntil<0> field0;
+};
+
 extern "C" {
 
 TakeUntil<0> until_nul(const uint8_t *start, uintptr_t len);