wiki:RustInTor/Hacking

Version 4 (modified by isis, 5 months ago) (diff)

--

Hacking on Rust in Tor

Getting Started

Please read or review our documentation on our documentation on Rust in Tor before doing anything.

Please also read the Rust Code of Conduct. We aim to follow the good example set by the Rust community and be excellent to one another. Let's be careful with each other, so we can be memory-safe together!

Next, please contact us before rewriting anything! Rust in Tor is still an experiment. It is an experiment that we very much want to see succeed, so we're going slowly and carefully. For the moment, it's also a completely volunteer-driven effort: while many, if not most, of us are paid to work on Tor, we are not yet funded to write Rust code for Tor. Please be patient with the other people who are working on getting more Rust code into Tor, because they are graciously donating their free time to contribute to this effort.

Resources for learning Rust

Beginning resources

The primary resource for learning Rust is The Book: https://doc.rust-lang.org/book/. If you'd like to start writing Rust immediately, without waiting for anything to install, there is https://play.rust-lang.org/.

Advanced

If you're interested in playing with various Rust compilers and viewing a very nicely displayed output of the generated assembly, there is https://rust.godbolt.org/

For learning how to write "unsafe" Rust, read The Rustonomicon: https://doc.rust-lang.org/nomicon/

For learning everything you ever wanted to know about Rust macros, there is The Little Book of Rust Macros: https://danielkeep.github.io/tlborm/book/index.html

Identifying which modules to rewrite

A good first step is to build a module-level callgraph to understand how interconnected your target module is.

git clone https://git.torproject.org/user/nickm/calltool.git
cd tor
CFLAGS=0 ./configure
../calltool/src/main.py module_callgraph

The output will tell you each module name, along with a set of every module that the module calls. Modules which call fewer other modules are better targets.

Writing your Rust module

Strive to change the C API as little as possible.

We are currently targetting Rust nightly, for now. We expect this to change moving forward, as we understand more about which nightly features we need. It is on our TODO list to try to cultivate good standing with various distro maintainers of rustc and cargo, in order to ensure that whatever version we solidify on is readily available.

Adding your Rust module to Tor's build system

  1. Your translation of the C module should live in its own crate(s) in the .../tor/src/rust/ directory.
  2. Add your crate to .../tor/src/rust/Cargo.toml, in the [workspace.members] section.
  3. Append your crate's static library to the rust_ldadd definition (underneath if USE_RUST) in .../tor/Makefile.am.

How to test your Rust code

Everything should be tested full stop. Even non-public functionality.

Tor's unittests in C should be run:

make test

Tor's integration tests should pass:

make test-stem

Tests inside your crate should pass:

cargo test # inside your rust module