Rust Edition Guide は現在 Rust 2024 のアップデート作業に向けて翻訳作業中です。本ページはある時点での英語版をコピーしていますが、一部のリンクが動作しない場合や、最新情報が更新されていない場合があります。問題が発生した場合は、原文（英語版）をご参照ください。

Rustdoc nested include! change

Summary

When a doctest is included with include_str!, if that doctest itself also uses include!, include_str!, or include_bytes!, the path is resolved relative to the Markdown file, rather than to the Rust source file.

Details

Prior to the 2024 edition, adding documentation with #[doc=include_str!("path/file.md")] didn't carry span information into any doctests in that file. As a result, if the Markdown file was in a different directory than the source, any paths included had to be specified relative to the source file.

For example, consider a library crate with these files:

  • Cargo.toml
  • README.md
  • src/
    • lib.rs
  • examples/
    • data.bin

Let's say that lib.rs contains this:

#![doc=include_str!("../README.md")]

And assume this README.md file:

```
let _ = include_bytes!("../examples/data.bin");
//                      ^^^ notice this
```

Prior to the 2024 edition, the path in README.md needed to be relative to the lib.rs file. In 2024 and later, it is now relative to README.md itself, so we would update README.md to:

```
let _ = include_bytes!("examples/data.bin");
```

Migration

There is no automatic migration to convert the paths in affected doctests. If one of your doctests is affected, you'll see an error like this after migrating to the new edition when building your tests:

error: couldn't read `../examples/data.bin`: No such file or directory (os error 2)
 --> src/../README.md:2:24
  |
2 | let _ = include_bytes!("../examples/data.bin");
  |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  = note: this error originates in the macro `include_bytes` (in Nightly builds, run with -Z macro-backtrace for more info)
help: there is a file with the same name in a different directory
  |
2 | let _ = include_bytes!("examples/data.bin");
  |                        ~~~~~~~~~~~~~~~~~~~

To migrate your doctests to Rust 2024, update any affected paths to be relative to the file containing the doctests.