Commit e87a2759 authored by Nick Mathewson's avatar Nick Mathewson
Browse files

Merge branch 'maint-0.3.3'

parents 62c88a60 d489e484
......@@ -9,17 +9,19 @@ Please read or review our documentation on Rust coding standards
(`.../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 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.
[the Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html). 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
-----------------------------
......@@ -33,14 +35,15 @@ Rust immediately, without waiting for anything to install, there is
**Advanced resources**
If you're interested in playing with various Rust compilers and viewing a very
nicely displayed output of the generated assembly, there is
If you're interested in playing with various Rust compilers and viewing
a very nicely displayed output of the generated assembly, there is
[the Godbolt compiler explorer](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
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).
For learning more about FFI and Rust, see Jake Goulding's
......@@ -49,10 +52,10 @@ For learning more about FFI and Rust, see Jake Goulding's
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 specify where to
fetch Rust dependencies, as we allow for either fetching dependencies from Cargo
or specifying a local directory.
You will need to run the `configure` script with the `--enable-rust`
flag to explicitly build with Rust. Additionally, you will need to
specify where to fetch Rust dependencies, as we allow for either
fetching dependencies from Cargo or specifying a local directory.
**Fetch dependencies from Cargo**
......@@ -65,21 +68,22 @@ You'll need the following Rust dependencies (as of this writing):
libc==0.2.22
We vendor our Rust dependencies in a separate repo using
[cargo-vendor](https://github.com/alexcrichton/cargo-vendor). To use them, do:
[cargo-vendor](https://github.com/alexcrichton/cargo-vendor). To use
them, do:
git submodule init
git submodule update
To specify the local directory containing the dependencies, (assuming you are in
the top level of the repository) configure tor with:
To specify the local directory containing the dependencies, (assuming
you are in the top level of the repository) configure tor with:
TOR_RUST_DEPENDENCIES='path_to_dependencies_directory' ./configure --enable-rust
(Note that RUST_DEPENDENCIES must be the full path to the directory; it cannot
be relative.)
(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 topmost
directory of the repository, this would be:
Assuming you used the above `git submodule` commands and you're in the
topmost directory of the repository, this would be:
TOR_RUST_DEPENDENCIES=`pwd`/src/ext/rust/crates ./configure --enable-rust
......@@ -87,19 +91,20 @@ directory of the repository, this would be:
Identifying which modules to rewrite
======================================
The places in the Tor codebase that are good candidates for porting to Rust are:
The places in the Tor codebase that are good candidates for porting to
Rust are:
1. loosely coupled to other Tor submodules,
2. have high test coverage, and
3. would benefit from being implemented in a memory safe language.
Help in either identifying places such as this, or working to improve existing
areas of the C codebase by adding regression tests and simplifying dependencies,
would be really helpful.
Help in either identifying places such as this, or working to improve
existing areas of the C codebase by adding regression tests and
simplifying dependencies, would be really helpful.
Furthermore, as submodules in C are implemented in Rust, this is a good
opportunity to refactor, add more tests, and split modules into smaller areas of
responsibility.
opportunity to refactor, add more tests, and split modules into smaller
areas of responsibility.
A good first step is to build a module-level callgraph to understand how
interconnected your target module is.
......@@ -117,21 +122,22 @@ the module calls. Modules which call fewer other modules are better targets.
Strive to change the C API as little as possible.
We are currently targeting 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.
We are currently targeting 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.
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:
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>`
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.
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
-----------------------------------------------
......@@ -153,8 +159,9 @@ dependency of other Rust modules):
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 crate to
the `crates` variable! This will ensure that `cargo test` is run on your crate.
Be sure to edit `.../tor/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.
Configure Tor's build system to build with Rust enabled:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment