doc/HACKING/Rust.md

   1 # Rust support in C Tor
   2
   3 The [Arti project](https://gitlab.torproject.org/tpo/core/arti) is the team's
   4 ongoing effort to write a pure-Rust implementation of Tor.
   5
   6 Arti is not yet feature complete but it's in active development. That's where
   7 you want to go if you're interested in Tor and Rust together.
   8
   9 This document describes something with niche interest: the C implementation of
  10 Tor can expose Rust crates which are used for internal testing, benchmarking,
  11 comparison, fuzzing, and so on. This could be useful for comparing the C
  12 implementation against new Rust implementations, or for simply using Rust
  13 tooling for writing tests against C.
  14
  15 ## Crates
  16
  17 Right now we are only using this mechanism for one crate:
  18
  19 - `tor-c-equix` -- Wraps the `src/ext/equix` module,
  20   containing Equi-X and HashX algorithms.
  21
  22 ## Stability
  23
  24 This is not a stable API and we have no plans to develop a stable Rust interface
  25 to the C implementation of Tor.
  26
  27 ## Files
  28
  29 We use only a few of the standard Rust file types in order to build our
  30 wrapper crates. Here's a summary:
  31
  32 - `Cargo.toml` in the repository root defines a Cargo *workspace*. It will
  33   list all subdirectories that contain crates with their own `Cargo.toml`.
  34 - A per-crate `Cargo.toml` defines metadata and dependencies. These crates
  35   should all be marked `publish = false`.
  36 - `build.rs` implements a simple build system that does not interact with
  37   autotools. It uses the `cc` and `bindgen` crates to get from `.c`/`.h`
  38   files to a static library and matching auto-generated bindings. Prefer to
  39   include bindgen wrapper headers inline within `build.rs` instead of adding
  40   `.h` files that are only used by the Rust bindings.
  41 - `lib.rs` publishes the low-level `ffi` interface produced with `cc` and
  42   `bindgen`. This is also where we can add any wrappers or additions we want
  43   for making the Rust API more convenient.