From 95bcd17705af8e85df9893025608f2ea4f57bf37 Mon Sep 17 00:00:00 2001 From: Micah Elizabeth Scott Date: Tue, 25 Jul 2023 19:28:06 -0700 Subject: 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 --- doc/HACKING/Rust.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 doc/HACKING/Rust.md (limited to 'doc') diff --git a/doc/HACKING/Rust.md b/doc/HACKING/Rust.md new file mode 100644 index 0000000000..a52807e540 --- /dev/null +++ b/doc/HACKING/Rust.md @@ -0,0 +1,43 @@ +# Rust support in C Tor + +The [Arti project](https://gitlab.torproject.org/tpo/core/arti) 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. -- cgit v1.2.3-54-g00ecf