| Lukasz Anforowicz | 7166d0e | 2023-03-02 16:50:17 -0800 | [diff] [blame] | 1 | # Reproducible builds |
| 2 | |
| 3 | Crubit can emit bindings for Rust or C++ libraries so that they can be called |
| 4 | from the other language, but these bindings require strict ABI compatibility. To |
| 5 | accomplish this, Crubit uses `clang` and `rustc` as libraries to discover the |
| 6 | public APIs of the wrapped libraries, and the ABI that they expose when built |
| 7 | (e.g. their function calling conventions, and the memory layout of their |
| 8 | structs). |
| 9 | |
| 10 | To ensure that the generated bindings are ABI-compatible with the built |
| 11 | libraries, Crubit needs to see exactly what the real compiler sees: |
| 12 | |
| 13 | * Build the wrapped libraries using the same version of the compiler that |
| 14 | Crubit uses, with the same compilation settings (flags, environment |
| 15 | variables, etc.). For example, an extra `-DSOME_DEFINE` or a new version of |
| 16 | the compiler can completely change the ABI, or even the API, of a given |
| 17 | library. If the compiler sees it, but Crubit does not, the generated |
| 18 | bindings will be incorrect. |
| 19 | * Do not store Crubit outputs (*e.g.* `..._cc_api.h` or `..._rs_api.rs`) in a |
| 20 | source code repository, as they *will* go out of date. Crubit comes with |
| 21 | Bazel integration support to invoke it at build time. |
| 22 | * The ABI must be deterministic and reproducible (*i.e.* depend only on |
| 23 | compilation settings, the compiler version, and the wrapped libraries |
| 24 | themselves). For example, the |
| 25 | [`-Zrandomize-layout`](https://github.com/rust-lang/compiler-team/issues/457) |
| 26 | flag cannot be used without a fixed seed. |
