doc/HACKING/GettingStartedRust.md

   1 # Hacking on Rust in Tor
   2
   3 ## Getting Started
   4
   5 Please read or review our documentation on Rust coding standards
   6 (`doc/HACKING/CodingStandardsRust.md`) before doing anything.
   7
   8 Please also read
   9 [the Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html). We
  10 aim to follow the good example set by the Rust community and be
  11 excellent to one another.  Let's be careful with each other, so we can
  12 be memory-safe together!
  13
  14 Next, please contact us before rewriting anything!  Rust in Tor is still
  15 an experiment.  It is an experiment that we very much want to see
  16 succeed, so we're going slowly and carefully.  For the moment, it's also
  17 a completely volunteer-driven effort: while many, if not most, of us are
  18 paid to work on Tor, we are not yet funded to write Rust code for Tor.
  19 Please be patient with the other people who are working on getting more
  20 Rust code into Tor, because they are graciously donating their free time
  21 to contribute to this effort.
  22
  23 ## Resources for learning Rust
  24
  25 **Beginning resources**
  26
  27 The primary resource for learning Rust is
  28 [The Book](https://doc.rust-lang.org/book/).  If you'd like to start writing
  29 Rust immediately, without waiting for anything to install, there is
  30 [an interactive browser-based playground](https://play.rust-lang.org/).
  31
  32 **Advanced resources**
  33
  34 If you're interested in playing with various Rust compilers and viewing
  35 a very nicely displayed output of the generated assembly, there is
  36 [the Godbolt compiler explorer](https://rust.godbolt.org/)
  37
  38 For learning how to write unsafe Rust, read
  39 [The Rustonomicon](https://doc.rust-lang.org/nomicon/).
  40
  41 For learning everything you ever wanted to know about Rust macros, there
  42 is
  43 [The Little Book of Rust Macros](https://danielkeep.github.io/tlborm/book/index.html).
  44
  45 For learning more about FFI and Rust, see Jake Goulding's
  46 [Rust FFI Omnibus](https://jakegoulding.com/rust-ffi-omnibus/).
  47
  48 ## Compiling Tor with Rust enabled
  49
  50 You will need to run the `configure` script with the `--enable-rust`
  51 flag to explicitly build with Rust. Additionally, you will need to
  52 specify where to fetch Rust dependencies, as we allow for either
  53 fetching dependencies from Cargo or specifying a local directory.
  54
  55 **Fetch dependencies from Cargo**
  56
  57 ```console
  58 $ ./configure --enable-rust --enable-cargo-online-mode
  59 ```
  60
  61 **Using a local dependency cache**
  62
  63 You'll need the following Rust dependencies (as of this writing):
  64
  65     libc==0.2.39
  66
  67 We vendor our Rust dependencies in a separate repo using
  68 [cargo-vendor](https://github.com/alexcrichton/cargo-vendor).  To use
  69 them, do:
  70
  71 ```console
  72 $ git submodule init
  73 $ git submodule update
  74 ```
  75
  76 To specify the local directory containing the dependencies, (assuming
  77 you are in the top level of the repository) configure tor with:
  78
  79 ```console
  80 $ TOR_RUST_DEPENDENCIES='path_to_dependencies_directory' ./configure --enable-rust
  81 ```
  82
  83 (Note that `TOR_RUST_DEPENDENCIES` must be the full path to the directory; it
  84 cannot be relative.)
  85
  86 Assuming you used the above `git submodule` commands and you're in the
  87 topmost directory of the repository, this would be:
  88
  89 ```console
  90 $ TOR_RUST_DEPENDENCIES=`pwd`/src/ext/rust/crates ./configure --enable-rust
  91 ```
  92
  93 ## Identifying which modules to rewrite
  94
  95 The places in the Tor codebase that are good candidates for porting to
  96 Rust are:
  97
  98 1. loosely coupled to other Tor submodules,
  99 2. have high test coverage, and
 100 3. would benefit from being implemented in a memory safe language.
 101
 102 Help in either identifying places such as this, or working to improve
 103 existing areas of the C codebase by adding regression tests and
 104 simplifying dependencies, would be really helpful.
 105
 106 Furthermore, as submodules in C are implemented in Rust, this is a good
 107 opportunity to refactor, add more tests, and split modules into smaller
 108 areas of responsibility.
 109
 110 A good first step is to build a module-level callgraph to understand how
 111 interconnected your target module is.
 112
 113 ```console
 114 $ git clone https://git.torproject.org/user/nickm/calltool.git
 115 $ cd tor
 116 $ CFLAGS=0 ./configure
 117 $ ../calltool/src/main.py module_callgraph
 118 ```
 119
 120 The output will tell you each module name, along with a set of every module that
 121 the module calls.  Modules which call fewer other modules are better targets.
 122
 123 ## Writing your Rust module
 124
 125 Strive to change the C API as little as possible.
 126
 127 We are currently targeting Rust stable. (See `CodingStandardsRust.md` for more
 128 details.)
 129
 130 It is on our TODO list to try to cultivate good
 131 standing with various distro maintainers of `rustc` and `cargo`, in
 132 order to ensure that whatever version we solidify on is readily
 133 available.
 134
 135 If parts of your Rust code needs to stay in sync with C code (such as
 136 handling enums across the FFI boundary), annonotate these places in a
 137 comment structured as follows:
 138
 139   `/// C_RUST_COUPLED: <path_to_file> <name_of_c_object>`
 140
 141 Where `<name_of_c_object>` can be an enum, struct, constant, etc.  Then,
 142 do the same in the C code, to note that rust will need to be changed
 143 when the C does.
 144
 145 ## Adding your Rust module to Tor's build system
 146
 147 0. Your translation of the C module should live in its own crate(s)
 148    in the `src/rust/` directory.
 149 1. Add your crate to `src/rust/Cargo.toml`, in the
 150    `[workspace.members]` section.
 151 2. Add your crate's files to src/rust/include.am
 152
 153 If your crate should be available to C (rather than just being included as a
 154 dependency of other Rust modules):
 155 0. Declare the crate as a dependency of tor_rust in
 156    `src/rust/tor_util/Cargo.toml` and include it in
 157    `src/rust/tor_rust/lib.rs`
 158
 159 ## How to test your Rust code
 160
 161 Everything should be tested full stop.  Even non-public functionality.
 162
 163 Be sure to edit `src/test/test_rust.sh` to add the name of your
 164 crate to the `crates` variable! This will ensure that `cargo test` is
 165 run on your crate.
 166
 167 Configure Tor's build system to build with Rust enabled:
 168
 169 ```console
 170 $ ./configure --enable-fatal-warnings --enable-rust --enable-cargo-online-mode
 171 ```
 172
 173 Tor's test should be run by doing:
 174
 175 ```console
 176 $ make check
 177 ```
 178
 179 Tor's integration tests should also pass:
 180
 181 ```console
 182 $ make test-stem
 183 ```
 184
 185 ## Submitting a patch
 186
 187 Please follow the instructions in `doc/HACKING/GettingStarted.md`.