tor-commits February 2018

tor-commits@lists.torproject.org

19 participants
1579 discussions

[tor/maint-0.3.3] Wrap GettingStartedRust.md to 72 columns.
by nickm＠torproject.org 21 Feb '18

21 Feb '18

commit d2bdb54d37706b2322b1a1fa0a85c72cf72acd9e Author: Nick Mathewson <nickm(a)torproject.org> 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:

1 0

[tor/master] Wrap GettingStartedRust.md to 72 columns.
by nickm＠torproject.org 21 Feb '18

21 Feb '18

1 0

[tor/maint-0.3.3] Fix a variable name in tor-rust-dependencies
by nickm＠torproject.org 21 Feb '18

21 Feb '18

commit d489e4847b1ec30cb127ce6db675e2316c1772e3 Author: Nick Mathewson <nickm(a)torproject.org> Date: Wed Feb 21 11:55:25 2018 -0500 Fix a variable name in tor-rust-dependencies --- doc/HACKING/GettingStartedRust.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/HACKING/GettingStartedRust.md b/doc/HACKING/GettingStartedRust.md index 87b41b5e2..f5914bc87 100644 --- a/doc/HACKING/GettingStartedRust.md +++ b/doc/HACKING/GettingStartedRust.md @@ -79,7 +79,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 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

1 0

[tor/master] Fix a variable name in tor-rust-dependencies
by nickm＠torproject.org 21 Feb '18

21 Feb '18

1 0

[tor/master] Merge branch 'maint-0.3.3'
by nickm＠torproject.org 21 Feb '18

21 Feb '18

commit e87a2759f3d7b51445334bccd1265427393e5528 Merge: 62c88a601 d489e4847 Author: Nick Mathewson <nickm(a)torproject.org> Date: Wed Feb 21 11:56:02 2018 -0500 Merge branch 'maint-0.3.3' doc/HACKING/GettingStartedRust.md | 95 +++++++++++++++++++++------------------ 1 file changed, 51 insertions(+), 44 deletions(-)

1 0

[tor/release-0.3.3] Wrap GettingStartedRust.md to 72 columns.
by nickm＠torproject.org 21 Feb '18

21 Feb '18

1 0

[tor/release-0.3.3] Fix a variable name in tor-rust-dependencies
by nickm＠torproject.org 21 Feb '18

21 Feb '18

1 0

[tor/maint-0.3.1] Update the .gitmodules to refer to project-level tor-rust-dependencies
by nickm＠torproject.org 21 Feb '18

21 Feb '18

commit ac1942ac58d631af036acc97c73dad9d89b23aaf Author: Nick Mathewson <nickm(a)torproject.org> Date: Wed Feb 21 11:53:04 2018 -0500 Update the .gitmodules to refer to project-level tor-rust-dependencies Closes most of #25323. --- .gitmodules | 2 +- changes/ticket25323 | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.gitmodules b/.gitmodules index 7074403c9..8f8040565 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,3 +1,3 @@ [submodule "src/ext/rust"] path = src/ext/rust - url = https://git.torproject.org/user/sebastian/tor-rust-dependencies + url = https://git.torproject.org/tor-rust-dependencies diff --git a/changes/ticket25323 b/changes/ticket25323 new file mode 100644 index 000000000..836825de5 --- /dev/null +++ b/changes/ticket25323 @@ -0,0 +1,4 @@ + o Code simplification and refactoring: + - Update the "rust dependencies" submodule to be an project-level + repository, rather than a user repository. Closes ticket 25323. +

1 0

[tor/maint-0.3.2] Update the .gitmodules to refer to project-level tor-rust-dependencies
by nickm＠torproject.org 21 Feb '18

21 Feb '18

1 0

[tor/maint-0.3.3] Merge branch 'maint-0.3.1' into maint-0.3.2
by nickm＠torproject.org 21 Feb '18

21 Feb '18

commit bcfb034957dbd5d891befcd99a9725a225903b4e Merge: bd71e0a0c ac1942ac5 Author: Nick Mathewson <nickm(a)torproject.org> Date: Wed Feb 21 11:53:50 2018 -0500 Merge branch 'maint-0.3.1' into maint-0.3.2 .gitmodules | 2 +- changes/ticket25323 | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-)

1 0

← Newer
1
...
7
8
9
10
11
12
13
...
158
Older →

Jump to page:

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

tor-commits February 2018