Cranelift docs.rs build failure in 0.124.2: why the documentation disappeared and how to fix it

The cranelift-codegen 0.124.2 documentation did not vanish because docs.rs was temporarily down; it failed because the crate could not complete a docs.rs documentation build under the environment docs.rs uses for public releases. When that build breaks, the hosted API docs page shows no rendered documentation for the latest version. This tutorial explains the failure pattern, why it happens specifically on docs.rs, and how to make the crate build reliably again.

What happened on docs.rs

For the latest cranelift-codegen docs page, docs.rs attempted to compile the crate in its own sandboxed environment and failed with compilation errors. docs.rs does not simply upload prebuilt artifacts from a maintainer machine. It performs a fresh documentation build using rustdoc, a constrained Linux environment, a fixed toolchain policy, and crate metadata from the published package.

That means a crate can work locally, pass CI, and still fail on docs.rs if any of the following are true:

• The published crate is missing generated files required by documentation builds.
• The crate depends on build.rs behavior that assumes a full repository checkout rather than the packaged crate contents.
• Conditional compilation for docsrs, cfg(doc), or feature flags exposes code paths that are not normally built.
• The docs.rs environment disables assumptions your local build allows, such as external binaries, filesystem layout, or unpublished workspace members.

Understanding the Root Cause

The root cause in issues like this is usually a mismatch between crate packaging and documentation-time compilation. docs.rs builds from the uploaded crate tarball, not from the full Git repository. If cranelift-codegen relies on generated sources, ISA tables, meta-generated Rust modules, or workspace-relative files that were available during development but not included in the published package, rustdoc compilation fails.

Cranelift is particularly sensitive to this class of problem because parts of the project are often generated from shared metadata and build scripts. If version 0.124.2 published an incomplete set of generated artifacts or changed the build script assumptions, docs.rs would hit compile errors even though the repository itself may still be healthy.

Technically, this failure often comes from one or more of these patterns:

• Generated source files not included in Cargo packaging: a file exists in the repo after generation but is absent from the published crate because of include/exclude rules in Cargo.toml.
• build.rs reads files outside the crate root: this works in a workspace checkout but fails on docs.rs because only the packaged crate is available.
• Feature-sensitive APIs: documentation gets built with a feature set different from local defaults, revealing missing imports, trait impls, or modules.
• docs.rs-specific cfg branches: code under #[cfg(docsrs)] or #[cfg(doc)] can compile differently than normal builds.
• Toolchain/version drift: the released crate may compile on a newer local toolchain but fail on the docs.rs toolchain used for that release window.

In short, the bug is not really “docs.rs is broken.” The bug is that the published crate version was not fully reproducible in a docs.rs build context.

Step-by-Step Solution

The fix is to reproduce the docs.rs environment, identify the file or cfg mismatch, and publish a corrected patch release.

1. Reproduce the docs.rs build locally

Start by building documentation in a clean environment as close as possible to docs.rs. Use a packaged crate, not your workspace checkout, because that is what docs.rs actually sees.

cargo package --allow-dirty --no-verify
cargo doc --no-deps

A better reproduction path is to inspect the packaged artifact directly:

mkdir -p /tmp/cranelift-repro
cp target/package/cranelift-codegen-0.124.2.crate /tmp/cranelift-repro/
cd /tmp/cranelift-repro
tar -xf cranelift-codegen-0.124.2.crate
cd cranelift-codegen-0.124.2
cargo doc --no-deps

If the failure reproduces here, you are dealing with a published crate contents problem rather than a repository-only problem.

2. Test with docs.rs configuration enabled

docs.rs often sets RUSTDOCFLAGS and exposes cfg(docsrs). Test that path explicitly.

RUSTDOCFLAGS="--cfg docsrs" cargo doc --no-deps

If this fails while a normal cargo doc succeeds, inspect code gated on #[cfg(docsrs)] or items that become visible only during documentation generation.

3. Audit Cargo.toml packaging rules

Check whether generated files, metadata files, or source fragments are accidentally excluded. Review include, exclude, and workspace-related assumptions.

[package]
name = "cranelift-codegen"
version = "0.124.3"

# Ensure required generated sources are packaged
include = [
  "src/**",
  "build.rs",
  "Cargo.toml",
  "README*",
  "LICENSE*",
  "generated/**",
  "meta/**"
]

If the crate needs generated files, either:

• Check them into the published crate and include them explicitly, or
• Make build.rs regenerate them using only files that are also included in the package.

4. Fix build.rs to avoid workspace-only paths

A common docs.rs breakage is code like this:

let root = std::path::Path::new("..").join("shared-meta");

That can work in a monorepo checkout and fail in the packaged crate. Replace it with crate-local paths or embed the generated output into the package.

Safer patterns look like this:

use std::env;
use std::path::PathBuf;

fn main() {
    let manifest_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap());
    let meta_dir = manifest_dir.join("meta");
    let generated_dir = manifest_dir.join("generated");

    assert!(meta_dir.exists(), "meta directory must be packaged");
    assert!(generated_dir.exists(), "generated sources must be packaged");
}

5. Make docs build lighter if needed

If the crate exposes architecture-heavy internals or optional codegen backends, constrain docs.rs to a supported feature set using package metadata.

[package.metadata.docs.rs]
no-default-features = false
all-features = false
features = ["std"]
rustdoc-args = ["--cfg", "docsrs"]

This is useful when one optional feature depends on an environment docs.rs cannot provide.

6. Gate non-doc-only internals correctly

If an item is meant only for documentation visibility, use cfgs carefully so that signatures remain compilable during rustdoc passes.

#[cfg(any(doc, docsrs, feature = "std"))]
pub struct ExampleType {
    // ...
}

Be careful not to expose a public type in docs without also enabling all dependencies needed for it to compile.

7. Verify the package before republishing

Before cutting a patch release, run all three checks:

cargo check
cargo doc --no-deps
RUSTDOCFLAGS="--cfg docsrs" cargo doc --no-deps

Then test the packaged crate again:

cargo package --allow-dirty --no-verify
cd target/package
tar -xf cranelift-codegen-0.124.3.crate
cd cranelift-codegen-0.124.3
RUSTDOCFLAGS="--cfg docsrs" cargo doc --no-deps

8. Publish a patch release

Because docs.rs builds per published version, a broken release usually requires a new version such as 0.124.3. After publishing, docs.rs should rebuild the newly released crate automatically.

cargo publish

After release, verify the result on docs.rs for cranelift-codegen.

Common Edge Cases

• Generated files exist locally but are gitignored: cargo package may omit them unless they are explicitly included or generated during build from packaged inputs.
• Workspace dependency leakage: local builds can accidentally use sibling crates or files not present in the published tarball.
• Optional backend features: one backend may compile only on certain targets, but docs.rs may attempt a different documentation path than your local environment.
• Environment-variable assumptions: if build.rs expects custom variables, docs.rs will not provide them unless the crate handles missing values safely.
• rustdoc warning promotion: some projects deny warnings globally, and rustdoc-specific warnings can become hard build failures.
• Target-specific cfgs: code behind target_arch or target_feature gates may surface unresolved items during docs generation if not mirrored carefully.

If this specific Cranelift release failed because of generated metadata, the most durable fix is to ensure the generated outputs required for docs are part of the crate package and that build.rs never depends on repository-only layout.

FAQ

Why does docs.rs fail when local cargo doc works?

Because docs.rs builds from the published crate archive inside a constrained environment, not from your full repository checkout. Local builds often have extra files, workspace members, or generated artifacts that are missing from the uploaded package.

Can this be fixed without publishing a new Cranelift version?

Usually no. docs.rs builds documentation per crate version. If version 0.124.2 was published with broken documentation inputs, the normal fix is a new patch release containing corrected package contents or build logic.

What is the fastest way to catch this before release?

Run cargo package, extract the generated .crate file, and build docs from that extracted package with RUSTDOCFLAGS="–cfg docsrs". That reproduces the most common docs.rs-only failures before publishing.

The practical takeaway is simple: treat docs.rs compatibility as a packaging contract. For cranelift-codegen, the fix path is to reproduce the failure from the packaged crate, include every required generated input, remove workspace-only assumptions, and publish a corrected patch release so docs.rs can render the API docs again.