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.)

1 post - 1 participant

Read full topic