Please consider adding documentation on the internal architecture

[oligamiq]

It would be great to have documentation explaining how this works. After spending about 2 hours investigating the code and issues, I’ve gathered the following points:

• The sysroot is being compiled into MIR (but, you say modified standard library so I miss understanding).
• Dependency libraries are also being executed by the interpreter.
• There seems to be some kind of caching mechanism (changes to library files are not reflected unless a clean is performed).
• Dummy files are being generated without compilation.
• It appears to be related to rustc’s compile-time constants (https://rustc-dev-guide.rust-lang.org/const-eval/interpret.html).

However, I’m still not entirely sure how everything fits together. Also, some parts are deeply tied to rustc, making it challenging to read through the code.

Having documentation available would be greatly appreciated.

[RalfJung]

Thanks for your interest in Miri!

We don't have the resources to write and maintain a fully in-depth documentation of all the inner workings and implementation details of Miri. Such a document could easily fill a book. We do have documentation on how to use Miri and how to work on Miri, which doesn't seem to be what you are looking for, but it makes the issue title misleading by making it sound like we have no documentation.

So the question is: what would be the goal of this documentation? What is it you are trying to achieve? If you merely want to use Miri, most of these questions should not matter.

[oligamiq]

Miri is the most advanced implementation of an interpreter for Rust's mid-level intermediate representation. Therefore, I want to customize it, fork it, reference it, or contribute to it. This is why I need documentation.

The documentation I am seeking includes, among other things, an overview of the first two aspects mentioned above and systems that have been extracted outside of repositories like rustc. Without a clear understanding of the system's overall structure, it becomes quite challenging to delve into the code, hence the need for documentation.

It is very difficult, especially when the code you want to refer to may even be in RUSTC.

I would like at least a document that clearly outlines the responsibilities of the relevant code within rustc and the responsibilities of the code within this repository.

[RalfJung]

Okay, so it's mostly about the large-scale internal architecture. We do have plenty of comments explaining local small-scale concerns, and we have user-facing docs, but we don't have an architecture overview.

That's a fair point. However, I'm not sure I'll be able to prioritize it any time soon.

This depends on #4108 -- we'd need a good place to put those kinds of docs first.