I have a strange documentation test issue related to "extern crate"

help
1

My documentation test code looks like this:

/// ```
/// extern crate rand;
/// # extern crate rusty_ulid;
/// # use rusty_ulid::Ulid;
/// let ulid = Ulid::from_timestamp_with_rng(0, &mut rand::thread_rng());
/// let timestamp = ulid.timestamp();
/// assert_eq!(timestamp, 0);
/// ```

The test works fine in beta and nightly but fails in stable (i.e. rustc 1.25.0 (84203cac6 2018-03-25)) with the following error message:

  |
5 | use rusty_ulid::Ulid;
  |     ^^^^^^^^^^ Maybe a missing `extern crate rusty_ulid;`?

Other code looking quite similar is working. The only difference is that the failing test code contains the line extern crate rand;.

Did I stumble over an actual bug in stable or am I doing something wrong? Is there any way to get this up and running in all three environments?

2

These tests have an implicit main function added which makes working with extern crate dependancies unintuitive. I suppose rusty_ulid is your own crate, that one is already correctly imported automatically.
It might be that the test generation algorithm on stable and beta has been improved, but hasn't been pushed to stable yet?
I'd link to rustbyeample.com for more information, but the site has been down for a while (for me).
If my google foo doesn't fail me this should be the relevant link: https://rustbyexample.com/testing/doc_testing.html

Also remember that the crates used in tests have to be listed as dev-dependancies if they are not already listed under normal dependancies.

Edit: If the implicit main is actually the problem you can solve it by implementing your own main function, just like you would write into your lib.rs or main.rs files.

3

Yes, rusty_ulid is my own crate. I should have mentioned this, sorry.

This is a working link to the Rust By Example chapter:

I already read that chapter before posting my question. Unfortunately, it didn't really help me understand the problem at hand.

I also tried my luck with Testing - The Rust Programming Language but that didn't help me either.

This is my first Rust project so I might be missing something obvious...

4

I just released the first version of the rusty_ulid crate.

It's probably easier to just look at the code in its entirety.
The documentation test in question is currently commented out and is located here:
https://github.com/huxi/rusty_ulid/blob/b56ef2e3022475c277776954f62388ea5f80d748/src/lib.rs#L156

5

The process of transforming the example to something that can be compiled and run is described here.

On stable it doesn't put the fn main at the correct place. I think this was fixed by https://github.com/rust-lang/rust/commit/b3d6597855d290d53f4f7bc80a5da07d5a5d5193

Explicitly adding the main works on stable:

    /// ```
    /// extern crate rand;
    /// # extern crate rusty_ulid;
    /// # use rusty_ulid::Ulid;
    /// # fn main() {
    /// let ulid = Ulid::from_timestamp_with_rng(0, &mut rand::thread_rng());
    ///
    /// let timestamp = ulid.timestamp();
    /// assert_eq!(timestamp, 0);
    /// # }
    /// ```
1 Like
6

That works and also helped my understanding quite a bit. Thanks!

1 Like