expose HYPERFINE_ITERATION to intermediate commands

Fixes: #781

Expose the `$HYPERFINE_ITERATION` variable to intermediate commands.
This will allow iteration-specific prepare/conclude, such as:

```bash
hyperfine --runs 5 --prepare 'echo touch file${HYPERFINE_ITERATION}.dat' \
    'echo testing file${HYPERFINE_ITERATION}.dat' \
    --conclude 'echo rm file${HYPERFINE_ITERATION}.dat' --show-output
```

src/benchmark/executor.rs

@@ -36,7 +36,7 @@ pub trait Executor {
     fn run_command_and_measure(
         &self,
         command: &Command<'_>,
-        iteration: BenchmarkIteration,
+        iteration: &BenchmarkIteration,
         command_failure_action: Option<CmdFailureAction>,
         output_policy: &CommandOutputPolicy,
     ) -> Result<Measurement>;
@@ -56,7 +56,7 @@ pub trait Executor {
 
 fn run_command_and_measure_common(
     mut command: std::process::Command,
-    iteration: BenchmarkIteration,
+    iteration: &BenchmarkIteration,
     command_failure_action: CmdFailureAction,
     command_input_policy: &CommandInputPolicy,
     command_output_policy: &CommandOutputPolicy,
@@ -132,7 +132,7 @@ impl Executor for RawExecutor<'_> {
     fn run_command_and_measure(
         &self,
         command: &Command<'_>,
-        iteration: BenchmarkIteration,
+        iteration: &BenchmarkIteration,
         command_failure_action: Option<CmdFailureAction>,
         output_policy: &CommandOutputPolicy,
     ) -> Result<Measurement> {
@@ -175,7 +175,7 @@ impl Executor for ShellExecutor<'_> {
     fn run_command_and_measure(
         &self,
         command: &Command<'_>,
-        iteration: BenchmarkIteration,
+        iteration: &BenchmarkIteration,
         command_failure_action: Option<CmdFailureAction>,
         output_policy: &CommandOutputPolicy,
     ) -> Result<Measurement> {
@@ -230,7 +230,7 @@ impl Executor for ShellExecutor<'_> {
             // Just run the shell without any command
             let res = self.run_command_and_measure(
                 &Command::new(None, ""),
-                BenchmarkIteration::NonBenchmarkRun,
+                &BenchmarkIteration::NonBenchmarkRun,
                 None,
                 &CommandOutputPolicy::Null,
             );
@@ -304,7 +304,7 @@ impl Executor for MockExecutor {
     fn run_command_and_measure(
         &self,
         command: &Command<'_>,
-        _iteration: BenchmarkIteration,
+        _iteration: &BenchmarkIteration,
         _command_failure_action: Option<CmdFailureAction>,
         _output_policy: &CommandOutputPolicy,
     ) -> Result<Measurement> {

src/benchmark/mod.rs

@@ -58,11 +58,12 @@ impl<'a> Benchmark<'a> {
         command: &Command<'_>,
         error_output: &'static str,
         output_policy: &CommandOutputPolicy,
+        iteration: &executor::BenchmarkIteration,
     ) -> Result<Measurement> {
         self.executor
             .run_command_and_measure(
                 command,
-                executor::BenchmarkIteration::NonBenchmarkRun,
+                iteration,
                 Some(CmdFailureAction::RaiseError),
                 output_policy,
             )
@@ -74,6 +75,7 @@ impl<'a> Benchmark<'a> {
         &self,
         parameters: impl IntoIterator<Item = ParameterNameAndValue<'a>>,
         output_policy: &CommandOutputPolicy,
+        iteration: executor::BenchmarkIteration,
     ) -> Result<Measurement> {
         let command = self
             .options
@@ -85,7 +87,7 @@ impl<'a> Benchmark<'a> {
                             Append ' || true' to the command if you are sure that this can be ignored.";
 
         Ok(command
-            .map(|cmd| self.run_intermediate_command(&cmd, error_output, output_policy))
+            .map(|cmd| self.run_intermediate_command(&cmd, error_output, output_policy, &iteration))
             .transpose()?
             .unwrap_or_default())
     }
@@ -95,6 +97,7 @@ impl<'a> Benchmark<'a> {
         &self,
         parameters: impl IntoIterator<Item = ParameterNameAndValue<'a>>,
         output_policy: &CommandOutputPolicy,
+        iteration: executor::BenchmarkIteration,
     ) -> Result<Measurement> {
         let command = self
             .options
@@ -106,7 +109,7 @@ impl<'a> Benchmark<'a> {
                             Append ' || true' to the command if you are sure that this can be ignored.";
 
         Ok(command
-            .map(|cmd| self.run_intermediate_command(&cmd, error_output, output_policy))
+            .map(|cmd| self.run_intermediate_command(&cmd, error_output, output_policy, &iteration))
             .transpose()?
             .unwrap_or_default())
     }
@@ -116,11 +119,12 @@ impl<'a> Benchmark<'a> {
         &self,
         command: &Command<'_>,
         output_policy: &CommandOutputPolicy,
+        iteration: &executor::BenchmarkIteration,
     ) -> Result<Measurement> {
         let error_output = "The preparation command terminated with a non-zero exit code. \
                             Append ' || true' to the command if you are sure that this can be ignored.";
 
-        self.run_intermediate_command(command, error_output, output_policy)
+        self.run_intermediate_command(command, error_output, output_policy, iteration)
     }
 
     /// Run the command specified by `--conclude`.
@@ -128,11 +132,12 @@ impl<'a> Benchmark<'a> {
         &self,
         command: &Command<'_>,
         output_policy: &CommandOutputPolicy,
+        iteration: executor::BenchmarkIteration,
     ) -> Result<Measurement> {
         let error_output = "The conclusion command terminated with a non-zero exit code. \
                             Append ' || true' to the command if you are sure that this can be ignored.";
 
-        self.run_intermediate_command(command, error_output, output_policy)
+        self.run_intermediate_command(command, error_output, output_policy, &iteration)
     }
 
     /// Run the benchmark for a single command
@@ -165,10 +170,10 @@ impl<'a> Benchmark<'a> {
             )
         });
 
-        let run_preparation_command = || {
+        let run_preparation_command = |iteration: &executor::BenchmarkIteration| {
             preparation_command
                 .as_ref()
-                .map(|cmd| self.run_preparation_command(cmd, output_policy))
+                .map(|cmd| self.run_preparation_command(cmd, output_policy, iteration))
                 .transpose()
         };
 
@@ -184,14 +189,18 @@ impl<'a> Benchmark<'a> {
                 self.command.get_parameters().iter().cloned(),
             )
         });
-        let run_conclusion_command = || {
+        let run_conclusion_command = |iteration: executor::BenchmarkIteration| {
             conclusion_command
                 .as_ref()
-                .map(|cmd| self.run_conclusion_command(cmd, output_policy))
+                .map(|cmd| self.run_conclusion_command(cmd, output_policy, iteration))
                 .transpose()
         };
 
-        self.run_setup_command(self.command.get_parameters().iter().cloned(), output_policy)?;
+        self.run_setup_command(
+            self.command.get_parameters().iter().cloned(),
+            output_policy,
+            executor::BenchmarkIteration::NonBenchmarkRun,
+        )?;
 
         // Warmup phase
         if self.options.warmup_count > 0 {
@@ -206,14 +215,15 @@ impl<'a> Benchmark<'a> {
             };
 
             for i in 0..self.options.warmup_count {
-                let _ = run_preparation_command()?;
+                let warmup_iteration = BenchmarkIteration::Warmup(i);
+                let _ = run_preparation_command(&warmup_iteration)?;
                 let _ = self.executor.run_command_and_measure(
                     self.command,
-                    BenchmarkIteration::Warmup(i),
+                    &warmup_iteration,
                     None,
                     output_policy,
                 )?;
-                let _ = run_conclusion_command()?;
+                let _ = run_conclusion_command(warmup_iteration)?;
                 if let Some(bar) = progress_bar.as_ref() {
                     bar.inc(1)
                 }
@@ -234,7 +244,8 @@ impl<'a> Benchmark<'a> {
             None
         };
 
-        let preparation_result = run_preparation_command()?;
+        let benchmark_iteration = BenchmarkIteration::Benchmark(0);
+        let preparation_result = run_preparation_command(&benchmark_iteration)?;
         let preparation_overhead = preparation_result.map_or(Time::zero(), |res| {
             res.time_wall_clock + self.executor.time_overhead()
         });
@@ -242,13 +253,13 @@ impl<'a> Benchmark<'a> {
         // Initial timing run
         let res = self.executor.run_command_and_measure(
             self.command,
-            BenchmarkIteration::Benchmark(0),
+            &benchmark_iteration,
             None,
             output_policy,
         )?;
         let success = res.exit_status.success();
 
-        let conclusion_result = run_conclusion_command()?;
+        let conclusion_result = run_conclusion_command(benchmark_iteration)?;
         let conclusion_overhead = conclusion_result.map_or(Time::zero(), |res| {
             res.time_wall_clock + self.executor.time_overhead()
         });
@@ -289,7 +300,8 @@ impl<'a> Benchmark<'a> {
 
         // Gather statistics (perform the actual benchmark)
         for i in 0..count_remaining {
-            run_preparation_command()?;
+            let benchmark_iteration = BenchmarkIteration::Benchmark(i + 1);
+            run_preparation_command(&benchmark_iteration)?;
 
             let msg = {
                 let t_wall_clock_mean = measurements.time_wall_clock_mean();
@@ -307,7 +319,7 @@ impl<'a> Benchmark<'a> {
 
             let res = self.executor.run_command_and_measure(
                 self.command,
-                BenchmarkIteration::Benchmark(i + 1),
+                &benchmark_iteration,
                 None,
                 output_policy,
             )?;
@@ -321,7 +333,7 @@ impl<'a> Benchmark<'a> {
                 bar.inc(1)
             }
 
-            run_conclusion_command()?;
+            run_conclusion_command(benchmark_iteration)?;
         }
 
         if let Some(bar) = progress_bar.as_ref() {
@@ -440,7 +452,11 @@ impl<'a> Benchmark<'a> {
             console_writeln!(io::stdout(), " ")?;
         }
 
-        self.run_cleanup_command(self.command.get_parameters().iter().cloned(), output_policy)?;
+        self.run_cleanup_command(
+            self.command.get_parameters().iter().cloned(),
+            output_policy,
+            executor::BenchmarkIteration::NonBenchmarkRun,
+        )?;
 
         Ok(BenchmarkResult {
             command: self.command.get_name(),