rust-lang / rust-lang/rust

extracted doctests that have `include!` macros cannot be compiled outside of rustdoc

Open
#143,969 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Code

Consider the following code

/// ```rust
/// const MY_STRING: &str = include_str!("my_file.txt");
/// ```
fn f() {}

If you run rustdoc to extract the tests you get something like this

cargo build

RUSTC_BOOTSTRAP=1 rustdoc \                                                                                                                             
    -Zunstable-options \
    --crate-name=a \
    --edition 2024 \
    --output-format doctest \
    --crate-type lib a/src/lib.rs \
    --extern=a=target/debug/liba.rlib \
    -Ltarget/debug \
    -Ltarget/debug/deps
{
  "format_version": 1,
  "doctests": [
    {
      "file": "a/src/lib.rs",
      "line": 1,
      "doctest_attributes": {
        "original": "rust",
        "should_panic": false,
        "no_run": false,
        "ignore": "None",
        "rust": true,
        "test_harness": false,
        "compile_fail": false,
        "standalone_crate": false,
        "error_codes": [],
        "edition": null,
        "added_css_classes": [],
        "unknown": []
      },
      "original_code": "const MY_STRING: &str = include_str!(\"my_file.txt\");",
      "doctest_code": "#![allow(unused)]\nfn main() {\nconst MY_STRING: &str = include_str!(\"my_file.txt\");\n}",
      "name": "a/src/lib.rs - f (line 1)"
    }
  ]
}

I observed the behaviour of the 2024 merged doc tests but it still seems that somehow rustdoc is using internal features to tell rustc where the src file is relative to so that include! and include_str! resolve.

Version

rustdoc 1.88.0 (6b00bc388 2025-06-23)
binary: rustdoc
commit-hash: 6b00bc3880198600130e1cf62b8f8a93494488cc
commit-date: 2025-06-23
host: x86_64-unknown-linux-gnu
release: 1.88.0
LLVM version: 20.1.5

Additional Details

Part of my working goal to get bazel project working without cargo.

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 reproducing the rustdoc command against a/src/lib.rs and inspect the extracted doctest JSON, especially doctest_code and its include_str! path. Trace the rustdoc doctest compilation entry point and compare it with the standalone extracted-test behavior; done means the reported include! and include_str! doctests compile outside rustdoc with the intended source-relative resolution.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
compilers, testing-qa, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.