[guide] How to disable miri in doctests

[yoshuawuyts]

I'm documenting this for posterity in an issue, following up from #584. This is what I've used to disable miri from running in my doc tests:

/// # Example
///
/// ```
/// # #[cfg(miri)] fn main() {}
/// # #[cfg(not(miri))]
/// # fn main() {
/// use my_crate::my_function;
///
/// my_function();
/// # }
/// ```
fn my_function() {}

This should show the example as intended in the docs while also ensuring miri doesn't run this particular doctest. This also provides a dummy main function to ensure that miri doesn't complain about a missing fn main either.

This took me around 30 mins to figure out, so I wanted to make sure I'd leave a note of how to do this in the miri repo in case anyone else runs into this in the future. Thanks!

[yoshuawuyts]

Closing this straight away as there shouldn't be anything actionable here.

[RalfJung]

Usually I would do that via:

/// ```no_run
/// my_function();
/// ```
fn my_function() {}

This will type-check the doctest but not run it.

So a trick like the above is only needed if you want the example to run in cargo test but not cargo miri test. That should be pretty rare I think? But the dummy main function is a nice trick, I recently wanted to enable a test only under cfg(bootstrap) and couldn't get it to work; this would have done it.

[yoshuawuyts]

So a trick like the above is only needed if you want the example to run in cargo test but not cargo miri test. That should be pretty rare I think?

This came up when writing yoshuawuyts/futures-concurrency#167 earlier today. Miri doesn't understand how things like async timers work, so I figured we should just skip the doctest here. But it's still useful to test on e.g. linux to actually ensure the test works as intended.

[saethlin]

Miri doesn't understand how things like async timers work

Because of an attempt to call an external function or make a syscall Miri doesn't understand? Which one(s)?

[yoshuawuyts]

I believe it may have been something kqueue related given I'm on macOS and was executing async code. My test pulls in an async timer crate, which I don't think Miri liked.

[RalfJung]

Yeah Miri can't run the Tokio executor on any target I think. On Linux it's missing epoll.