mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-09-20 04:56:21 +02:00
95bcd17705
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>
44 lines
1.8 KiB
Markdown
44 lines
1.8 KiB
Markdown
# 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.
|