feature-manifest

feature-manifest is a Rust crate and Cargo subcommand for documenting, validating, and rendering Cargo feature flags.

Cargo feature tables are precise enough for builds, but often too terse for users. A crate can start with:

[features]

default = ["serde"]

serde = ["dep:serde"]

tokio = ["dep:tokio"]

Then keep the missing intent beside it:

[package.metadata.feature-manifest.features]

serde = { description = "Enable Serialize and Deserialize support." }

tokio = { description = "Enable Tokio-backed async APIs." }

From there, feature-manifest can generate a README feature table and fail CI when the table drifts:

cargo fm markdown --insert-into README.md
cargo fm markdown --check --insert-into README.md

This repository uses cargo fm in CI to keep its own feature metadata and generated README section in sync.

Should I Use This?

Use it if:

• your crate has more than a few public features,
• your README or docs.rs page has a feature table,
• feature documentation drifts during releases,
• your workspace repeats feature patterns across packages.

Probably skip it if:

• your crate has no optional features,
• all features are internal and intentionally undocumented,
• you do not want feature metadata in Cargo.toml.

Installation

From crates.io:

cargo install feature-manifest

This installs both cargo-feature-manifest and the short alias cargo-fm. feature-manifest currently requires Rust 1.85 or newer because it uses the 2024 edition. Since it runs as a developer tool, that does not change the MSRV of crates it checks.

Use the short Cargo subcommand:

cargo fm

The original long form still works:

cargo feature-manifest

From source:

git clone https://github.com/funwithcthulhu/feature-manifest.git
cd feature-manifest
cargo install --path .

Minimum Adoption

cargo install feature-manifest
cargo fm init --dry-run
cargo fm init
cargo fm markdown --insert-into README.md
cargo fm markdown --check --insert-into README.md

Common Commands

cargo fm check
cargo fm init --dry-run
cargo fm doctor --explain
cargo fm markdown --write FEATURES.md
cargo fm markdown --check --insert-into README.md
cargo fm json
cargo fm graph
cargo fm sync --diff
cargo fm explain <feature>

The default command is check, so cargo fm and cargo feature-manifest are both valid shorthand.

See the generated CLI reference for the full command surface, including schemas, completions, and lint-reference generation.

Short aliases are available for daily use:

• check -> c, chk
• markdown -> md, m
• json -> j
• graph -> g, viz
• sync -> s
• explain -> show, x
• list-lints -> lints

Workspace Support

Point the tool at a workspace root or a single crate:

cargo fm --workspace check --manifest-path path/to/workspace
cargo fm --package my-crate explain serde --manifest-path path/to/workspace
cargo fm markdown --manifest-path path/to/crate

When a workspace has multiple members, the default behavior is intentionally strict: you must choose --workspace or --package <name>.

Markdown Output and Injection

Write a generated document directly:

cargo fm markdown --write FEATURES.md

Inject generated Markdown into an existing README using markers:

<!-- feature-manifest:start -->


# feature-manifest feature manifest


Default feature set: _none_

| Feature | Default | Visibility | Status | Category | Enables | Description |
| --- | --- | --- | --- | --- | --- | --- |
<!-- feature-manifest:end -->

Then run:

cargo fm markdown --insert-into README.md

Check whether generated docs are stale:

cargo fm markdown --check --insert-into README.md

Custom markers are supported with --start-marker and --end-marker.

Additional Output Formats

check supports multiple output formats:

• text: default human-readable output
• json: machine-readable structured report
• github: GitHub Actions workflow commands
• sarif: SARIF 2.1.0 for code scanning pipelines

Example:

cargo fm check --format sarif > feature-manifest.sarif

GitHub annotations include manifest line numbers when the relevant feature, metadata entry, or group can be located.

Lint Configuration

feature-manifest lints can be configured in Cargo.toml:

[package.metadata.feature-manifest.lints]

missing-description = "deny"

small-group = "allow"

private-enabled-by-public = "warn"

For staged adoption or strict CI defaults:

[package.metadata.feature-manifest]

preset = "adopt"

You can also override them per-run:

cargo fm check --lint missing-description=warn
cargo fm check --preset strict

For stricter project setup checks:

cargo fm doctor --strict
cargo fm doctor --explain

See docs/lints.md for the generated lint reference.

Stability

The CLI and metadata format are the primary supported surface before 1.0. The library API is public for integration tests and early tooling, but it may still move while the crate is pre-1.0. See the 1.0 roadmap for the stabilization checklist.

Documentation

• Start using it: Getting started, CI setup, Adoption recipes, Cookbook
• Metadata and output: Metadata format, Lint reference, JSON schema, Generated CLI reference
• Migration examples: Before and after adoption, Compatibility and migration, Real-world patterns
• Project and policy: Architecture, Supply-chain trust, 1.0 roadmap, Security policy, Contributing guide, Support

Example metadata snippets live in examples.

Contributing

Development setup, test guidance, and release steps live in CONTRIBUTING.md and docs/releasing.md.

License

Licensed under either of the following, at your option:

• Apache License, Version 2.0
• MIT license