Update README files with common style.

- external links use markdown's []() format,
- local files are formated with backquotes,
- duplicated new lines were removed,
- unnecesary single spaces were removed,
- broken links and local paths were updated.
This commit is contained in:
Bartosz Duszel
2020-03-22 13:50:58 +01:00
parent dccac40e69
commit fd6a35eb59
8 changed files with 71 additions and 94 deletions
+13 -16
View File
@@ -1,8 +1,7 @@
Hacking on Rust in Tor
Hacking on Rust in Tor
========================
Getting Started
Getting Started
-----------------
Please read or review our documentation on Rust coding standards
@@ -23,7 +22,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**
@@ -49,7 +48,7 @@ is
For learning more about FFI and Rust, see Jake Goulding's
[Rust FFI Omnibus](http://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`
@@ -79,7 +78,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,8 +86,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
@@ -117,12 +115,12 @@ 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,14 +132,13 @@ 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)
@@ -156,7 +153,7 @@ 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.
@@ -177,7 +174,7 @@ 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`.