[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[tor-commits] [tor/maint-0.3.3] Wrap GettingStartedRust.md to 72 columns.
commit d2bdb54d37706b2322b1a1fa0a85c72cf72acd9e
Author: Nick Mathewson <nickm@xxxxxxxxxxxxxx>
Date: Wed Feb 21 11:55:07 2018 -0500
Wrap GettingStartedRust.md to 72 columns.
---
doc/HACKING/GettingStartedRust.md | 95 +++++++++++++++++++++------------------
1 file changed, 51 insertions(+), 44 deletions(-)
diff --git a/doc/HACKING/GettingStartedRust.md b/doc/HACKING/GettingStartedRust.md
index 3f9cf82ea..87b41b5e2 100644
--- a/doc/HACKING/GettingStartedRust.md
+++ b/doc/HACKING/GettingStartedRust.md
@@ -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 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:
_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits