Add warning messages for features that will become optional in 0.4.0. #…

…426

CHANGELOG.md

@@ -23,14 +23,26 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - `Criterion::bench_function_over_inputs`, `Criterion::bench_functions`, and `Criterion::bench` were
   already hidden from documentation, but are now formally deprecated pending deletion in 0.4.0.
   Callers should use `BenchmarkGroup` instead.
+- Three new optional features have been added; "html_reports", "csv_output" and 
+  "cargo_bench_support". These features currently do nothing except disable a warning message at 
+  runtime, but in version 0.4.0 they will be used to enable HTML report generation, CSV file 
+  generation, and the ability to run in cargo-bench (as opposed to [cargo-criterion]). 
+  "cargo_bench_support" is enabled by default, but "html_reports" and "csv_output"
+  are not. If you use Criterion.rs' HTML reports, it is recommended to switch to [cargo-criterion].
+  If you use CSV output, it is recommended to switch to [cargo-criterion] and use the 
+  `--message-format=json` option for machine-readable output instead. A warning message will be
+  printed at the start of benchmark runs which do not have "html_reports" or "cargo_bench_support"
+  enabled, but because CSV output is not widely used it has no warning.
+
+[cargo-criterion]: /~https://github.com/bheisler/cargo-criterion
 
 ## [0.3.3] - 2020-06-29
 ### Added
 - Added `CRITERION_HOME` environment variable to set the directory for Criterion to store
   its results and charts in. 
-- Added support for [cargo-criterion](/~https://github.com/bheisler/cargo-criterion). The long-term
-  goal here is to remove code from Criterion-rs itself to improve compile times, as well as to add
-  features to `cargo-criterion` that are difficult to implement in Criterion-rs.
+- Added support for [cargo-criterion]. The long-term goal here is to remove code from Criterion-rs 
+  itself to improve compile times, as well as to add  features to `cargo-criterion` that are 
+  difficult to implement in Criterion-rs.
 - Add sampling mode option for benchmarks. This allows the user to change how Criterion.rs chooses
   the iteration counts in each sample. By default, nothing will change for most benchmarks, but
   very slow benchmarks will now run fewer iterations to fit in the desired number of samples.

Cargo.toml

@@ -54,7 +54,7 @@ appveyor = { repository = "bheisler/criterion.rs", id = "4255ads9ctpupcl2" }
 maintenance = { status = "passively-maintained" }
 
 [features]
-default = []
+default = ["cargo_bench_support"]
 
 # Enable use of the nightly-only test::black_box function to discourage compiler optimizations.
 real_blackbox = []
@@ -69,6 +69,19 @@ async_smol = ["smol", "async"]
 async_tokio = ["tokio", "async"]
 async_std = ["async-std", "async"]
 
+# This feature _currently_ does nothing except disable a warning message, but in 0.4.0 it will be
+# required in order to have Criterion.rs generate its own plots (as opposed to using cargo-criterion)
+html_reports = []
+
+# This feature _currently_ does nothing except disable a warning message, but in 0.4.0 it will be
+# required in order to have Criterion.rs be usable outside of cargo-criterion.
+cargo_bench_support = []
+
+# This feature _currently_ does nothing, but in 0.4.0 it will be
+# required in order to have Criterion.rs generate CSV files. This feature is deprecated in favor of
+# cargo-criterion's --message-format=json option.
+csv_output = []
+
 [workspace]
 exclude = ["cargo-criterion"]
 

book/src/user_guide/csv_output.md

@@ -1,5 +1,10 @@
 # CSV Output
 
+NOTE: The CSV output is in the process of being deprecated. For machine-readable output,
+cargo-criterion's `--message-format=json` option is recommended instead - see [External
+Tools](../cargo_criterion/external_tools.html). CSV output will become an optional feature in
+Criterion.rs 0.4.0.
+
 Criterion.rs saves its measurements in several files, as shown below:
 
 ```

src/lib.rs

@@ -1550,3 +1550,53 @@ pub fn runner(benches: &[&dyn Fn()]) {
     }
     Criterion::default().configure_from_args().final_summary();
 }
+
+/// Print a warning informing users about upcoming changes to features
+#[cfg(not(feature = "html_reports"))]
+#[doc(hidden)]
+pub fn __warn_about_html_reports_feature() {
+    if CARGO_CRITERION_CONNECTION.is_none() {
+        println!(
+            "WARNING: HTML report generation will become a non-default optional feature in Criterion.rs 0.4.0."
+        );
+        println!(
+            "This feature is being moved to cargo-criterion \
+            (/~https://github.com/bheisler/cargo-criterion) and will be optional in a future \
+            version of Criterion.rs. To silence this warning, either switch to cargo-criterion or \
+            enable the 'html_reports' feature in your Cargo.toml."
+        );
+        println!();
+    }
+}
+
+/// Print a warning informing users about upcoming changes to features
+#[cfg(feature = "html_reports")]
+#[doc(hidden)]
+pub fn __warn_about_html_reports_feature() {
+    // They have the feature enabled, so they're ready for the update.
+}
+
+/// Print a warning informing users about upcoming changes to features
+#[cfg(not(feature = "cargo_bench_support"))]
+#[doc(hidden)]
+pub fn __warn_about_cargo_bench_support_feature() {
+    if CARGO_CRITERION_CONNECTION.is_none() {
+        println!(
+            "WARNING: In Criterion.rs 0.4.0, running criterion benchmarks outside of cargo-criterion will become a default optional feature."
+        );
+        println!(
+            "The statistical analysis and reporting is being moved to cargo-criterion \
+            (/~https://github.com/bheisler/cargo-criterion) and will be optional in a future \
+            version of Criterion.rs. To silence this warning, either switch to cargo-criterion or \
+            enable the 'cargo_bench_support' feature in your Cargo.toml."
+        );
+        println!();
+    }
+}
+
+/// Print a warning informing users about upcoming changes to features
+#[cfg(feature = "cargo_bench_support")]
+#[doc(hidden)]
+pub fn __warn_about_cargo_bench_support_feature() {
+    // They have the feature enabled, so they're ready for the update.
+}

src/macros.rs

@@ -120,6 +120,9 @@ macro_rules! criterion_group {
 macro_rules! criterion_main {
     ( $( $group:path ),+ $(,)* ) => {
         fn main() {
+            $crate::__warn_about_html_reports_feature();
+            $crate::__warn_about_cargo_bench_support_feature();
+
             $(
                 $group();
             )+