Merge rust-bitcoin/rust-bitcoin#1092: Create configuration conditional "bench"

f3b2120 Create configuration conditional bench (Tobin C. Harding)
f60c92c Add informative error message to DO_BENCH (Tobin C. Harding)
c6d5a12 Add cargo/rustc sanity calls (Tobin C. Harding)
34d5a31 Put triple ticks on their own line (Tobin C. Harding)

Pull request description:

  Currently we are unable to build with all features enabled with a non-nightly toolchain, this is because of the use of

      `#![cfg_attr(all(test, feature = "unstable"), feature(test))]`

  which causes the following error when building:

   error[E0554]: `#![feature]` may not be used on the stable release channel

  The "unstable" feature is used to guard bench mark modules, this is widely suggested online but there is a better way.

  When running the bench marks use the following incantation:

      `RUSTFLAGS='--cfg=bench' cargo bench`

  This creates a configuration conditional "bench" that can be used to guard the bench mark modules.

  ```
  #[cfg(bench)]
  mod benches {
      ...
  }
  ```

ACKs for top commit:
  Kixunil:
    ACK f3b2120
  apoelstra:
    ACK f3b2120

Tree-SHA512: 7ec2a501a30bfe2ce72601077cd675cf5e5ac2f0f93f97fc7e83cb7401606b69ae909b35bfc0ace8bd1ea771ca4fba70e2ad9ac9ba26f2b6e371494cf694c0a8

Author: apoelstra

Cargo.toml

@@ -15,7 +15,6 @@ edition = "2018"
 # Please don't forget to add relevant features to docs.rs below
 [features]
 default = [ "std", "secp-recovery" ]
-unstable = []
 rand = ["secp256k1/rand-std"]
 serde = ["actual-serde", "bitcoin_hashes/serde", "secp256k1/serde"]
 secp-lowmemory = ["secp256k1/lowmemory"]

README.md

@@ -106,7 +106,14 @@ Please refer to the [`cargo` documentation](https://doc.rust-lang.org/stable/car
 We build docs with the nightly toolchain, you may wish to use the following
 shell alias to check your documentation changes build correctly.
 
-```alias build-docs='RUSTDOCFLAGS="--cfg docsrs" cargo +nightly rustdoc --features="$FEATURES" -- -D rustdoc::broken-intra-doc-links'```
+```
+alias build-docs='RUSTDOCFLAGS="--cfg docsrs" cargo +nightly rustdoc --features="$FEATURES" -- -D rustdoc::broken-intra-doc-links'
+```
+
+### Running benchmarks
+
+We use a custom Rust compiler configuration conditional to guard the bench mark code. To run the
+bench marks use: `RUSTFLAGS='--cfg=bench' cargo +nightly bench`.
 
 ## Pull Requests
 

contrib/test.sh

@@ -13,6 +13,14 @@ then
     export RUSTFLAGS="-C link-dead-code"
 fi
 
+cargo --version
+rustc --version
+
+# Work out if we are using a nightly toolchain.
+NIGHTLY=false
+if cargo --version | grep nightly; then
+    NIGHTLY=true
+fi
 
 echo "********* Testing std *************"
 # Test without any features other than std first
@@ -69,10 +77,20 @@ then
     )
 fi
 
-# Bench if told to
+# Bench if told to, only works with non-stable toolchain (nightly, beta).
 if [ "$DO_BENCH" = true ]
 then
-    cargo bench --features unstable
+    if [ "NIGHTLY" = false ]
+    then
+        if [ -n "TOOLCHAIN" ]
+        then
+            echo "TOOLCHAIN is set to a non-nightly toolchain but DO_BENCH requires a nightly toolchain"
+        else
+            echo "DO_BENCH requires a nightly toolchain"
+        fi
+        exit 1
+    fi
+    RUSTFLAGS='--cfg=bench' cargo bench
 fi
 
 # Use as dependency if told to

src/blockdata/block.rs

@@ -528,7 +528,7 @@ mod tests {
     }
 }
 
-#[cfg(all(test, feature = "unstable"))]
+#[cfg(bench)]
 mod benches {
     use super::Block;
     use crate::EmptyWrite;

src/blockdata/transaction.rs

@@ -1724,7 +1724,7 @@ mod tests {
     }
 }
 
-#[cfg(all(test, feature = "unstable"))]
+#[cfg(bench)]
 mod benches {
     use super::Transaction;
     use crate::EmptyWrite;

src/blockdata/witness.rs

@@ -441,7 +441,7 @@ mod test {
 }
 
 
-#[cfg(all(test, feature = "unstable"))]
+#[cfg(bench)]
 mod benches {
     use test::{Bencher, black_box};
     use super::Witness;

src/lib.rs

@@ -19,7 +19,6 @@
 //! * `std` - the usual dependency on `std` (default).
 //! * `secp-recovery` - enables calculating public key from a signature and message.
 //! * `base64` - (dependency), enables encoding of PSBTs and message signatures.
-//! * `unstable` - enables unstable features for testing.
 //! * `rand` - (dependency), makes it more convenient to generate random values.
 //! * `serde` - (dependency), implements `serde`-based serialization and
 //!                 deserialization.
@@ -31,9 +30,8 @@
 
 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
 
-// Experimental features we need
-#![cfg_attr(all(test, feature = "unstable"), feature(test))]
-
+// Experimental features we need.
+#![cfg_attr(bench, feature(test))]
 #![cfg_attr(docsrs, feature(doc_cfg))]
 
 // Coding conventions
@@ -56,6 +54,8 @@ compile_error!("rust-bitcoin currently only supports architectures with pointers
                 than 16 bits, let us know if you want 16-bit support. Note that we do
                 NOT guarantee that we will implement it!");
 
+#[cfg(bench)] extern crate test;
+
 #[cfg(feature = "no-std")]
 #[macro_use]
 extern crate alloc;
@@ -181,10 +181,10 @@ mod prelude {
     pub use std::collections::HashSet;
 }
 
-#[cfg(all(test, feature = "unstable"))] use tests::EmptyWrite;
+#[cfg(bench)] use bench::EmptyWrite;
 
-#[cfg(all(test, feature = "unstable"))]
-mod tests {
+#[cfg(bench)]
+mod bench {
     use core::fmt::Arguments;
     use crate::io::{IoSlice, Result, Write};