nihilist/tor
1
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/core/tor.git synced 2024-09-20 04:56:21 +02:00
Code Issues Packages Projects Releases Wiki Activity
main
tor/doc/HACKING/Rust.md
Micah Elizabeth Scott 95bcd17705 Include a basic Rust wrapper for Equi-X and HashX 
The idea behind this is that we may want to start exporting more pieces
of c-tor as Rust crates so that Arti can perform cross compatibility and
comparison testing using Rust tooling.

This turns the 'tor' repo into a Cargo workspace, and adds one crate to
start with: "tor-c-equix", rooted in src/ext/equix. This actually
includes both Equi-X itself and HashX, since there's less overall
duplication if we package these together instead of packaging HashX
separately.

This patch adds a basic safe Rust interface, but doesn't expose any
additional internals for testing purposes.

No changes to the C code here or the normal Tor build system.

Signed-off-by: Micah Elizabeth Scott <beth@torproject.org>
2023-07-26 12:27:15 -07:00

1.8 KiB
Raw Permalink Blame History

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.