Guidance on isolating a crate from its optional dependencies (alternative: a crate family)

During the development of a library, I found the question asking for Guidance on optional functionality: crates vs features here in the forum.

The answers given there focused on two topics: "Features need to be additive"; and "The discoverability and self-documenting abilities of features are really really poor".

Both are not a problem for me, so I used features, and ignored the answer saying "Where I work, we've stopped using features with our code. It's not something being dictated. It's just natural selection".

Then, the 1.100-beta and its nighty predecessors came, together with the 1.100-beta regression: expected Global, found type parameter A. One of my dependencies (crate btree_monstrousity) fails (see beta-rustdoc-1.100 - Crater report ) when the docs of my library are compiled with the nightly rustc 1.99.0. for all features, as docs.rs would do it to document the API added by the features.

My question is now:

Is there any guidance on decoupling a crate’s successful use from future failures of its optional dependencies? Or is a crate family the better option for this goal?

With isolating I mean: The crate and its other features should remain fully usable if some dependency is not usable anymore. usable includes tests still showing that the crate and the remaining features / optional dependencies are ok and docs still build ok and document their use.

--

My best guess so far is:

  1. Document the optional API parts manually and tell rustdoc not to document them automatically
    (...because this could fail when building optional dependencies)
  2. Split the CI tests in a core part (not using the features and their optional dependencies) and in separate runs with the different features
    (...so users can see what still works and what does not).

In this situation, using a family of crates, one for the core and others for features, seems to me like the easier way...

Or maybe mixing the approaches?

In my project, I port my python package NoGraphs to rust, offering a high degree of flexibility, even w.r.t. the dependencies needed for increased performance. Here, the mix could look like this:

  • Features (“Because I fully believe in the stability and future of these libraries, including tests and doc builds?”)
    • std
    • hashbrown (hashtable used; support of no-std)
    • indexmap
    • rayon
  • Feature-crates (“Because I have doubts here??”):
    • btree_monstrosity
    • dashmap
    • clashmap
    • papaya
    • once_map
    • scc
    • append-only-vec
    • boxcar

(I invested hundreds of hours in my project so far, but I am not using Rust professionally, so I am not an expert. Please take this into account when interpreting my question. Thanks.)

Features are already sufficient to decouple usage of a library, with a specific feature set, from failure of its optional dependencies to build. (For example, many libraries have optional features that only compile on certain platforms, whether directly or due to dependencies — so, it is expected, not a bug, that enabling certain features would fail the build.) The only way in which features breaking inconveniences people not using that feature is that docs.rs builds that enable all features might fail.

For maintenance, rather than usage, it’s your task as the maintainer of a library to, if a dependency becomes broken, to either remove that dependency, or work with that other library’s maintainer to get it fixed.

All that said, you are entirely right that having a family of packages, instead of one package with features, is a way to reduce risks, and not only from broken dependencies — it also means you can avoid silent bugs from mis-written cfg conditions, by not needing to write any of those conditions. But it also has disadvantages; your separate crates have to obey the rules of separate crates and can’t cooperate as closely as code in the same crate:

  • There is no equivalent of pub(crate) visibility for multiple crates; at most you can do #[doc(hidden)] pub, but you lose dead code detection for such items.

  • #[non_exhaustive] is enforced at the crate boundary.

  • Your trait implementations have to obey the orphan rules.

  • A crate family can’t be versioned in lockstep.[1] Suppose that you have published A v1.3.0 and B v1.3.0, and B depends on A. Then, suppose you release v1.4.0 of both libraries. Then, if B’s dependency is A = ["1.4.0"], B can rely on seeing the newer A, but the reverse is not true; the build graph could contain A v1.4.0 but B v1.3.0. This can result in issues like:

    • You removed a #[doc(hidden)] pub implementation detail item from A, but B is still the old version and therefore still using it.
    • Macros in proc-macro library A written to work with items defined in B may use items that don’t exist yet.
    • A non_exhaustive enum in A that was supposed to be completely handled in B may gain a new variant that isn’t handled.

    These examples may sound esoteric, but things like this can come up when you are writing code that is designed as a single library with close cooperation between its parts, but published as multiple packages.

Because of all of these issues, you should not just consider robustness and API surface, but also on how closely coupled the code you are considering splitting is.


  1. except by routinely releasing incompatible versions, which inconveniences your dependents and hampers the growth of a dependent ecosystem ↩︎