bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Rollup merge of #132085 - celinval:update-smir-doc, r=compiler-errors

Browse source 
Update StableMIR doc to reflect current status

Update stable-mir documentation, since we no longer use git subtree, and we have 2 different crates.
This commit is contained in:
Jubilee 2024-10-24 23:23:55 -07:00 • committed by GitHub
commit 7782b0dd56
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 22 additions and 88 deletions
Download patch file Download diff file Expand all files Collapse all files

110
compiler/stable_mir/README.md
View file

@ -1,93 +1,33 @@
This crate is regularly synced with its mirror in the rustc repo at `compiler/rustc_smir`. This crate is currently developed in-tree together with the compiler.
We use `git subtree` for this to preserve commits and allow the rustc repo to Our goal is to start publishing `stable_mir` into crates.io.
edit these crates without having to touch this repo. This keeps the crates compiling Until then, users will use this as any other rustc crate, by installing
while allowing us to independently work on them here. The effort of keeping them in the rustup component `rustc-dev`, and declaring `stable-mir` as an external crate.
sync is pushed entirely onto us, without affecting rustc workflows negatively.
This may change in the future, but changes to policy should only be done via a
compiler team MCP.
## Instructions for working on this crate locally See the StableMIR ["Getting Started"](https://rust-lang.github.io/project-stable-mir/getting-started.html)
guide for more information.
Since the crate is the same in the rustc repo and here, the dependencies on rustc_* crates
will only either work here or there, but never in both places at the same time. Thus we use
optional dependencies on the rustc_* crates, requiring local development to use
```
cargo build --no-default-features -Zavoid-dev-deps
```
in order to compile successfully.
## Instructions for syncing
### Updating this repository
In the rustc repo, execute
```
git subtree push --prefix=compiler/rustc_smir url_to_your_fork_of_project_stable_mir some_feature_branch
```
and then open a PR of your `some_feature_branch` against https://github.com/rust-lang/project-stable-mir
### Updating the rustc library
First we need to bump our stack limit, as the rustc repo otherwise quickly hits that:
```
ulimit -s 60000
```
#### Maximum function recursion depth (1000) reached
Then we need to disable `dash` as the default shell for sh scripts, as otherwise we run into a
hard limit of a recursion depth of 1000:
```
sudo dpkg-reconfigure dash
```
and then select `No` to disable dash.
#### Patching your `git worktree`
The regular git worktree does not scale to repos of the size of the rustc repo.
So download the `git-subtree.sh` from https://github.com/gitgitgadget/git/pull/493/files and run
```
sudo cp --backup /path/to/patched/git-subtree.sh /usr/lib/git-core/git-subtree
sudo chmod --reference=/usr/lib/git-core/git-subtree~ /usr/lib/git-core/git-subtree
sudo chown --reference=/usr/lib/git-core/git-subtree~ /usr/lib/git-core/git-subtree
```
#### Actually doing a sync
In the rustc repo, execute
```
git subtree pull --prefix=compiler/rustc_smir https://github.com/rust-lang/project-stable-mir smir
```
Note: only ever sync to rustc from the project-stable-mir's `smir` branch. Do not sync with your own forks.
Then open a PR against rustc just like a regular PR.
## Stable MIR Design ## Stable MIR Design
The stable-mir will follow a similar approach to proc-macro2. It’s The stable-mir will follow a similar approach to proc-macro2. Its
implementation will eventually be broken down into two main crates: implementation is split between two main crates:
- `stable_mir`: Public crate, to be published on crates.io, which will contain - `stable_mir`: Public crate, to be published on crates.io, which will contain
the stable data structure as well as proxy APIs to make calls to the the stable data structure as well as calls to `rustc_smir` APIs. The
compiler. translation between stable and internal constructs will also be done in this crate,
- `rustc_smir`: The compiler crate that will translate from internal MIR to however, this is currently implemented in the `rustc_smir` crate.[^translation].
SMIR. This crate will also implement APIs that will be invoked by - `rustc_smir`: This crate implements the public APIs to the compiler.
stable-mir to query the compiler for more information. It is responsible for gathering all the information requested, and providing
the data in its unstable form.
This will help tools to communicate with the rust compiler via stable APIs. Tools will depend on [^translation]: This is currently implemented in the `rustc_smir` crate,
`stable_mir` crate, which will invoke the compiler using APIs defined in `rustc_smir`. I.e.: but we are working to change that.
I.e.,
tools will depend on `stable_mir` crate,
which will invoke the compiler using APIs defined in `rustc_smir`.
I.e.:
``` ```
┌──────────────────────────────────┐ ┌──────────────────────────────────┐ ┌──────────────────────────────────┐ ┌──────────────────────────────────┐
@ -104,9 +44,3 @@ This will help tools to communicate with the rust compiler via stable APIs. Tool
More details can be found here: More details can be found here:
https://hackmd.io/XhnYHKKuR6-LChhobvlT-g?view https://hackmd.io/XhnYHKKuR6-LChhobvlT-g?view
For now, the code for these two crates are in separate modules of this crate.
The modules have the same name for simplicity. We also have a third module,
`rustc_internal` which will expose APIs and definitions that allow users to
gather information from internal MIR constructs that haven't been exposed in
the `stable_mir` module.