rust-lang / rust-lang/rust

doc reproducibility

Open
#156,567 10 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-reproducibility C-bug T-rustdoc
Dominant language
Rust
Stars
119k
Forks
16.1k
PR metrics pending

Description

Summary

Debian is starting to step up its reproducibility game. Unfortunately, at the moment rust-doc and cargo-doc are not 100% reproducible. I've minimized the invocations/behaviour for upstream main.

Command used
./x.py -j1 doc --stage 2 && ./x.py -j1 doc --stage 2 cargo

./x.py -j16 doc --stage 2 && ./x.py -j16 doc --stage 2 cargo

I haven't verified yet whether it's actually the difference in parallelism triggering it, or whether it just makes it more likely.

Expected behaviour

I expect the generated html files to be identical given the same input tree and toolchain (e.g., two back to back invocations, just clearing build artifacts).

Actual behaviour

They are (sometimes) not, sample diff:

diff -up ../{first,second}/doc/alloc/alloc/fn.alloc.html
--- ../first/doc/alloc/alloc/fn.alloc.html      2026-05-14 10:13:28.533447849 +0200
+++ ../second/doc/alloc/alloc/fn.alloc.html     2026-05-14 12:22:55.126794897 +0200
@@ -1,4 +1,4 @@
-<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Allocates memory with the global allocator."><title>alloc in alloc::alloc - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../static.files/rustdoc-17e0aaed.css"><meta name="rustdoc-vars" data-root-path="../../" data-static-root-path="../../static.files/" data-current-crate="alloc" data-themes="" data-resource-suffix="1.97.0" data-rustdoc-version="1.97.0-nightly (c8c4c83d5 2026-05-13)" data-channel="nightly" data-search-js="search-b5634cc7.js" data-stringdex-js="stringdex-2da4960a.js" data-settings-js="settings-170eb4bf.js" ><script src="../../static.files/storage-41dd4d93.js"></script><script defer src="sidebar-items1.97.0.js"></script><script defer src="../../static.files/main-aa4d37ac.js"></script><noscript><link rel="stylesheet" href="../../static.files/noscript-f7c3ffd8.css"></noscript><link rel="alternate icon" type="image/png" href="../../static.files/favicon-32x32-eab170b8.png"><link rel="icon" type="image/svg+xml" href="../../static.files/favicon-044be391.svg"></head><body class="rustdoc fn"><a class="skip-main-content" href="#main-content">Skip to main content</a><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">alloc</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><a class="logo-container" href="../../alloc/index.html"><img class="rust-logo" src="../../static.files/rust-logo-9a9549ea.svg" alt="logo"></a><h2><a href="../../alloc/index.html">alloc</a><span class="version">1.97.0-nightly</span></h2></div><div class="version">(c8c4c83d5     2026-05-13)</div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">alloc</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#safety" title="Safety">Safety</a></li><li><a href="#examples" title="Examples">Examples</a></li></ul></section><div id="rustdoc-modnav"><h2><a href="index.html">In alloc::<wbr>alloc</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content" tabindex="-1"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../index.html">alloc</a>::<wbr><a href="index.html">alloc</a></div><h1>Function <span class="fn">alloc</span>&nbsp;<button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><span class="since" title="Stable since Rust version 1.36.0">1.36.0</span> · <a class="src" href="../../src/alloc/alloc.rs.html#95-103">Source</a> </span></div><pre class="rust item-decl"><code>pub unsafe fn alloc(layout: <a class="struct" href="struct.Layout.html" title="struct alloc::alloc::Layout">Layout</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.pointer.html">*mut </a><a class="primitive" href="https://doc.rust-lang.org/nightly/core/primitive.u8.html">u8</a></code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Allocates memory with the global allocator.</p>
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="Allocates memory with the global allocator."><title>alloc in alloc::alloc - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../static.files/rustdoc-17e0aaed.css"><meta name="rustdoc-vars" data-root-path="../../" data-static-root-path="../../static.files/" data-current-crate="alloc" data-themes="" data-resource-suffix="1.97.0" data-rustdoc-version="1.97.0-nightly (c8c4c83d5 2026-05-13)" data-channel="nightly" data-search-js="search-b5634cc7.js" data-stringdex-js="stringdex-2da4960a.js" data-settings-js="settings-170eb4bf.js" ><script src="../../static.files/storage-41dd4d93.js"></script><script defer src="sidebar-items1.97.0.js"></script><script defer src="../../static.files/main-aa4d37ac.js"></script><noscript><link rel="stylesheet" href="../../static.files/noscript-f7c3ffd8.css"></noscript><link rel="alternate icon" type="image/png" href="../../static.files/favicon-32x32-eab170b8.png"><link rel="icon" type="image/svg+xml" href="../../static.files/favicon-044be391.svg"></head><body class="rustdoc fn"><a class="skip-main-content" href="#main-content">Skip to main content</a><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">alloc</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><a class="logo-container" href="../../alloc/index.html"><img class="rust-logo" src="../../static.files/rust-logo-9a9549ea.svg" alt="logo"></a><h2><a href="../../alloc/index.html">alloc</a><span class="version">1.97.0-nightly</span></h2></div><div class="version">(c8c4c83d5     2026-05-13)</div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">alloc</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#safety" title="Safety">Safety</a></li><li><a href="#examples" title="Examples">Examples</a></li></ul></section><div id="rustdoc-modnav"><h2><a href="index.html">In alloc::<wbr>alloc</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content" tabindex="-1"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../index.html">alloc</a>::<wbr><a href="index.html">alloc</a></div><h1>Function <span class="fn">alloc</span>&nbsp;<button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><span class="since" title="Stable since Rust version 1.36.0">1.36.0</span> · <a class="src" href="../../src/alloc/alloc.rs.html#95-103">Source</a> </span></div><pre class="rust item-decl"><code>pub unsafe fn alloc(layout: <a class="struct" href="struct.Layout.html" title="struct alloc::alloc::Layout">Layout</a>) -&gt; <a class="primitive" href="../../core/primitive.pointer.html">*mut </a><a class="primitive" href="../../core/primitive.u8.html">u8</a></code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Allocates memory with the global allocator.</p>
 <p>This function forwards calls to the <a href="trait.GlobalAlloc.html#tymethod.alloc" title="method alloc::alloc::GlobalAlloc::alloc"><code>GlobalAlloc::alloc</code></a> method
 of the allocator registered with the <code>#[global_allocator]</code> attribute
 if there is one, or the <code>std</code> crate’s default.</p>

(The reference from alloc to core is to the internet in the first, and relative with a local path in the second output)

Bootstrap configuration (bootstrap.toml)
# See bootstrap.example.toml for documentation of available options
#                                                                                                                                                                                             profile = "dist"  # Includes one of the default files in src/bootstrap/defaults                                                                                                               change-id = 154587                                                                                                                                                                            llvm.download-ci-llvm = true

[build]
docs = true
Operating system

Debian Trixie (13.5)

HEAD

c8c4c83d57d3b4cf72a7306cd77bb8b5c0f03434 , but we've seen this behaviour in Debian builds for quite a while already, so it's not a recent regression.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by rerunning the two ./x.py -j1 and -j16 doc --stage 2 commands described in the issue, clearing build artifacts between runs. Compare the generated alloc HTML and inspect bootstrap.toml and the rustdoc output paths involved in the differing links. Done means repeated builds from the same input produce identical HTML, including consistent local references.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
build-system, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.