Publishing to crates.io

Purpose and Scope

Publishing to crates.io is the point where a Rust package stops being only a local project and becomes a dependency other developers can discover, read, build, and reuse. The Rust Book frames crates.io as the registry that distributes package source code, primarily for open source packages, and it introduces publishing only after showing how Rust projects consume dependencies. This page explains that reader-facing workflow while grounding it in the Rust repository’s own documentation practices: public Rust interfaces are expected to be documented, organized, and generated consistently before they are exposed to a broader audience.

For a crate author, the practical publishing task is not just running a final Cargo command. The author needs package metadata, useful API documentation, examples that readers can trust, and a clear distinction between stable public API and unstable implementation detail. The requested source files for this page come from the Unstable Book rather than Cargo itself, so they are best read as evidence of how the Rust project documents public-facing technical surfaces. They show generated indexes, per-feature pages, tracking issues, examples, and target-specific notes, all of which mirror the discipline expected of crates published for other users.

Sources: src/tools/unstable-book-gen/src/main.rs, src/doc/unstable-book/src/language-features/lang-items.md

Relevant Source Files

• src/doc/unstable-book/src/language-features/lang-items.md — Documents the lang_items unstable feature with explanatory prose, examples, and links to compiler implementation, demonstrating the kind of public technical context that package documentation should provide before users rely on an API.
• src/tools/unstable-book-gen/src/main.rs — Generates Unstable Book summary entries and stub pages from collected feature data, showing how Rust keeps documentation coverage synchronized with source-level feature inventories.
• src/doc/unstable-book/src/compiler-flags/external-clangrt.md — Documents the external-clangrt compiler flag and links it to sanitizer behavior, serving as a compact example of option-level documentation for users who need precise build behavior.
• src/doc/unstable-book/src/language-features.md — Defines the Language features section boundary in the Unstable Book, which is part of the repository’s structured documentation surface.
• src/doc/unstable-book/src/language-features/abi-cmse-nonsecure-call.md — Documents a target-specific unstable ABI with motivation, constraints, and generated assembly, illustrating how specialized APIs need examples and platform context.
• src/doc/unstable-book/src/language-features/abi-msp430-interrupt.md — Documents another target-specific ABI with a concrete code sample and object dump output, showing how documentation can make low-level behavior reviewable by users.

Publishing Workflow

The Rust Book’s publishing chapter starts from a simple premise: users have already depended on crates from crates.io, and they can also share their own packages there. That framing matters because crates.io publishing is a social and maintenance action, not only a technical upload. A crate becomes part of another project’s dependency graph, documentation set, security review, and build process. Before publishing, authors should inspect the package as a future user would: is the public API intentional, is the crate name meaningful, and can someone understand the crate without reading its private implementation?

A typical publishing flow begins with a Cargo package that already builds and has a library or binary interface worth sharing. The package’s manifest identifies the crate, version, edition, dependencies, and metadata used by registry and documentation tooling. The Book emphasizes documentation comments because they generate HTML documentation for public API items, aimed at programmers who want to use the crate rather than understand its internals. In practice, that means writing /// comments directly before public functions, types, modules, traits, and constants, and including Markdown sections such as examples when they clarify usage.

The Rust repository’s Unstable Book material reinforces this same expectation from a first-party perspective. The lang_items page does not merely name a feature; it explains that rustc has pluggable operations marked with #[lang = "..."], identifies examples such as operator traits, panicking, unwinding, marker traits, and allocation, and includes a freestanding Box example. A published crate should aspire to a similar standard at its own scale: define the concept, identify the public contract, explain when users need it, and include code that demonstrates correct use.

Sources: src/doc/unstable-book/src/language-features/lang-items.md

The final registry operation is usually performed with Cargo after the author has an account and API token for crates.io. The common command sequence is to authenticate with Cargo, package-check the crate, and publish only when the metadata, version, license, README, and documentation are ready. A concise workflow looks like this:

cargo login <api-token>
cargo package
cargo publish

Treat cargo package as a release review step rather than a formality. It creates the archive that Cargo would upload and helps reveal missing files, bad metadata, or accidental assumptions about local paths. After a successful publish, the crate version is immutable in the registry model: authors normally publish a new version for changes instead of replacing an existing upload. If a release should not be selected by dependency resolution, Cargo supports yanking a version, but yanking is a compatibility signal rather than deletion of source code already published.

Documentation and Public API Quality

Good crates.io packages reduce surprise. The Book explicitly calls out documentation comments as a feature that makes packages easier to find and use, because generated HTML is part of how Rust users evaluate APIs. The Rust tree’s generated unstable documentation shows a complementary mechanism: src/tools/unstable-book-gen/src/main.rs collects unstable language features, library features, compiler flags, and environment variables, then writes summary content and missing stub pages. That generator encodes a policy that discoverable public surfaces should not silently drift away from their documentation.

Sources: src/tools/unstable-book-gen/src/main.rs

For a crate author, the equivalent habit is to make documentation part of the release process. Public items should have comments that explain behavior, invariants, errors, safety requirements, and examples. If the crate exposes optional capabilities through Cargo features, document the feature names in the README and API docs. If the crate supports a narrow platform, target, or ABI, explain that up front. The Unstable Book ABI pages are good examples of this style because they identify the target architecture, state what the ABI changes, and show code that only makes sense under the relevant target constraints.

Sources: src/doc/unstable-book/src/language-features/abi-cmse-nonsecure-call.md, src/doc/unstable-book/src/language-features/abi-msp430-interrupt.md

The abi_cmse_nonsecure_call page is especially useful as a documentation model for specialized crates. It explains the TrustZone-M context, identifies the thumbv8m target-family signal, describes what the compiler does for calls using the ABI, and shows both Rust source and assembly output. A published embedded or FFI crate benefits from the same pattern: name the platform, describe the contract, show the user-facing syntax, and include enough output or behavior detail for readers to confirm they configured the build correctly.

The external-clangrt compiler flag page shows the opposite extreme: a small, focused option page can still be valuable when it states the behavior precisely and points to the larger concept it modifies. It says the flag controls whether the compiler links its own runtime library for sanitizers and that passing it makes the compiler not link its own library. For crates.io packages, short documentation is acceptable when the scope is narrow, but it still needs to tell readers what changes, when to use it, and where to learn the surrounding model.

Sources: src/doc/unstable-book/src/compiler-flags/external-clangrt.md

Repository Documentation Pattern Applied to Crates

The Unstable Book generator uses ordered sets and collected feature inventories to build a summary and create stub pages for undocumented unstable features. That is not the same as publishing to crates.io, but it is a strong repository signal about release hygiene: public names are gathered, compared against existing documentation files, and emitted into a navigable book structure. A crate maintainer can apply the same idea manually by keeping a checklist of public modules, features, command-line options, or environment variables and ensuring every released public surface has documentation.

The src/doc/unstable-book/src/language-features.md file is minimal, but its existence as a section boundary matters. Documentation systems often need both detailed leaf pages and stable navigation nodes. For a crates.io package, that usually maps to a README, crate-level docs, module docs, and item-level docs. The README helps users decide whether to add the dependency; crate-level docs explain the mental model; module docs organize the API; and item-level docs answer exact usage questions in generated rustdoc.

Sources: src/doc/unstable-book/src/language-features.md

A release-ready crate should therefore be reviewed through two lenses. The Cargo lens asks whether the package can be built, packaged, versioned, licensed, and uploaded correctly. The documentation lens asks whether users can discover and apply the API without relying on private knowledge. The Rust repository evidence for this page is weighted toward the second lens, but that is exactly the part many new publishers underestimate. The registry can host the source, yet the documentation determines whether the source is usable by strangers.

Compact Reference

Use this checklist for a crate release: build and test locally, review the manifest metadata, run cargo package, inspect the packaged contents, confirm generated documentation, authenticate with crates.io, then run cargo publish. After publishing, verify the crate page and docs render as expected, and reserve yanking for versions that should remain available but no longer be selected by new dependency resolution.

Next Steps

If you are preparing your first public crate, read the Rust Book’s publishing chapter alongside the Cargo manifest and workspace documentation. Then review your crate as if it were an unfamiliar dependency: start from the README, open the generated docs, copy the examples into a fresh project, and check whether platform or feature requirements are explicit. For repository contributors, the Unstable Book sources on this page are useful examples of how Rust documents unstable public surfaces before users build against them.