diff --git a/doc/HACKING/CodingStandardsRust.md b/doc/HACKING/CodingStandardsRust.md index ad8cd9d04b..7c6405e624 100644 --- a/doc/HACKING/CodingStandardsRust.md +++ b/doc/HACKING/CodingStandardsRust.md @@ -61,10 +61,46 @@ In general, we use modules from only the Rust standard library whenever possible. We will review including external crates on a case-by-case basis. +If a crate only contains traits meant for compatibility between Rust +crates, such as [the digest crate](https://crates.io/crates/digest) or +[the failure crate](https://crates.io/crates/failure), it is very likely +permissible to add it as a dependency. However, a brief review should +be conducted as to the usefulness of implementing external traits +(i.e. how widespread is the usage, how many other crates either +implement the traits or have trait bounds based upon them), as well as +the stability of the traits (i.e. if the trait is going to change, we'll +potentially have to re-do all our implementations of it). + +For large external libraries, especially which implement features which +would be labour-intensive to reproduce/maintain ourselves, such as +cryptographic or mathematical/statistics libraries, only crates which +have stabilised to 1.0.0 should be considered, however, again, we may +make exceptions on a case-by-case basis. + Currently, Tor requires that you use the latest stable Rust version. At some point in the future, we will freeze on a given stable Rust version, to ensure backward compatibility with stable distributions that ship it. + Updating/Adding Dependencies +------------------------------ + +To add/remove/update dependencies, first add your dependencies, +exactly specifying their versions, into the appropriate *crate-level* +`Cargo.toml` in `src/rust/` (i.e. *not* `/src/rust/Cargo.toml`, but +instead the one for your crate). Also, investigate whether your +dependency has any optional dependencies which are unnecessary but are +enabled by default. If so, you'll likely be able to enable/disable +them via some feature, e.g.: + +```toml +[dependencies] +foo = { version = "1.0.0", default-features = false } +``` + +Next, run `/scripts/maint/updateRustDependencies.sh`. Then, go into +`src/ext/rust` and commit the changes to the `tor-rust-dependencies` +repo. + Documentation --------------- diff --git a/scripts/maint/updateRustDependencies.sh b/scripts/maint/updateRustDependencies.sh new file mode 100755 index 0000000000..a5a92579d3 --- /dev/null +++ b/scripts/maint/updateRustDependencies.sh @@ -0,0 +1,45 @@ +#!/usr/bin/env bash +# +# Copyright (c) 2018 The Tor Project, Inc. +# Copyright (c) 2018 isis agora lovecruft +# See LICENSE for license information +# +# updateRustDependencies.sh +# ------------------------- +# Update our vendored Rust dependencies, either adding/removing +# dependencies and/or upgrading current dependencies to newer +# versions. +# +# To use this script, first add your dependencies, exactly specifying +# their versions, into the appropriate *crate-level* Cargo.toml in +# src/rust/ (i.e. *not* /src/rust/Cargo.toml, but instead the one for +# your crate). +# +# Next, run this script. Then, go into src/ext/rust and commit the +# changes to the tor-rust-dependencies repo. + +set -e + +HERE=`dirname $(realpath $0)` +TOPLEVEL=`dirname $(dirname $HERE)` +TOML="$TOPLEVEL/src/rust/Cargo.toml" +VENDORED="$TOPLEVEL/src/ext/rust/crates" +CARGO=`which cargo` + +if ! test -f "$TOML" ; then + printf "Error: Couldn't find workspace Cargo.toml in expected location: %s\n" "$TOML" +fi + +if ! test -d "$VENDORED" ; then + printf "Error: Couldn't find directory for Rust dependencies! Expected location: %s\n" "$VENDORED" +fi + +if test -z "$CARGO" ; then + printf "Error: cargo must be installed and in your \$PATH\n" +fi + +if test -z `cargo --list | grep vendor` ; then + printf "Error: cargo-vendor not installed\n" +fi + +$CARGO vendor -v --locked --explicit-version --no-delete --sync $TOML $VENDORED diff --git a/src/ext/rust b/src/ext/rust index 2402968008..2422d7accc 160000 --- a/src/ext/rust +++ b/src/ext/rust @@ -1 +1 @@ -Subproject commit 240296800824e40b10cb8c16da0e711563353945 +Subproject commit 2422d7acccc44c633ea825b630ceee6777773cc2 diff --git a/src/rust/Cargo.lock b/src/rust/Cargo.lock index 224d2135bf..4f918c0221 100644 --- a/src/rust/Cargo.lock +++ b/src/rust/Cargo.lock @@ -1,21 +1,13 @@ -[root] -name = "tor_util" -version = "0.0.1" -dependencies = [ - "libc 0.2.22 (registry+https://github.com/rust-lang/crates.io-index)", - "tor_allocate 0.0.1", -] - [[package]] name = "external" version = "0.0.1" dependencies = [ - "libc 0.2.22 (registry+https://github.com/rust-lang/crates.io-index)", + "libc 0.2.39 (registry+https://github.com/rust-lang/crates.io-index)", ] [[package]] name = "libc" -version = "0.2.22" +version = "0.2.39" source = "registry+https://github.com/rust-lang/crates.io-index" [[package]] @@ -23,7 +15,7 @@ name = "protover" version = "0.0.1" dependencies = [ "external 0.0.1", - "libc 0.2.22 (registry+https://github.com/rust-lang/crates.io-index)", + "libc 0.2.39 (registry+https://github.com/rust-lang/crates.io-index)", "smartlist 0.0.1", "tor_allocate 0.0.1", "tor_util 0.0.1", @@ -33,14 +25,14 @@ dependencies = [ name = "smartlist" version = "0.0.1" dependencies = [ - "libc 0.2.22 (registry+https://github.com/rust-lang/crates.io-index)", + "libc 0.2.39 (registry+https://github.com/rust-lang/crates.io-index)", ] [[package]] name = "tor_allocate" version = "0.0.1" dependencies = [ - "libc 0.2.22 (registry+https://github.com/rust-lang/crates.io-index)", + "libc 0.2.39 (registry+https://github.com/rust-lang/crates.io-index)", ] [[package]] @@ -51,5 +43,13 @@ dependencies = [ "tor_util 0.0.1", ] +[[package]] +name = "tor_util" +version = "0.0.1" +dependencies = [ + "libc 0.2.39 (registry+https://github.com/rust-lang/crates.io-index)", + "tor_allocate 0.0.1", +] + [metadata] -"checksum libc 0.2.22 (registry+https://github.com/rust-lang/crates.io-index)" = "babb8281da88cba992fa1f4ddec7d63ed96280a1a53ec9b919fd37b53d71e502" +"checksum libc 0.2.39 (registry+https://github.com/rust-lang/crates.io-index)" = "f54263ad99207254cf58b5f701ecb432c717445ea2ee8af387334bdd1a03fdff" diff --git a/src/rust/external/Cargo.toml b/src/rust/external/Cargo.toml index bccd7033a7..b5957b1079 100644 --- a/src/rust/external/Cargo.toml +++ b/src/rust/external/Cargo.toml @@ -4,7 +4,7 @@ version = "0.0.1" name = "external" [dependencies] -libc = "0.2.22" +libc = "=0.2.39" [lib] name = "external" diff --git a/src/rust/protover/Cargo.toml b/src/rust/protover/Cargo.toml index 04d2f2ed7d..86301b8787 100644 --- a/src/rust/protover/Cargo.toml +++ b/src/rust/protover/Cargo.toml @@ -4,7 +4,7 @@ version = "0.0.1" name = "protover" [dependencies] -libc = "0.2.22" +libc = "=0.2.39" [dependencies.smartlist] path = "../smartlist" diff --git a/src/rust/smartlist/Cargo.toml b/src/rust/smartlist/Cargo.toml index 51f486c4d7..6ddcbee8e9 100644 --- a/src/rust/smartlist/Cargo.toml +++ b/src/rust/smartlist/Cargo.toml @@ -4,7 +4,7 @@ version = "0.0.1" name = "smartlist" [dependencies] -libc = "0.2.22" +libc = "0.2.39" [lib] name = "smartlist" diff --git a/src/rust/tor_allocate/Cargo.toml b/src/rust/tor_allocate/Cargo.toml index ceb08b78ab..468425f115 100644 --- a/src/rust/tor_allocate/Cargo.toml +++ b/src/rust/tor_allocate/Cargo.toml @@ -4,7 +4,7 @@ version = "0.0.1" name = "tor_allocate" [dependencies] -libc = "0.2.22" +libc = "=0.2.39" [lib] name = "tor_allocate" diff --git a/src/rust/tor_util/Cargo.toml b/src/rust/tor_util/Cargo.toml index d7379a5988..b540d8c847 100644 --- a/src/rust/tor_util/Cargo.toml +++ b/src/rust/tor_util/Cargo.toml @@ -12,5 +12,5 @@ crate_type = ["rlib", "staticlib"] path = "../tor_allocate" [dependencies] -libc = "0.2.22" +libc = "=0.2.39"