rust-lang / rust-lang/rust

Run merged doc-tests by default in the same process and add opt-out attribute

Open
#129,119 18 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

C-discussion T-rustdoc
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

https://github.com/rust-lang/rust/pull/126245 merged support in Edition 2024 for consolidating doctests into as few binaries as possible, with an opt-out of a standalone attribute.

I propose by default doc-tests should be run in parallel in the same process.

What's the motivation for the proposed change? For example when working on the Rust standard library, I usually run the tests for core and std/alloc, that takes incremental ~84s on my Zen 3 5900X machine. Out of that ~66s are spent running the ~4k core doc tests. That's on Linux, on Windows I expect this to be even slower, due to a higher process spawning overhead. Merged doc tests is tied to the Rust 2024 edition because it can break behavior. So there is already precedent for having a new default that is better in the common case, but may break existing projects that opt into the new edition, requiring some work. I believe and doing some code analysis via grep.app would support that the majority of doc tests can be run in parallel in the same binary. So that should be the default. For the cases that depend on some kind of singleton, log lib init, etc. they can be marked with an attribute as requiring a standalone process. That would make for two possible attributes: build isolated and run isolated. If this is deemed too complex, it's imaginable that there is only a single attribute that implies both build and run isolated.

Tagging @GuillaumeGomez

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 reading the merged PR 126245 and its Edition 2024 doctest consolidation support, focusing on how the existing standalone attribute works. Determine the design for running doctests in parallel within one process, including whether separate build and run opt-outs are needed, and define completion by documenting and validating the new default and compatibility behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
compilers, testing-qa
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.