Add codegen/types docs (#370)

This doesn't have all the info updated. For example enums are no more
transalted as enum in Rust, I plan to update that in a future PR. For
the moment I would like to get the core of codegen/types merged, then I
will make the appropiate edits.

Author: lucic71

.github/workflows/docs.yml

@@ -16,7 +16,9 @@ jobs:
     steps:
       - uses: actions/checkout@v7
       - name: Install mdbook
-        run: cargo install mdbook
+        run: cargo install mdbook mdbook-mermaid
+      - name: Install mermaid assets
+        run: mdbook-mermaid install docs
       - name: Build book
         run: mdbook build docs
       - uses: actions/upload-pages-artifact@v5

cpp2rust/converter/converter.cpp

@@ -1525,24 +1525,6 @@ const clang::Expr *Converter::GetParentExpr(const clang::Expr *expr) {
   return nullptr;
 }
 
-bool Converter::IsSubExprOf(const clang::Expr *sub_expr,
-                            const clang::Expr *parent_expr) {
-  if (sub_expr == nullptr || parent_expr == nullptr)
-    return false;
-
-  if (parent_expr == sub_expr)
-    return true;
-
-  for (auto *child : parent_expr->children()) {
-    if (auto *child_expr = llvm::dyn_cast<clang::Expr>(child)) {
-      if (IsSubExprOf(sub_expr, child_expr))
-        return true;
-    }
-  }
-
-  return false;
-}
-
 bool Converter::GetFmtArg(clang::Expr *arg, std::string &fmt,
                           std::string &fmt_args, const char *&fmt_trait,
                           std::string &fmt_width) {

cpp2rust/converter/converter.h

@@ -442,7 +442,6 @@ class Converter : public clang::RecursiveASTVisitor<Converter> {
 
 protected:
   const clang::Expr *GetParentExpr(const clang::Expr *expr);
-  bool IsSubExprOf(const clang::Expr *sub_expr, const clang::Expr *parent_expr);
 
 #define StrCat(...) _StrCat(__FUNCTION__, __LINE__, __VA_ARGS__)
 

docs/.gitignore

@@ -1 +1,3 @@
 book
+mermaid.min.js
+mermaid-init.js

docs/book.toml

@@ -10,7 +10,11 @@ create-missing = false
 [output.html]
 git-repository-url = "https://github.com/cpp2rust/cpp2rust"
 edit-url-template = "https://github.com/cpp2rust/cpp2rust/edit/master/docs/{path}"
+additional-js = ["mermaid.min.js", "mermaid-init.js"]
 
 [output.html.fold]
 enable = true
 level = 1
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"

docs/src/SUMMARY.md

@@ -40,8 +40,18 @@
 # Code Generation
 
 - [Overview](./codegen/overview.md)
-- [Pointers and References](./codegen/pointers.md)
-- [Unions](./codegen/unions.md)
-- [Global Variables](./codegen/globals.md)
-- [Temporary Materialization](./codegen/temporaries.md)
-- [Translation Plugins](./codegen/plugins.md)
+- [The Translation Pipeline](./codegen/pipeline.md)
+- [Types](./codegen/types.md)
+  - [Type Mappings](./codegen/types/mappings.md)
+  - [Boxing](./codegen/types/boxing.md)
+  - [Naming](./codegen/types/naming.md)
+  - [Classes and Structs](./codegen/types/classes.md)
+  - [Traits](./codegen/types/traits.md)
+  - [Enums](./codegen/types/enums.md)
+  - [Unions](./codegen/types/unions.md)
+  - [Bit-fields](./codegen/types/bitfields.md)
+  - [Pointers and References](./codegen/types/pointers.md)
+  - [Casts](./codegen/types/casts.md)
+  - [Function Pointers](./codegen/types/fn-pointers.md)
+  - [Lambdas](./codegen/types/lambdas.md)
+  - [Special-cased Library Types](./codegen/types/special-types.md)

docs/src/codegen/pipeline.md

@@ -0,0 +1,55 @@
+# The Translation Pipeline
+
+<style>pre.mermaid { text-align: center; }</style>
+
+```mermaid
+flowchart TD
+    driver["<b>cpp2rust</b><br/><code>cpp2rust/cpp2rust.cpp</code>"]
+    lib["<b>TranspileSrc / TranspileDir</b><br/><code>cpp2rust/cpp2rust_lib.cpp</code>"]
+    action["<b>FrontendAction, ASTConsumer</b><br/><code>cpp2rust/ast_consumer.cpp</code>"]
+    factory["<b>CreateConverter</b><br/><code>cpp2rust/converter/factory.cpp</code>"]
+    mapper["<b>Mapper::LoadTranslationRules</b><br/><code>cpp2rust/converter/mapper.cpp</code>"]
+    conv["<b>Converter / ConverterRefCount</b><br/><code>cpp2rust/converter/</code>"]
+    out["<b>output file</b><br/>rustfmt"]
+    driver -->|"source or compilation database"| lib
+    lib -->|"one per translation unit"| action
+    action --> factory
+    factory -.->|"first call only"| mapper
+    factory --> conv
+    conv -->|"rs_code"| out
+```
+
+## The stages
+
+1. `cpp2rust` (`cpp2rust/cpp2rust.cpp`) parses the flags, resolves the rules
+   directory (see
+   [Loading and Matching](../rules/loading.md#finding-the-rules-directory)), and
+   calls `TranspileSrc` for `--file` or `TranspileDir` for `--dir`.
+2. `TranspileSrc` / `TranspileDir` (`cpp2rust/cpp2rust_lib.cpp`) run clang
+   tooling over the source or over every file in `compile_commands.json`, with
+   one `FrontendAction` per translation unit.
+3. `ASTConsumer::HandleTranslationUnit` calls `CreateConverter`
+   (`cpp2rust/converter/factory.cpp`), which loads the translation rules on its
+   first call and constructs a `Converter` (`--model=unsafe`) or a
+   `ConverterRefCount` (`--model=refcount`).
+4. The converter emits the file preamble if this is the first unit, then
+   traverses the unit and appends Rust text to `rs_code`.
+5. The driver writes `rs_code` to the `-o` path and runs `rustfmt` on it.
+
+## Gotchas
+
+- Every unit is parsed with the platform flags from
+  `cpp2rust/compat/platform_flags.h`, which put the
+  [compat headers](../rules/compat.md) ahead of the system headers and set
+  `-D_FORTIFY_SOURCE=0`, so macro-heavy libc APIs reach the converter as plain
+  function calls.
+- In `--dir` mode `__FILE__` is redefined to the file's basename, so the
+  generated code does not embed the absolute paths of the build machine.
+- Rules are loaded once per process, and the file preamble is emitted once, by
+  the first unit; the bookkeeping that spans units (which declarations and
+  records have already been emitted) is kept in `static` members of `Converter`.
+- After the last unit, `Converter::EmitOpaqueRecords` appends `pub struct Name;`
+  for every record type that was referenced but never defined, so types only
+  used behind pointers still compile.
+- A failing `rustfmt` is reported as an error, but the unformatted file stays on
+  disk for inspection.

docs/src/codegen/types.md

@@ -0,0 +1,52 @@
+# Types
+
+Every place the converter prints a type goes through `Convert(QualType)`. It
+first asks the [type rules](../rules/writing-rules.md) for a mapping, so library
+types and typedef names such as `size_t` are resolved by rules, and only falls
+back to the `Visit*Type` methods for the built-in and user-defined types
+described here.
+
+Given
+
+```cpp
+struct Item {
+  int id;
+  char name[8];
+  std::vector<int> refs;
+};
+
+int count(Item item) { return item.id; }
+```
+
+the unsafe model produces (attributes and trait impls omitted)
+
+```rust
+pub struct Item {
+    pub id: i32,
+    pub name: [libc::c_char; 8],
+    pub refs: Vec<i32>,
+}
+pub unsafe fn count_0(mut item: Item) -> i32 {
+    return item.id;
+}
+```
+
+and the refcount model produces
+
+```rust
+pub struct Item {
+    pub id: Value<i32>,
+    pub name: Value<Box<[u8]>>,
+    pub refs: Value<Vec<i32>>,
+}
+pub fn count_0(item: Item) -> i32 {
+    let item: Value<Item> = Rc::new(RefCell::new(item));
+    return *(*item.borrow()).id.borrow();
+}
+```
+
+Every struct field is boxed in its own `Value<T>` so that a pointer can be taken
+to it. This is set to change: field writes and field addresses through a
+reinterpreted struct pointer go to a temporary and are lost, so fields will
+become plain `T` and `Ptr` will gain a kind that stores the parent struct plus
+an offset ([#309](https://github.com/Cpp2Rust/cpp2rust/issues/309)).

docs/src/codegen/types/bitfields.md

@@ -0,0 +1,13 @@
+# Bit-fields
+
+Bit-fields are not implemented. `VisitFieldDecl` ignores the declared width, so
+a field such as `unsigned flags : 3;` is emitted as a plain `u32` field: the
+struct compiles, but its layout, size, and the wrap-around of the field's value
+differ from C.
+
+> [!WARNING]
+>
+> Code that relies on bit-field layout or width (packing several fields into one
+> word, `sizeof` on such a struct, storing a value wider than the field)
+> translates silently to something else
+> ([#312](https://github.com/Cpp2Rust/cpp2rust/issues/312)).

docs/src/codegen/types/boxing.md

@@ -0,0 +1,52 @@
+# Boxing
+
+In the refcount model a variable is boxed: its type `T` is wrapped in
+`Value<T>`, an alias for `Rc<RefCell<T>>` (see
+[Reference Counting](../../runtime/rc.md)). Without the box, taking the address
+of a variable would need a Rust reference, and arbitrary C++ aliasing cannot be
+expressed with references.
+
+Not every type position is boxed. `ConverterRefCount` keeps a stack of
+conversion kinds, [`conversion_kind_`](../internals/state.md), and the construct
+that owns the type pushes one before printing it:
+
+- `FullRefCount`: pushed by variable and field declarations; `Convert(QualType)`
+  wraps the result in `Value<...>`.
+- `Unboxed`: pushed by parameter lists, return types, and record names; the bare
+  type is printed.
+- `Ptr`: pushed by a pointer type for its pointee; also printed bare.
+
+The result by position:
+
+| Position                                    | `int`        | `Item`        | `int[3]`             |
+| ------------------------------------------- | ------------ | ------------- | -------------------- |
+| local variable, struct field, global        | `Value<i32>` | `Value<Item>` | `Value<Box<[i32]>>`  |
+| function parameter, return type             | `i32`        | `Item`        | decays to `Ptr<i32>` |
+| pointee of `Ptr<T>`, element of a container | `i32`        | `Item`        | `Box<[i32]>`         |
+
+Parameters arrive unboxed and are re-boxed by the function preamble; return
+values are unboxed:
+
+```cpp
+int add(int a, Item item) { return a + item.id; }
+```
+
+```rust
+pub fn add_0(a: i32, item: Item) -> i32 {
+    let a: Value<i32> = Rc::new(RefCell::new(a));
+    let item: Value<Item> = Rc::new(RefCell::new(item));
+    return *a.borrow() + *(*item.borrow()).id.borrow();
+}
+```
+
+C++ passes arguments to functions by copy, so signatures stay unboxed; boxing
+the copy on entry then lets the body treat parameters exactly like local
+variables. The preamble skips reference parameters, which are a `Ptr<T>` and
+never boxed.
+
+Nested containers, library ones and arrays alike, box each level except the
+innermost, so that every inner container can be borrowed and mutated on its own,
+and a pointer can be taken to it. The boxing is written into the type rules
+themselves: `std::vector<std::vector<int>>` maps to `Vec<Value<Vec<i32>>>`, and
+the `carray` rules map `int a[2][2]` to `Box<[Value<Box<[i32]>>]>`, both before
+the outer `Value<...>` of the declaration is added.