From fce6845f2b2165c6835b0b9de8d6728da387ad79 Mon Sep 17 00:00:00 2001 From: Alice Ryhl Date: Sun, 15 Mar 2020 13:02:39 +0100 Subject: Document common cargo commands (#2293) * Document common cargo commands * Add loom command --- CONTRIBUTING.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e1a6956..0aa58273 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -112,6 +112,39 @@ usually a good idea to first open an issue describing the change to solicit feedback and guidance. This will increase the likelihood of the PR getting merged. +### Cargo Commands + +Due to the extensive use of features in Tokio, you will often need to add extra +arguments to many common cargo commands. This section lists some commonly needed +commands. + +Some commands just need the `--all-features` argument: +``` +cargo build --all-features +cargo check --all-features +cargo test --all-features +``` +When building documentation normally, the markers that list the features +required for various parts of Tokio are missing. To build the documentation +correctly, use this command: +``` +RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features +``` +The `cargo fmt` command does not work on the Tokio codebase. You can use the +command below instead: +``` +rustfmt --check --edition 2018 $(find . -name '*.rs' -print) +``` +The `--check` argument prints the things that need to be fixed. If you remove +it, `rustfmt` will update your files locally instead. + +You can run loom tests with +``` +cd tokio # tokio crate in workspace +LOOM_MAX_PREEMPTIONS=1 RUSTFLAGS="--cfg loom" \ + cargo test --lib --release --features full -- --test-threads=1 --nocapture +``` + ### Tests If the change being proposed alters code (as opposed to only documentation for -- cgit v1.2.3