diff --git a/doc/HACKING/CodingStandardsRust.md b/doc/HACKING/CodingStandardsRust.md index 915d37e006..7c6405e624 100644 --- a/doc/HACKING/CodingStandardsRust.md +++ b/doc/HACKING/CodingStandardsRust.md @@ -81,6 +81,26 @@ 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