Skip to content

Commit 7782b0d

Browse files
workingjubileeworkingjubilee
authored
Rollup merge of #132085 - celinval:update-smir-doc, r=compiler-errors
Update StableMIR doc to reflect current status Update stable-mir documentation, since we no longer use git subtree, and we have 2 different crates.
2 parents fd78b67 + aa2f968 commit 7782b0d

1 file changed

Lines changed: 22 additions & 88 deletions

File tree

‎compiler/stable_mir/README.md‎

Lines changed: 22 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,93 +1,33 @@
1-
This crate is regularly synced with its mirror in the rustc repo at `compiler/rustc_smir`.
1+
This crate is currently developed in-tree together with the compiler.
22

3-
We use `git subtree` for this to preserve commits and allow the rustc repo to
4-
edit these crates without having to touch this repo. This keeps the crates compiling
5-
while allowing us to independently work on them here. The effort of keeping them in
6-
sync is pushed entirely onto us, without affecting rustc workflows negatively.
7-
This may change in the future, but changes to policy should only be done via a
8-
compiler team MCP.
3+
Our goal is to start publishing `stable_mir` into crates.io.
4+
Until then, users will use this as any other rustc crate, by installing
5+
the rustup component `rustc-dev`, and declaring `stable-mir` as an external crate.
96

10-
## Instructions for working on this crate locally
11-
12-
Since the crate is the same in the rustc repo and here, the dependencies on rustc_* crates
13-
will only either work here or there, but never in both places at the same time. Thus we use
14-
optional dependencies on the rustc_* crates, requiring local development to use
15-
16-
```
17-
cargo build --no-default-features -Zavoid-dev-deps
18-
```
19-
20-
in order to compile successfully.
21-
22-
## Instructions for syncing
23-
24-
### Updating this repository
25-
26-
In the rustc repo, execute
27-
28-
```
29-
git subtree push --prefix=compiler/rustc_smir url_to_your_fork_of_project_stable_mir some_feature_branch
30-
```
31-
32-
and then open a PR of your `some_feature_branch` against https://github.com/rust-lang/project-stable-mir
33-
34-
### Updating the rustc library
35-
36-
First we need to bump our stack limit, as the rustc repo otherwise quickly hits that:
37-
38-
```
39-
ulimit -s 60000
40-
```
41-
42-
#### Maximum function recursion depth (1000) reached
43-
44-
Then we need to disable `dash` as the default shell for sh scripts, as otherwise we run into a
45-
hard limit of a recursion depth of 1000:
46-
47-
```
48-
sudo dpkg-reconfigure dash
49-
```
50-
51-
and then select `No` to disable dash.
52-
53-
54-
#### Patching your `git worktree`
55-
56-
The regular git worktree does not scale to repos of the size of the rustc repo.
57-
So download the `git-subtree.sh` from https://github.com/gitgitgadget/git/pull/493/files and run
58-
59-
```
60-
sudo cp --backup /path/to/patched/git-subtree.sh /usr/lib/git-core/git-subtree
61-
sudo chmod --reference=/usr/lib/git-core/git-subtree~ /usr/lib/git-core/git-subtree
62-
sudo chown --reference=/usr/lib/git-core/git-subtree~ /usr/lib/git-core/git-subtree
63-
```
64-
65-
#### Actually doing a sync
66-
67-
In the rustc repo, execute
68-
69-
```
70-
git subtree pull --prefix=compiler/rustc_smir https://github.com/rust-lang/project-stable-mir smir
71-
```
72-
73-
Note: only ever sync to rustc from the project-stable-mir's `smir` branch. Do not sync with your own forks.
74-
75-
Then open a PR against rustc just like a regular PR.
7+
See the StableMIR ["Getting Started"](https://rust-lang.github.io/project-stable-mir/getting-started.html)
8+
guide for more information.
769

7710
## Stable MIR Design
7811

79-
The stable-mir will follow a similar approach to proc-macro2. It’s
80-
implementation will eventually be broken down into two main crates:
12+
The stable-mir will follow a similar approach to proc-macro2. Its
13+
implementation is split between two main crates:
8114

8215
- `stable_mir`: Public crate, to be published on crates.io, which will contain
83-
the stable data structure as well as proxy APIs to make calls to the
84-
compiler.
85-
- `rustc_smir`: The compiler crate that will translate from internal MIR to
86-
SMIR. This crate will also implement APIs that will be invoked by
87-
stable-mir to query the compiler for more information.
16+
the stable data structure as well as calls to `rustc_smir` APIs. The
17+
translation between stable and internal constructs will also be done in this crate,
18+
however, this is currently implemented in the `rustc_smir` crate.[^translation].
19+
- `rustc_smir`: This crate implements the public APIs to the compiler.
20+
It is responsible for gathering all the information requested, and providing
21+
the data in its unstable form.
22+
23+
[^translation]: This is currently implemented in the `rustc_smir` crate,
24+
but we are working to change that.
8825

89-
This will help tools to communicate with the rust compiler via stable APIs. Tools will depend on
90-
`stable_mir` crate, which will invoke the compiler using APIs defined in `rustc_smir`. I.e.:
26+
I.e.,
27+
tools will depend on `stable_mir` crate,
28+
which will invoke the compiler using APIs defined in `rustc_smir`.
29+
30+
I.e.:
9131

9232
```
9333
┌──────────────────────────────────┐ ┌──────────────────────────────────┐
@@ -104,9 +44,3 @@ This will help tools to communicate with the rust compiler via stable APIs. Tool
10444

10545
More details can be found here:
10646
https://hackmd.io/XhnYHKKuR6-LChhobvlT-g?view
107-
108-
For now, the code for these two crates are in separate modules of this crate.
109-
The modules have the same name for simplicity. We also have a third module,
110-
`rustc_internal` which will expose APIs and definitions that allow users to
111-
gather information from internal MIR constructs that haven't been exposed in
112-
the `stable_mir` module.

0 commit comments

Comments
 (0)