feat: Add support for custom per-field attributes

This adds the ability to apply custom Rust attributes to individual
struct, union, and newtype fields in generated bindings through three
mechanisms:

1. HTML annotations in C/C++ comments:
   /// <div rustbindgen attribute="serde(rename = x_coord)"></div>
   int x;

2. ParseCallbacks::field_attributes() method for programmatic control:
   fn field_attributes(&self, info: &FieldAttributeInfo) -> Vec<String>

3. CLI flag and Builder API for pattern-based attributes:
   --field-attr "Point::x=serde(rename = x_coord)"
   .field_attribute("Point", "x", "serde(rename = x_coord)")

All three mechanisms can be used together, with attributes merged in
order: annotations, callbacks, then CLI/Builder patterns.

This is useful for adding serde attributes, documentation, or other
derive-related metadata to specific fields.

Author: jsgf

bindgen-tests/tests/expectations/tests/field_attr_annotation.rs

@@ -0,0 +1,17 @@
+/// <div rustbindgen deriveDebug></div>
+struct Point {
+    /// <div rustbindgen attribute="serde(rename = x_coord)"></div>
+    int x;
+    /// <div rustbindgen attribute="serde(rename = y_coord)"></div>
+    int y;
+};
+
+/// <div rustbindgen deriveDebug></div>
+union Data {
+    /// <div rustbindgen attribute="serde(skip)"></div>
+    int i;
+    float f;
+};
+
+/// <div rustbindgen attribute="serde(skip)"></div>
+typedef int Handle;

bindgen-tests/tests/expectations/tests/field_attr_cli.rs

@@ -0,0 +1,13 @@
+// bindgen-flags: --field-attr "Point::x=serde(rename = x_coord)" --field-attr "Point::y=serde(rename = y_coord)" --field-attr "Data::i=serde(skip)" --field-attr "Handle::0=serde(skip)" --new-type-alias "Handle"
+
+struct Point {
+    int x;
+    int y;
+};
+
+union Data {
+    int i;
+    float f;
+};
+
+typedef int Handle;

bindgen-tests/tests/headers/field_attr_annotation.h

@@ -142,6 +142,35 @@ pub trait ParseCallbacks: fmt::Debug {
         vec![]
     }
 
+    /// Provide a list of custom attributes for struct/union fields.
+    ///
+    /// These attributes will be applied to the field in the generated Rust code.
+    /// If no additional attributes are wanted, this function should return an
+    /// empty `Vec`.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use bindgen::callbacks::{ParseCallbacks, FieldAttributeInfo};
+    /// # #[derive(Debug)]
+    /// # struct MyCallbacks;
+    /// # impl ParseCallbacks for MyCallbacks {
+    /// fn field_attributes(&self, info: &FieldAttributeInfo<'_>) -> Vec<String> {
+    ///     if info.field_name == "internal" {
+    ///         vec!["serde(skip)".to_string()]
+    ///     } else if info.field_name == "0" {
+    ///         // Newtype tuple field
+    ///         vec!["serde(transparent)".to_string()]
+    ///     } else {
+    ///         vec![]
+    ///     }
+    /// }
+    /// # }
+    /// ```
+    fn field_attributes(&self, _info: &FieldAttributeInfo<'_>) -> Vec<String> {
+        vec![]
+    }
+
     /// Process a source code comment.
     fn process_comment(&self, _comment: &str) -> Option<String> {
         None
@@ -334,6 +363,27 @@ pub struct FieldInfo<'a> {
     pub field_type_name: Option<&'a str>,
 }
 
+/// Relevant information about a field to which new attributes will be added using
+/// [`ParseCallbacks::field_attributes`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[non_exhaustive]
+pub struct FieldAttributeInfo<'a> {
+    /// The name of the containing type (struct/union).
+    pub type_name: &'a str,
+
+    /// The kind of the containing type.
+    pub type_kind: TypeKind,
+
+    /// The name of the field.
+    ///
+    /// For newtype tuple structs (when using `--default-alias-style=new_type`),
+    /// this will be `"0"` for the inner field.
+    pub field_name: &'a str,
+
+    /// The name of the field's type, if available.
+    pub field_type_name: Option<&'a str>,
+}
+
 /// Location in the source code. Roughly equivalent to the same type
 /// within `clang_sys`.
 #[derive(Clone, Debug, PartialEq, Eq)]

bindgen-tests/tests/headers/field_attr_cli.h

@@ -21,8 +21,8 @@ use self::struct_layout::StructLayoutTracker;
 use super::BindgenOptions;
 
 use crate::callbacks::{
-    AttributeInfo, DeriveInfo, DiscoveredItem, DiscoveredItemId, FieldInfo,
-    TypeKind as DeriveTypeKind,
+    AttributeInfo, DeriveInfo, DiscoveredItem, DiscoveredItemId,
+    FieldAttributeInfo, FieldInfo, TypeKind as DeriveTypeKind,
 };
 use crate::codegen::error::Error;
 use crate::ir::analysis::{HasVtable, Sizedness};
@@ -1138,8 +1138,48 @@ impl CodeGenerator for Type {
                             })
                             .unwrap_or(ctx.options().default_visibility);
                         let access_spec = access_specifier(visibility);
+
+                        // Collect field attributes from multiple sources for newtype tuple field
+                        let mut all_field_attributes = Vec::new();
+
+                        // 1. Get attributes from typedef annotations (if any)
+                        all_field_attributes.extend(
+                            item.annotations().attributes().iter().cloned()
+                        );
+
+                        // 2. Get custom attributes from callbacks
+                        all_field_attributes.extend(ctx.options().all_callbacks(|cb| {
+                            cb.field_attributes(&FieldAttributeInfo {
+                                type_name: &item.canonical_name(ctx),
+                                type_kind: DeriveTypeKind::Struct,
+                                field_name: "0",
+                                field_type_name: inner_item.expect_type().name(),
+                            })
+                        }));
+
+                        // 3. Get attributes from CLI/Builder patterns
+                        let type_name = item.canonical_name(ctx);
+                        for (type_pat, field_pat, attr) in &ctx.options().field_attr_patterns {
+                            if type_pat.as_ref() == type_name && field_pat.as_ref() == "0" {
+                                all_field_attributes.push(attr.to_string());
+                            }
+                        }
+
+                        // Build the field with attributes
+                        let mut field_tokens = quote! {};
+                        for attr in &all_field_attributes {
+                            let attr_tokens: proc_macro2::TokenStream =
+                                attr.parse().expect("Invalid field attribute");
+                            field_tokens.append_all(quote! {
+                                #[#attr_tokens]
+                            });
+                        }
+                        field_tokens.append_all(quote! {
+                            #access_spec #inner_rust_type
+                        });
+
                         quote! {
-                            (#access_spec #inner_rust_type) ;
+                            (#field_tokens) ;
                         }
                     }
                 });
@@ -1569,6 +1609,45 @@ impl FieldCodegen<'_> for FieldData {
         let accessor_kind =
             self.annotations().accessor_kind().unwrap_or(accessor_kind);
 
+        // Collect field attributes from multiple sources
+        let mut all_field_attributes = Vec::new();
+
+        // 1. Get attributes from field annotations (/// <div rustbindgen attribute="..."></div>)
+        all_field_attributes.extend(
+            self.annotations().attributes().iter().cloned()
+        );
+
+        // 2. Get custom attributes from callbacks
+        all_field_attributes.extend(ctx.options().all_callbacks(|cb| {
+            cb.field_attributes(&FieldAttributeInfo {
+                type_name: &parent_item.canonical_name(ctx),
+                type_kind: if parent.is_union() {
+                    DeriveTypeKind::Union
+                } else {
+                    DeriveTypeKind::Struct
+                },
+                field_name,
+                field_type_name: field_ty.name(),
+            })
+        }));
+
+        // 3. Get attributes from CLI/Builder patterns
+        let type_name = parent_item.canonical_name(ctx);
+        for (type_pat, field_pat, attr) in &ctx.options().field_attr_patterns {
+            if type_pat.as_ref() == type_name && field_pat.as_ref() == field_name {
+                all_field_attributes.push(attr.to_string());
+            }
+        }
+
+        // Apply all custom attributes to the field
+        for attr in &all_field_attributes {
+            let attr_tokens: proc_macro2::TokenStream =
+                attr.parse().expect("Invalid field attribute");
+            field.append_all(quote! {
+                #[#attr_tokens]
+            });
+        }
+
         match visibility {
             FieldVisibilityKind::Private => {
                 field.append_all(quote! {

bindgen/callbacks.rs

@@ -137,6 +137,27 @@ fn parse_custom_attribute(
     Ok((attributes, regex.to_owned()))
 }
 
+fn parse_field_attr(
+    field_attr: &str,
+) -> Result<(String, String, String), Error> {
+    // Parse format: TYPE::FIELD=ATTR
+    // We need to split on the first '=' after finding the '::'
+    let (type_field, attr) = field_attr
+        .split_once('=')
+        .ok_or_else(|| Error::raw(ErrorKind::InvalidValue, "Missing `=` in field-attr"))?;
+
+    let (type_name, field_name) = type_field
+        .rsplit_once("::")
+        .ok_or_else(|| Error::raw(ErrorKind::InvalidValue, "Missing `::` in field-attr. Expected format: TYPE::FIELD=ATTR"))?;
+
+    // Validate the attribute is valid Rust syntax
+    if let Err(err) = TokenStream::from_str(attr) {
+        return Err(Error::raw(ErrorKind::InvalidValue, err));
+    }
+
+    Ok((type_name.to_owned(), field_name.to_owned(), attr.to_owned()))
+}
+
 #[derive(Parser, Debug)]
 #[clap(
     about = "Generates Rust bindings from C/C++ headers.",
@@ -531,6 +552,9 @@ struct BindgenCommand {
     /// be called.
     #[arg(long)]
     generate_private_functions: bool,
+    /// Add a custom attribute to a field. The SPEC value must be of the shape TYPE::FIELD=ATTR.
+    #[arg(long, value_name = "SPEC", value_parser = parse_field_attr)]
+    field_attr: Vec<(String, String, String)>,
     /// Whether to emit diagnostics or not.
     #[cfg(feature = "experimental")]
     #[arg(long, requires = "experimental")]
@@ -684,6 +708,7 @@ where
         generate_deleted_functions,
         generate_pure_virtual_functions,
         generate_private_functions,
+        field_attr,
         #[cfg(feature = "experimental")]
         emit_diagnostics,
         generate_shell_completions,
@@ -981,6 +1006,7 @@ where
             generate_deleted_functions,
             generate_pure_virtual_functions,
             generate_private_functions,
+            field_attr => |b, (type_name, field_name, attr)| b.field_attribute(type_name, field_name, attr),
         }
     );
 

bindgen/codegen/mod.rs

@@ -2329,4 +2329,51 @@ options! {
         },
         as_args: "--generate-private-functions",
     },
+    /// Field attribute patterns for adding custom attributes to struct/union fields.
+    field_attr_patterns: Vec<(Box<str>, Box<str>, Box<str>)> {
+        methods: {
+            /// Add a custom attribute to a specific field.
+            ///
+            /// # Arguments
+            ///
+            /// * `type_name` - The name of the struct or union containing the field
+            /// * `field_name` - The name of the field (use "0" for newtype tuple fields)
+            /// * `attribute` - The attribute to add (e.g., "serde(skip)")
+            ///
+            /// # Example
+            ///
+            /// ```ignore
+            /// bindgen::Builder::default()
+            ///     .header("input.h")
+            ///     .field_attribute("MyStruct", "data", r#"serde(rename = "myData")"#)
+            ///     .field_attribute("MyStruct", "secret", "serde(skip)")
+            ///     .generate()
+            ///     .unwrap();
+            /// ```
+            pub fn field_attribute<T, F, A>(
+                mut self,
+                type_name: T,
+                field_name: F,
+                attribute: A,
+            ) -> Self
+            where
+                T: Into<String>,
+                F: Into<String>,
+                A: Into<String>,
+            {
+                self.options.field_attr_patterns.push((
+                    type_name.into().into_boxed_str(),
+                    field_name.into().into_boxed_str(),
+                    attribute.into().into_boxed_str(),
+                ));
+                self
+            }
+        },
+        as_args: |patterns, args| {
+            for (type_pat, field_pat, attr) in patterns {
+                args.push("--field-attr".to_owned());
+                args.push(format!("{type_pat}::{field_pat}={attr}"));
+            }
+        },
+    },
 }