tor/doc/HACKING/Rust.md

Rust support in C Tor

The Arti project is the team's ongoing effort to write a pure-Rust implementation of Tor.

Arti is not yet feature complete but it's in active development. That's where you want to go if you're interested in Tor and Rust together.

This document describes something with niche interest: the C implementation of Tor can expose Rust crates which are used for internal testing, benchmarking, comparison, fuzzing, and so on. This could be useful for comparing the C implementation against new Rust implementations, or for simply using Rust tooling for writing tests against C.

Crates

Right now we are only using this mechanism for one crate:

• tor-c-equix -- Wraps the src/ext/equix module, containing Equi-X and HashX algorithms.

Stability

This is not a stable API and we have no plans to develop a stable Rust interface to the C implementation of Tor.

Files

We use only a few of the standard Rust file types in order to build our wrapper crates. Here's a summary:

• Cargo.toml in the repository root defines a Cargo workspace. It will list all subdirectories that contain crates with their own Cargo.toml.
• A per-crate Cargo.toml defines metadata and dependencies. These crates should all be marked publish = false.
• build.rs implements a simple build system that does not interact with autotools. It uses the cc and bindgen crates to get from .c/.h files to a static library and matching auto-generated bindings. Prefer to include bindgen wrapper headers inline within build.rs instead of adding .h files that are only used by the Rust bindings.
• lib.rs publishes the low-level ffi interface produced with cc and bindgen. This is also where we can add any wrappers or additions we want for making the Rust API more convenient.