How to release related crates with fake (dev-dependency) cycle?

help
1

I have a workspace of several crates. One of them is kind of a core, others are plugins. So, when you use it, you'd depend on the core and some of the plugins, depending on functionality you'd need.

Now, I want to use a plugin in an example of the core (because the core is kind of useless on its own, you need some plugins to see what it does).

For that to work, I have dependencies like:

  • The plugin depends on core.
  • The core doesn't directly depend on any plugin, but dev-depends on it.

This works fine in a local workspace. But I don't seem to be able to release the crates on crates.io.

First I attempted to release without versions (only with path = ) inside the dev dependencies. Cargo refused that, saying that to publish a crate, I need to specify versions for all dependencies (even the dev ones, which seems to be unnecessary).

If I add the versions, it tells me such version is not on crates.io yet (well, of course, I would be releasing that one next).

I don't see a way to release them "atomically".

Is there a trick I'm missing? Or is my only chance to exclude the examples, which would be a pity?

The stuff I have is this: https://github.com/vorner/spirit/

Thanks for any directions what to try or explanations why this makes no sense.

2

AFAIK examples aren't usable in crates-io crates anyway, so removing it from the published package doesn't lose anything.

You could temporarily comment it out and publish with --allow-dirty.

3

That probably can be a workaround for this time I guess (it'll still be a bit annoying to do every time), thanks for that hint.

Are there plans for docs.rs to have a [run] button with examples some day?

4

I can't speak for docs.rs, but from my experience in building crates.rs I think it'd be unlikely to reliably work without using git as the source for the example files, rather than the crate. And correlation of crate versions with git commits is also unreliable, so the whole thing would need changes in cargo/crates-io publishing model first.

There are two conflicting ways of thinking about crates-io crates:

  1. Minimal package with only necessary files to build the library (use of include/exclude is encouraged, small packages are preferred). cargo publish can even automagically make readme and metadata available on crates-io even if this data is missing from the crate tarball! (e.g. readme = "../readme.md" is a common pattern used in crates).

  2. Complete snapshot of the package at the time. That's what you'd need for runnable examples, runnable tests, etc. (and these may require extra data files to use as examples or test cases).

I'm not sure which one is the official preferred way, but actual published crates are a mix of both.

5

To be clear, I'm actually talking about in-documentation examples, eg:

/// Some struct
///
/// Blabla...
///
/// ```rust
/// do_stuff();
/// ```

These will get rendered on docs.rs and I've seen mdbook being able to generate links to eg. playground, so I *thought* docs.rs might want something like that in the future.

But yes, throwing the dev-dependencies out for release worked for me. Maybe they should just be ignored by cargo publish?
6

Ahh, in that case you can mock something in lines prepended with #, which are hidden in the docs.

Whether the docs should be built with dev deps available is an interesting question.