bindgen/ir/
var.rs

Help
1//! Intermediate representation of variables.
2
3use super::super::codegen::MacroTypeVariation;
4use super::context::{BindgenContext, TypeId};
5use super::dot::DotAttributes;
6use super::function::cursor_mangling;
7use super::int::IntKind;
8use super::item::Item;
9use super::ty::{FloatKind, TypeKind};
10use crate::callbacks::{ItemInfo, ItemKind, MacroParsingBehavior};
11use crate::clang;
12use crate::clang::ClangToken;
13use crate::parse::{ClangSubItemParser, ParseError, ParseResult};
14
15use std::io;
16use std::num::Wrapping;
17
18/// The type for a constant variable.
19#[derive(Debug)]
20pub(crate) enum VarType {
21    /// A boolean.
22    Bool(bool),
23    /// An integer.
24    Int(i64),
25    /// A floating point number.
26    Float(f64),
27    /// A character.
28    Char(u8),
29    /// A string, not necessarily well-formed utf-8.
30    String(Vec<u8>),
31}
32
33/// A `Var` is our intermediate representation of a variable.
34#[derive(Debug)]
35pub(crate) struct Var {
36    /// The name of the variable.
37    name: String,
38    /// The mangled name of the variable.
39    mangled_name: Option<String>,
40    /// The link name of the variable.
41    link_name: Option<String>,
42    /// The type of the variable.
43    ty: TypeId,
44    /// The value of the variable, that needs to be suitable for `ty`.
45    val: Option<VarType>,
46    /// Whether this variable is const.
47    is_const: bool,
48}
49
50impl Var {
51    /// Construct a new `Var`.
52    pub(crate) fn new(
53        name: String,
54        mangled_name: Option<String>,
55        link_name: Option<String>,
56        ty: TypeId,
57        val: Option<VarType>,
58        is_const: bool,
59    ) -> Var {
60        assert!(!name.is_empty());
61        Var {
62            name,
63            mangled_name,
64            link_name,
65            ty,
66            val,
67            is_const,
68        }
69    }
70
71    /// Is this variable `const` qualified?
72    pub(crate) fn is_const(&self) -> bool {
73        self.is_const
74    }
75
76    /// The value of this constant variable, if any.
77    pub(crate) fn val(&self) -> Option<&VarType> {
78        self.val.as_ref()
79    }
80
81    /// Get this variable's type.
82    pub(crate) fn ty(&self) -> TypeId {
83        self.ty
84    }
85
86    /// Get this variable's name.
87    pub(crate) fn name(&self) -> &str {
88        &self.name
89    }
90
91    /// Get this variable's mangled name.
92    pub(crate) fn mangled_name(&self) -> Option<&str> {
93        self.mangled_name.as_deref()
94    }
95
96    /// Get this variable's link name.
97    pub fn link_name(&self) -> Option<&str> {
98        self.link_name.as_deref()
99    }
100}
101
102impl DotAttributes for Var {
103    fn dot_attributes<W>(
104        &self,
105        _ctx: &BindgenContext,
106        out: &mut W,
107    ) -> io::Result<()>
108    where
109        W: io::Write,
110    {
111        if self.is_const {
112            writeln!(out, "<tr><td>const</td><td>true</td></tr>")?;
113        }
114
115        if let Some(ref mangled) = self.mangled_name {
116            writeln!(out, "<tr><td>mangled name</td><td>{mangled}</td></tr>")?;
117        }
118
119        Ok(())
120    }
121}
122
123fn default_macro_constant_type(ctx: &BindgenContext, value: i64) -> IntKind {
124    if value < 0 ||
125        ctx.options().default_macro_constant_type ==
126            MacroTypeVariation::Signed
127    {
128        if value < i64::from(i32::MIN) || value > i64::from(i32::MAX) {
129            IntKind::I64
130        } else if !ctx.options().fit_macro_constants ||
131            value < i64::from(i16::MIN) ||
132            value > i64::from(i16::MAX)
133        {
134            IntKind::I32
135        } else if value < i64::from(i8::MIN) || value > i64::from(i8::MAX) {
136            IntKind::I16
137        } else {
138            IntKind::I8
139        }
140    } else if value > i64::from(u32::MAX) {
141        IntKind::U64
142    } else if !ctx.options().fit_macro_constants || value > i64::from(u16::MAX)
143    {
144        IntKind::U32
145    } else if value > i64::from(u8::MAX) {
146        IntKind::U16
147    } else {
148        IntKind::U8
149    }
150}
151
152/// Parses tokens from a `CXCursor_MacroDefinition` pointing into a function-like
153/// macro, and calls the `func_macro` callback.
154fn handle_function_macro(
155    cursor: &clang::Cursor,
156    callbacks: &dyn crate::callbacks::ParseCallbacks,
157) {
158    let is_closing_paren = |t: &ClangToken| {
159        // Test cheap token kind before comparing exact spellings.
160        t.kind == clang_sys::CXToken_Punctuation && t.spelling() == b")"
161    };
162    let tokens: Vec<_> = cursor.tokens().iter().collect();
163    if let Some(boundary) = tokens.iter().position(is_closing_paren) {
164        let mut spelled = tokens.iter().map(ClangToken::spelling);
165        // Add 1, to convert index to length.
166        let left = spelled.by_ref().take(boundary + 1);
167        let left = left.collect::<Vec<_>>().concat();
168        if let Ok(left) = String::from_utf8(left) {
169            let right: Vec<_> = spelled.collect();
170            callbacks.func_macro(&left, &right);
171        }
172    }
173}
174
175impl ClangSubItemParser for Var {
176    fn parse(
177        cursor: clang::Cursor,
178        ctx: &mut BindgenContext,
179    ) -> Result<ParseResult<Self>, ParseError> {
180        use cexpr::expr::EvalResult;
181        use cexpr::literal::CChar;
182        use clang_sys::*;
183        match cursor.kind() {
184            CXCursor_MacroDefinition => {
185                for callbacks in &ctx.options().parse_callbacks {
186                    match callbacks.will_parse_macro(&cursor.spelling()) {
187                        MacroParsingBehavior::Ignore => {
188                            return Err(ParseError::Continue);
189                        }
190                        MacroParsingBehavior::Default => {}
191                    }
192
193                    if cursor.is_macro_function_like() {
194                        handle_function_macro(&cursor, callbacks.as_ref());
195                        // We handled the macro, skip macro processing below.
196                        return Err(ParseError::Continue);
197                    }
198                }
199
200                let value = parse_macro(ctx, &cursor);
201
202                let Some((id, value)) = value else {
203                    return Err(ParseError::Continue);
204                };
205
206                assert!(!id.is_empty(), "Empty macro name?");
207
208                let previously_defined = ctx.parsed_macro(&id);
209
210                // NB: It's important to "note" the macro even if the result is
211                // not an integer, otherwise we might loose other kind of
212                // derived macros.
213                ctx.note_parsed_macro(id.clone(), value.clone());
214
215                if previously_defined {
216                    let name = String::from_utf8(id).unwrap();
217                    duplicated_macro_diagnostic(&name, cursor.location(), ctx);
218                    return Err(ParseError::Continue);
219                }
220
221                // NOTE: Unwrapping, here and above, is safe, because the
222                // identifier of a token comes straight from clang, and we
223                // enforce utf8 there, so we should have already panicked at
224                // this point.
225                let name = String::from_utf8(id).unwrap();
226                let (type_kind, val) = match value {
227                    EvalResult::Invalid => return Err(ParseError::Continue),
228                    EvalResult::Float(f) => {
229                        (TypeKind::Float(FloatKind::Double), VarType::Float(f))
230                    }
231                    EvalResult::Char(c) => {
232                        let c = match c {
233                            CChar::Char(c) => {
234                                assert_eq!(c.len_utf8(), 1);
235                                c as u8
236                            }
237                            CChar::Raw(c) => {
238                                assert!(c <= u64::from(u8::MAX));
239                                c as u8
240                            }
241                        };
242
243                        (TypeKind::Int(IntKind::U8), VarType::Char(c))
244                    }
245                    EvalResult::Str(val) => {
246                        let char_ty = Item::builtin_type(
247                            TypeKind::Int(IntKind::U8),
248                            true,
249                            ctx,
250                        );
251                        for callbacks in &ctx.options().parse_callbacks {
252                            callbacks.str_macro(&name, &val);
253                        }
254                        (TypeKind::Pointer(char_ty), VarType::String(val))
255                    }
256                    EvalResult::Int(Wrapping(value)) => {
257                        let kind = ctx
258                            .options()
259                            .last_callback(|c| c.int_macro(&name, value))
260                            .unwrap_or_else(|| {
261                                default_macro_constant_type(ctx, value)
262                            });
263
264                        (TypeKind::Int(kind), VarType::Int(value))
265                    }
266                };
267
268                let ty = Item::builtin_type(type_kind, true, ctx);
269
270                Ok(ParseResult::New(
271                    Var::new(name, None, None, ty, Some(val), true),
272                    Some(cursor),
273                ))
274            }
275            CXCursor_VarDecl => {
276                let mut name = cursor.spelling();
277                if cursor.linkage() == CXLinkage_External {
278                    if let Some(nm) = ctx.options().last_callback(|callbacks| {
279                        callbacks.generated_name_override(ItemInfo {
280                            name: name.as_str(),
281                            kind: ItemKind::Var,
282                        })
283                    }) {
284                        name = nm;
285                    }
286                }
287                // No more changes to name
288                let name = name;
289
290                if name.is_empty() {
291                    warn!("Empty constant name?");
292                    return Err(ParseError::Continue);
293                }
294
295                let link_name = ctx.options().last_callback(|callbacks| {
296                    callbacks.generated_link_name_override(ItemInfo {
297                        name: name.as_str(),
298                        kind: ItemKind::Var,
299                    })
300                });
301
302                let ty = cursor.cur_type();
303
304                // TODO(emilio): do we have to special-case constant arrays in
305                // some other places?
306                let is_const = ty.is_const() ||
307                    ([CXType_ConstantArray, CXType_IncompleteArray]
308                        .contains(&ty.kind()) &&
309                        ty.elem_type()
310                            .is_some_and(|element| element.is_const()));
311
312                let ty = match Item::from_ty(&ty, cursor, None, ctx) {
313                    Ok(ty) => ty,
314                    Err(e) => {
315                        assert!(
316                            matches!(ty.kind(), CXType_Auto | CXType_Unexposed),
317                            "Couldn't resolve constant type, and it \
318                             wasn't an nondeductible auto type or unexposed \
319                             type: {ty:?}"
320                        );
321                        return Err(e);
322                    }
323                };
324
325                // Note: Ty might not be totally resolved yet, see
326                // tests/headers/inner_const.hpp
327                //
328                // That's fine because in that case we know it's not a literal.
329                let canonical_ty = ctx
330                    .safe_resolve_type(ty)
331                    .and_then(|t| t.safe_canonical_type(ctx));
332
333                let is_integer = canonical_ty.is_some_and(|t| t.is_integer());
334                let is_float = canonical_ty.is_some_and(|t| t.is_float());
335
336                // TODO: We could handle `char` more gracefully.
337                // TODO: Strings, though the lookup is a bit more hard (we need
338                // to look at the canonical type of the pointee too, and check
339                // is char, u8, or i8 I guess).
340                let value = if is_integer {
341                    let TypeKind::Int(kind) = *canonical_ty.unwrap().kind()
342                    else {
343                        unreachable!()
344                    };
345
346                    let mut val = cursor.evaluate().and_then(|v| v.as_int());
347                    if val.is_none() || !kind.signedness_matches(val.unwrap()) {
348                        val = get_integer_literal_from_cursor(&cursor);
349                    }
350
351                    val.map(|val| {
352                        if kind == IntKind::Bool {
353                            VarType::Bool(val != 0)
354                        } else {
355                            VarType::Int(val)
356                        }
357                    })
358                } else if is_float {
359                    cursor
360                        .evaluate()
361                        .and_then(|v| v.as_double())
362                        .map(VarType::Float)
363                } else {
364                    cursor
365                        .evaluate()
366                        .and_then(|v| v.as_literal_string())
367                        .map(VarType::String)
368                };
369
370                let mangling = cursor_mangling(ctx, &cursor);
371                let var =
372                    Var::new(name, mangling, link_name, ty, value, is_const);
373
374                Ok(ParseResult::New(var, Some(cursor)))
375            }
376            _ => {
377                /* TODO */
378                Err(ParseError::Continue)
379            }
380        }
381    }
382}
383
384/// This function uses a [`FallbackTranslationUnit`][clang::FallbackTranslationUnit] to parse each
385/// macro that cannot be parsed by the normal bindgen process for `#define`s.
386///
387/// To construct the [`FallbackTranslationUnit`][clang::FallbackTranslationUnit], first precompiled
388/// headers are generated for all input headers. An empty temporary `.c` file is generated to pass
389/// to the translation unit. On the evaluation of each macro, a [`String`] is generated with the
390/// new contents of the empty file and passed in for reparsing. The precompiled headers and
391/// preservation of the [`FallbackTranslationUnit`][clang::FallbackTranslationUnit] across macro
392/// evaluations are both optimizations that have significantly improved the performance.
393fn parse_macro_clang_fallback(
394    ctx: &mut BindgenContext,
395    cursor: &clang::Cursor,
396) -> Option<(Vec<u8>, cexpr::expr::EvalResult)> {
397    if !ctx.options().clang_macro_fallback {
398        return None;
399    }
400
401    let ftu = ctx.try_ensure_fallback_translation_unit()?;
402    let contents = format!("int main() {{ {}; }}", cursor.spelling());
403    ftu.reparse(&contents).ok()?;
404    // Children of root node of AST
405    let root_children = ftu.translation_unit().cursor().collect_children();
406    // Last child in root is function declaration
407    // Should be FunctionDecl
408    let main_func = root_children.last()?;
409    // Children should all be statements in function declaration
410    let all_stmts = main_func.collect_children();
411    // First child in all_stmts should be the statement containing the macro to evaluate
412    // Should be CompoundStmt
413    let macro_stmt = all_stmts.first()?;
414    // Children should all be expressions from the compound statement
415    let paren_exprs = macro_stmt.collect_children();
416    // First child in all_exprs is the expression utilizing the given macro to be evaluated
417    // Should  be ParenExpr
418    let paren = paren_exprs.first()?;
419
420    Some((
421        cursor.spelling().into_bytes(),
422        cexpr::expr::EvalResult::Int(Wrapping(paren.evaluate()?.as_int()?)),
423    ))
424}
425
426/// Try and parse a macro using all the macros parsed until now.
427fn parse_macro(
428    ctx: &mut BindgenContext,
429    cursor: &clang::Cursor,
430) -> Option<(Vec<u8>, cexpr::expr::EvalResult)> {
431    use cexpr::expr;
432
433    let cexpr_tokens = cursor.cexpr_tokens();
434
435    let parser = expr::IdentifierParser::new(ctx.parsed_macros());
436
437    match parser.macro_definition(&cexpr_tokens) {
438        Ok((_, (id, val))) => Some((id.into(), val)),
439        _ => parse_macro_clang_fallback(ctx, cursor),
440    }
441}
442
443fn parse_int_literal_tokens(cursor: &clang::Cursor) -> Option<i64> {
444    use cexpr::expr;
445    use cexpr::expr::EvalResult;
446
447    let cexpr_tokens = cursor.cexpr_tokens();
448
449    // TODO(emilio): We can try to parse other kinds of literals.
450    match expr::expr(&cexpr_tokens) {
451        Ok((_, EvalResult::Int(Wrapping(val)))) => Some(val),
452        _ => None,
453    }
454}
455
456fn get_integer_literal_from_cursor(cursor: &clang::Cursor) -> Option<i64> {
457    use clang_sys::*;
458    let mut value = None;
459    cursor.visit(|c| {
460        match c.kind() {
461            CXCursor_IntegerLiteral | CXCursor_UnaryOperator => {
462                value = parse_int_literal_tokens(&c);
463            }
464            CXCursor_UnexposedExpr => {
465                value = get_integer_literal_from_cursor(&c);
466            }
467            _ => (),
468        }
469        if value.is_some() {
470            CXChildVisit_Break
471        } else {
472            CXChildVisit_Continue
473        }
474    });
475    value
476}
477
478fn duplicated_macro_diagnostic(
479    macro_name: &str,
480    _location: clang::SourceLocation,
481    _ctx: &BindgenContext,
482) {
483    warn!("Duplicated macro definition: {macro_name}");
484
485    #[cfg(feature = "experimental")]
486    // FIXME (pvdrz & amanjeev): This diagnostic message shows way too often to be actually
487    // useful. We have to change the logic where this function is called to be able to emit this
488    // message only when the duplication is an actual issue.
489    //
490    // If I understood correctly, `bindgen` ignores all `#undef` directives. Meaning that this:
491    // ```c
492    // #define FOO 1
493    // #undef FOO
494    // #define FOO 2
495    // ```
496    //
497    // Will trigger this message even though there's nothing wrong with it.
498    #[allow(clippy::overly_complex_bool_expr)]
499    if false && _ctx.options().emit_diagnostics {
500        use crate::diagnostics::{get_line, Diagnostic, Level, Slice};
501        use std::borrow::Cow;
502
503        let mut slice = Slice::default();
504        let mut source = Cow::from(macro_name);
505
506        let (file, line, col, _) = _location.location();
507        if let Some(filename) = file.name() {
508            if let Ok(Some(code)) = get_line(&filename, line) {
509                source = code.into();
510            }
511            slice.with_location(filename, line, col);
512        }
513
514        slice.with_source(source);
515
516        Diagnostic::default()
517            .with_title("Duplicated macro definition.", Level::Warning)
518            .add_slice(slice)
519            .add_annotation("This macro had a duplicate.", Level::Note)
520            .display();
521    }
522}
bindgen/ir/var.rs

bindgen/ir/
var.rs
