Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update StableMIR doc to reflect current status #132085

Merged
merged 3 commits into from
Oct 25, 2024
Merged

Update StableMIR doc to reflect current status #132085

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0d300ac
Update StableMIR doc to reflect current status
celinval Sep 13, 2024
f1114ba
Apply suggestions from code review
celinval Oct 24, 2024
aa2f968
Update README.md
celinval Oct 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 14 additions & 88 deletions compiler/stable_mir/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,93 +1,25 @@
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
edit these crates without having to touch this repo. This keeps the crates compiling
while allowing us to independently work on them here. The effort of keeping them in
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

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.
Our goal is to start publishing `stable_mir` into crates.io.
Until then, users will use this as any other rustc crate, via extern crate.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps mention that users need to install the rustc-dev component.

## Stable MIR Design

The stable-mir will follow a similar approach to proc-macro2. It’s
implementation will eventually be broken down into two main crates:
celinval marked this conversation as resolved.
Show resolved Hide resolved
implementation is done using two main crates:

celinval marked this conversation as resolved.
Show resolved Hide resolved
- `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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

- `stable_mir`: Public crate, to be published on crates.io, whics contains
the stable data structures and APIs to access them. It calls to `rustc_smir`.
- `rustc_smir`: This crate serves as `stable_mir`'s interface to the compiler.
It is responsible for gathering all the information requested, and converting
them to their stable data structures.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Github didn't allow me to rewrite this as an inline suggestion, but this section seems wrong. AFAICT, the rustc_smir crate is what does the conversion; hence it having all the .stable calls.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed. Not for long though, but I'll update this to match the current state. Thanks

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I documented that we are in a transition period. Let me know if that makes sense.

compiler.
- `rustc_smir`: The compiler crate that will translate from internal MIR to
SMIR. This crate will also implement APIs that will be invoked by
stable-mir to query the compiler for more information.
the stable data structure as well as calls to `rustc_smir` APIs and
translation between stable and internal constructs.
- `rustc_smir`: This crate implements the public APIs to the compiler.
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
`stable_mir` crate, which will invoke the compiler using APIs defined in `rustc_smir`. I.e.:
I.e.,
tools will depend on `stable_mir` crate,
which will invoke the compiler using APIs defined in `rustc_smir`.

I.e.:

```
┌──────────────────────────────────┐ ┌──────────────────────────────────┐
Expand All @@ -104,9 +36,3 @@ This will help tools to communicate with the rust compiler via stable APIs. Tool

More details can be found here:
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.
Loading