diff options
Diffstat (limited to 'doc/HACKING/GettingStartedRust.md')
| -rw-r--r-- | doc/HACKING/GettingStartedRust.md | 50 |
1 files changed, 19 insertions, 31 deletions
diff --git a/doc/HACKING/GettingStartedRust.md b/doc/HACKING/GettingStartedRust.md index aa29c097da..af80018f4e 100644 --- a/doc/HACKING/GettingStartedRust.md +++ b/doc/HACKING/GettingStartedRust.md @@ -1,12 +1,9 @@ +# Hacking on Rust in Tor - Hacking on Rust in Tor -======================== - - Getting Started ------------------ +## Getting Started Please read or review our documentation on Rust coding standards -(`.../doc/HACKING/CodingStandardsRust.md`) before doing anything. +(`doc/HACKING/CodingStandardsRust.md`) before doing anything. Please also read [the Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html). We @@ -23,8 +20,7 @@ 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 ------------------------------ +## Resources for learning Rust **Beginning resources** @@ -47,10 +43,9 @@ is [The Little Book of Rust Macros](https://danielkeep.github.io/tlborm/book/index.html). For learning more about FFI and Rust, see Jake Goulding's -[Rust FFI Omnibus](http://jakegoulding.com/rust-ffi-omnibus/). +[Rust FFI Omnibus](https://jakegoulding.com/rust-ffi-omnibus/). - Compiling Tor with Rust enabled ---------------------------------- +## Compiling Tor with Rust enabled You will need to run the `configure` script with the `--enable-rust` flag to explicitly build with Rust. Additionally, you will need to @@ -79,7 +74,7 @@ you are in the top level of the repository) configure tor with: TOR_RUST_DEPENDENCIES='path_to_dependencies_directory' ./configure --enable-rust -(Note that TOR_RUST_DEPENDENCIES must be the full path to the directory; it +(Note that `TOR_RUST_DEPENDENCIES` must be the full path to the directory; it cannot be relative.) Assuming you used the above `git submodule` commands and you're in the @@ -87,9 +82,7 @@ topmost directory of the repository, this would be: TOR_RUST_DEPENDENCIES=`pwd`/src/ext/rust/crates ./configure --enable-rust - - Identifying which modules to rewrite -====================================== +## Identifying which modules to rewrite The places in the Tor codebase that are good candidates for porting to Rust are: @@ -117,12 +110,11 @@ interconnected your target module is. 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 -========================== +## Writing your Rust module Strive to change the C API as little as possible. -We are currently targetting Rust stable. (See CodingStandardsRust.md for more +We are currently targetting Rust stable. (See `CodingStandardsRust.md` for more details.) It is on our TODO list to try to cultivate good @@ -134,19 +126,17 @@ If parts of your Rust code needs to stay in sync with C code (such as handling enums across the FFI boundary), annonotate these places in a comment structured as follows: - /// C_RUST_COUPLED: <path_to_file> `<name_of_c_object>` + `/// C_RUST_COUPLED: <path_to_file> <name_of_c_object>` -Where <name_of_c_object> can be an enum, struct, constant, etc. Then, +Where `<name_of_c_object>` can be an enum, struct, constant, etc. Then, do the same in the C code, to note that rust will need to be changed when the C does. - - Adding your Rust module to Tor's build system ------------------------------------------------ +## Adding your Rust module to Tor's build system 0. Your translation of the C module should live in its own crate(s) - in the `.../tor/src/rust/` directory. -1. Add your crate to `.../tor/src/rust/Cargo.toml`, in the + in the `src/rust/` directory. +1. Add your crate to `src/rust/Cargo.toml`, in the `[workspace.members]` section. 2. Add your crate's files to src/rust/include.am @@ -156,12 +146,11 @@ dependency of other Rust modules): `src/rust/tor_util/Cargo.toml` and include it in `src/rust/tor_rust/lib.rs` - How to test your Rust code ----------------------------- +## How to test your Rust code Everything should be tested full stop. Even non-public functionality. -Be sure to edit `.../tor/src/test/test_rust.sh` to add the name of your +Be sure to edit `src/test/test_rust.sh` to add the name of your crate to the `crates` variable! This will ensure that `cargo test` is run on your crate. @@ -177,7 +166,6 @@ Tor's integration tests should also pass: make test-stem - Submitting a patch -===================== +## Submitting a patch -Please follow the instructions in `.../doc/HACKING/GettingStarted.md`. +Please follow the instructions in `doc/HACKING/GettingStarted.md`. |