Changes between Version 5 and Version 6 of RustInTor/Hacking


Ignore:
Timestamp:
Sep 5, 2017, 6:59:16 PM (2 years ago)
Author:
isis
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • RustInTor/Hacking

    v5 v6  
    1 = Hacking on Rust in Tor =
     1The documentation on this page has moved into the tor.git repo! Please see [https://gitweb.torproject.org/tor.git/tree/doc/HACKING/GettingStartedRust.md `doc/HACKING/GettingStartedRust.md`] ([https://github.com/isislovecruft/tor/blob/master/doc/HACKING/GettingStartedRust.md rendered]) and [https://gitweb.torproject.org/tor.git/tree/doc/HACKING/CodingStandardsRust.md `doc/HACKING/CodingStandardsRust.md`] ([https://github.com/isislovecruft/tor/blob/master/doc/HACKING/CodingStandardsRust.md rendered]).
    22
    3 == Getting Started ==
    43
    5 Please read or review our documentation on
    6 [https://trac.torproject.org/projects/tor/wiki/RustInTor our documentation on Rust in Tor] before doing anything.
    7 
    8 Please also read [https://www.rust-lang.org/en-US/conduct.html the Rust Code of Conduct]. We aim to follow the good
    9 example set by the Rust community and be excellent to one another.
    10 Let's be careful with each other, so we can be memory-safe together!
    11 
    12 Next, please contact us before rewriting anything!  Rust in Tor is
    13 still an experiment.  It is an experiment that we very much want to
    14 see succeed, so we're going slowly and carefully.  For the moment,
    15 it's also a completely volunteer-driven effort: while many, if not
    16 most, of us are paid to work on Tor, we are not yet funded to write
    17 Rust code for Tor.  Please be patient with the other people who are
    18 working on getting more Rust code into Tor, because they are
    19 graciously donating their free time to contribute to this effort.
    20 
    21 === Resources for learning Rust ===
    22 
    23 ==== Beginning resources ====
    24 
    25 The primary resource for learning Rust is The Book:
    26 https://doc.rust-lang.org/book/.  If you'd like to start writing Rust
    27 immediately, without waiting for anything to install, there is
    28 https://play.rust-lang.org/.
    29 
    30 ==== Advanced ====
    31 
    32 If you're interested in playing with various Rust compilers and viewing a very
    33 nicely displayed output of the generated assembly, there is https://rust.godbolt.org/
    34 
    35 For learning how to write "unsafe" Rust, read The Rustonomicon:
    36 https://doc.rust-lang.org/nomicon/
    37 
    38 For learning everything you ever wanted to know about Rust macros, there is The
    39 Little Book of Rust Macros: https://danielkeep.github.io/tlborm/book/index.html
    40 
    41 == Identifying which modules to rewrite ==
    42 
    43 A good first step is to build a module-level callgraph to understand
    44 how interconnected your target module is.
    45 
    46 {{{
    47 git clone https://git.torproject.org/user/nickm/calltool.git
    48 cd tor
    49 CFLAGS=0 ./configure
    50 ../calltool/src/main.py module_callgraph
    51 }}}
    52 
    53 The output will tell you each module name, along with a set of every
    54 module that the module calls.  Modules which call fewer other modules
    55 are better targets.
    56 
    57 == Writing your Rust module ==
    58 
    59 Strive to change the C API as little as possible.
    60 
    61 We are currently targetting 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.
    62 
    63 == Adding your Rust module to Tor's build system ==
    64 
    65 0. Your translation of the C module should live in its own crate(s)
    66    in the `.../tor/src/rust/` directory.
    67 1. Add your crate to `.../tor/src/rust/Cargo.toml`, in the `[workspace.members]` section.
    68 2. Append your crate's static library to the `rust_ldadd` definition
    69    (underneath `if USE_RUST`) in `.../tor/Makefile.am`.
    70 
    71 == How to test your Rust code ==
    72 
    73 Everything should be tested full stop.  Even non-public functionality.
    74 
    75 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.
    76 
    77 Tor's test should be run by doing:
    78 
    79 {{{
    80 make check
    81 }}}
    82 
    83 Tor's integration tests should also pass:
    84 {{{
    85 make test-stem
    86 }}}