Add a high-level tutorial

[llogiq]

I'm missing some documentation on, say, migrating a "standard" benchmark to a criterion benchmark.

[Ygg01]

Hm. Could I be of assistance? I think I could write a docs for this.

[sourcefrog]

A few things I found confusing that might help to address in the readme

• Should they live under benches/?
• It looks like this only works on nightly, at least due to its dependencies
• This is not yet on Crates.io, you have to add a git= dependency
• How are you intended to run the benchmarks?
• Is the idea that the benchmarks only write output to files and don't display it, and you have a separate program that displays it? Or, should this crate ship a binary that displays the output?

[bheisler]

Thanks for the comments. I think they're mostly addressed by the user guide I've added, but the short version is:

• Yes, the benchmarks should live under benches/. It's a bit odd that they're marked with #[test], but hopefully we can find a way around that at some point.
• Correct, Criterion-rs only works on nightly. That will continue for the foreseeable future, partly because it will take some work to refactor away much of the nightly-only code but mostly because it relies on the nightly-only test::black_box function (see the RFC to stabilize that).
• Correct, Criterion-rs is not yet available on crates.io. I hope to make a release in the next few weeks.
• You can run the benchmarks with the command cargo bench -- --test --nocapture. It's kind of awkward, and I hope to find a nicer way to do that.

With the addition of the user guide, I think this issue is satisfied, at least for the time being.

[sourcefrog]

The user guide looks great, thanks!

[llogiq]

@bheisler regarding nightly, you may want to have a look at the bencher crate. This is but a workaround, but runs on stable and is good enough for many applications. You may want to consider adopting their technique (volatile write) and offer the nightly version as a feature. That way criterion-rs could benefit far more users while retaining the full functionality.

[bheisler]

Ah, I wasn't aware of the bencher crate. Thanks, I'll take a look.