internals.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

## Overview

`cbindgen` works in four phases:

1. *Parsing* - Crate information is gathered from `cargo`, and `rust` source files are read using `syn`
1. *Loading* - `syn` AST nodes are converted into an IR of `Item`s that loosely correspond to the C types that will be output
1. *Transformation* - Several passes are run that transform the IR. Some examples:
   - Generic `type` aliases are used to specialize the type they refer to
   - Annotations are transferred from `type` aliases to the item they refer to
   - `Option<&T>` is converted to `*const T`
   - `Option<&mut T>` is converted to `*mut T`
   - Generic paths in struct fields, union variants, and static globals are collected and used to generate monomorphs of the structs or unions they refer to
   - The items are sorted by dependencies and type and unused items are filtered out
1. *Writing* - The IR is pretty printed to a file or `stdout`

## Process Flow

The main interface for `cbindgen` is `bindgen::Builder` which accepts configuration options and either a crate directory to parse or a list of source files.

If a list of source files is given, then `bindgen::Builder` will parse them using `parser::parse_src` which will use `syn` to parse a specific file. No `extern crate` items will be followed for dependencies, but `mod` items will be attempted to be followed.

If a crate directory is given, then `bindgen::Builder` will use `cargo::Cargo` to load a dependency graph from `Cargo.toml`, `Cargo.lock`, and `cargo metadata`. Then `parser::parse_lib` will parse each crate, following `extern crate` items when `ParseConfig::parse_deps` is enabled and the crate is not in the whitelist or blacklist of crates. In addition `bindgen::Parser` may use `cargo expand` on a crate to expand macro definitions.

Once the `syn` nodes are collected by either method, they are given to `bindgen::Parse` which will perform *Loading* by creating a `ir::Item` for each `syn` node as appropriate.

`bindgen::Builder` will then convert the resulting `bindgen::Parse`'s into a `bindgen::Library` which is the driver of all of the *Transformation* passes.

// TODO - Talk more about passes

Then finally the `bindgen::Library` will create a `bindgen::Bindings` which contains the `ir::Item`'s that are ready to be written. The `bindgen::Bindings` can then be written to `stdout` or a specific file.