Issue #978: A package published as a Rust library: artifact = "rust-library" and [features] whose roots are modules or pub items (blocks #928)

Open and answer this issue on GitHub.

ready · opened 2026-10-29 · updated 2026-10-29 · 0 comments

Why

The yaml package (#928) ships to Rust users as one crate, nikaia-yaml, with the features serde (default), tree and stream. Its parts:

• nikaia-yaml is the hand-written serde_yaml facade. It depends on a crate generated from the Nikaia package, an implementation detail like serde_derive.
• Both crates carry the same version.
• One crate rather than several keeps the migration to one line and keeps stars, downloads and issues in one place.

Today a package can only become a program or a C library (artifact = "c-library"). A C library loses the Rust types and zero-copy, and a package cannot say which of its parts a Rust user may switch off.

Decided (owner, 2026-10-29)

1. artifact = "rust-library". The package’s lowered Rust is written as an ordinary library crate with a public API. It depends on nikaia-std and is usable as a path dependency, and published once nikaia-std is.

2. [features] in nikaia.toml:

[features]
default = ["serde"]
tree    = ["yaml::tree"]            # a module: all its pub items
stream  = ["yaml::stream"]
serde   = ["yaml::serde"]
# a single pub item is a root too: "yaml::tree::Value"

• Roots: A feature is a set of public roots. Each root is a module, meaning all its pub items, or a single pub item such as a function or a type.
• Reachability: Everything a root reaches comes with it: helpers, types, grammar entries. Nobody marks helpers.
• Not in any feature: A pub item in no feature is always present (the core).
• Implications between features are derived, not written. If yaml::serde reaches yaml::tree, then serde ⇒ tree, recorded in the ledger and written into the generated Cargo.toml.
• Optional dependencies are derived the same way. A dependency reached only from a feature’s roots is optional, behind that feature.
• Grammar versions too: a grammar entry reached only from stream with a reader gets its streaming version only under stream. This is the per-grammar or per-entry switch requested from winnow-grammar.
• No #[cfg] in the code. A feature decides only whether something is there, never how it behaves, so features are additive by construction.
• Without [features], everything public is exported, as today.
• Scope: Features act only on rust-library and on the bindings (nikaia bind). A Nikaia program using the package needs none, because the compiler already emits only what the program uses.
• Checks: The compiler checks each feature alone, and all together. A root that does not compile without a feature it needs is refused with a Nikaia diagnostic.

To build

1. ADR plus the Part III text (manifest, artifact, [features], the checks), with its NK codes.
2. artifact = "rust-library": write the lowered package as a crate (lib target, public API, nikaia-std dependency). Test: a small package used from a Rust crate in the repository.
3. [features]: roots, reachability, derived implications and optional dependencies, #[cfg(feature)] written into the lowered crate, the generated Cargo.toml, and the check of every feature alone and all together. Test: a package with a module root, an item root, an implication and an optional dependency.
4. Features in nikaia bind (a binding without the parts that are switched off).

The commit that builds the last step says Fixes #N.

Back to Open Issues