Choose the platforms your Rust documentation explains

A crate can have an available API that its default documentation never shows. Conditional compilation makes the platform part of what readers see. If users depend on platform-specific functions, documentation target selection belongs in the release contract. Leaving that choice to a hosting service’s defaults makes the visible API depend on a policy the crate author does not control.

The appropriate promise is modest: documentation should explain the interfaces offered on the platforms the crate claims to support. A successful documentation build does not demonstrate that those interfaces behave correctly at runtime. Those are different kinds of evidence, and combining them into a single portability badge would mislead both developers choosing a dependency and people approving its use.

The five-target list was a dated default

The 16 October 2025 docs.rs announcement replaced Intel macOS with Apple silicon and 32-bit Linux with ARM64 Linux in its default documentation builds. The resulting list was x86_64-unknown-linux-gnu, aarch64-apple-darwin, x86_64-pc-windows-msvc, aarch64-unknown-linux-gnu and i686-pc-windows-msvc. Authors could explicitly request the earlier targets.

That list is historical context. The 4 April 2026 announcement scheduled default-target-only builds from 1 May 2026 for new releases and rebuilds. Reading the older announcement as today’s continuing five-platform guarantee would therefore be unsafe. An explicit documentation policy survives this kind of service change more reliably than a remembered default.

There is also a source inconsistency worth retaining when configuring a real release. The metadata reference fetched for this article still displays the five-target default. The dated 2026 announcement describes the later change. Treat the reference as configuration documentation with that caveat, and inspect the actual release’s build results before claiming that a particular set was produced. This article does not report a build experiment.

Specify the intended reader’s entry point

The configuration lives under [package.metadata.docs.rs] in Cargo.toml. The default-target key chooses the documentation landing target; targets expresses the requested target list. Those names matter because the first page a reader opens and the complete coverage offered are related decisions, but they answer different questions. A platform-specific crate should make both decisions deliberately.

The metadata reference documents targets = [] as requesting only the default target, and describes how an unset default-target can be derived from the first entry in targets. Its current text also describes additional builds when a default target is set. The later announcement says an explicit targets list is built exactly as specified. To avoid relying on the tension between those descriptions, include the intended landing target in the explicit list and verify the resulting release pages.

Features need a separate decision. The same reference exposes features, all-features and no-default-features. A platform list does not by itself explain optional interfaces. Decide which feature combination the public documentation represents, then state that scope near the documentation link. Otherwise readers may see an attractive function and discover only during integration that the documented feature configuration differs from their own.

Check visibility before claiming portability

Start a release review with the interfaces that vary by platform. For each promised platform, ask whether a reader can find the applicable API and understand its conditions. Follow the documentation links as a consumer would. A successful job in a build dashboard is weaker evidence than checking that the relevant platform page actually contains the interface being promised.

Then review the runtime claim separately. Documentation generation cannot establish filesystem semantics, native library availability or correct interaction with a platform service. Those depend on the crate and its use. Choose runtime checks that exercise the behaviour you promise rather than treating a rendered page as a substitute. This is a proposed release practice, not a claim that any crate discussed here has failed those checks.

Support tiers also need careful interpretation. A language project’s support policy and a library’s own platform promise operate at different levels. The docs.rs announcement connects its Apple target change to Rust’s tier changes; it does not thereby certify every crate’s behaviour on Apple silicon. A library author still has to define the narrower interface and behaviour that the library is prepared to maintain.

One target can be enough

The strongest counterargument is resource cost. A crate whose interfaces are identical across its supported platforms may gain little from several documentation builds. The 2026 announcement itself motivates fewer default builds through the typical absence of target-dependent code and the resources saved. Requiring every crate to reproduce the old list would turn a useful contract into redundant work.

The recommendation applies when target choice changes what a reader needs to know. A single documentation target can be a reasonable decision for a portable interface, provided the support statement is backed by suitable evidence elsewhere. Conversely, five generated pages do not establish broader support if nobody checks their contents or maintains the corresponding platform integration.

Keep this policy small enough to use during a release. Name the intended landing target, the additional platform interfaces worth exposing and the feature combination shown. Record what was actually generated for the release under review. Separate any runtime support statement and the evidence behind it. That gives a future maintainer enough information to recognise a meaningful change in the service’s defaults.

For custom software development that depends on a Rust crate, ask for documentation matching the application’s target before committing to the integration. The useful output is a visible interface and a separately supported runtime expectation. Explicit target metadata makes the documentation decision reviewable even when the hosting service changes its default policy again.