diff options
Diffstat (limited to 'doc/HACKING/GettingStartedRust.md')
| -rw-r--r-- | doc/HACKING/GettingStartedRust.md | 51 |
1 files changed, 32 insertions, 19 deletions
diff --git a/doc/HACKING/GettingStartedRust.md b/doc/HACKING/GettingStartedRust.md index a5253b46a6..3d00388314 100644 --- a/doc/HACKING/GettingStartedRust.md +++ b/doc/HACKING/GettingStartedRust.md @@ -60,30 +60,28 @@ or specifying a local directory. **Using a local dependency cache** -**NOTE**: local dependency caches which were not *originally* created via - `--enable-cargo-online-mode` are broken. See https://bugs.torproject.org/22907 +You'll need the following Rust dependencies (as of this writing): -To specify a local directory: + libc==0.2.22 - RUST_DEPENDENCIES='path_to_dependencies_directory' ./configure --enable-rust +We vendor our Rust dependencies in a separate repo using +[cargo-vendor](https://github.com/alexcrichton/cargo-vendor). To use them, do: -(Note that RUST_DEPENDENCIES must be the full path to the directory; it cannot -be relative.) + git submodule init + git submodule update -You'll need the following Rust dependencies (as of this writing): +To specify the local directory containing the dependencies, (assuming you are in +the top level of the repository) configure tor with: - libc==0.2.22 + TOR_RUST_DEPENDENCIES='path_to_dependencies_directory' ./configure --enable-rust -To get them, do: +(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: - mkdir path_to_dependencies_directory - cd path_to_dependencies_directory - git clone https://github.com/rust-lang/libc - cd libc - git checkout 0.2.22 - cargo package - cd .. - ln -s libc/target/package/libc-0.2.22 libc-0.2.22 + TOR_RUST_DEPENDENCIES=`pwd`/src/ext/rust/crates ./configure --enable-rust Identifying which modules to rewrite @@ -125,6 +123,16 @@ 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: + + /// 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. + Adding your Rust module to Tor's build system ----------------------------------------------- @@ -132,8 +140,13 @@ solidify on is readily available. in the `.../tor/src/rust/` directory. 1. Add your crate to `.../tor/src/rust/Cargo.toml`, in the `[workspace.members]` section. -2. Append your crate's static library to the `rust_ldadd` definition - (underneath `if USE_RUST`) in `.../tor/Makefile.am`. +2. Add your crate's files to src/rust/include.am + +If your crate should be available to C (rather than just being included as a +dependency of other Rust modules): +0. Declare the crate as a dependency of tor_rust in + `src/rust/tor_util/Cargo.toml` and include it in + `src/rust/tor_rust/lib.rs` How to test your Rust code ---------------------------- |