Skip to content

Commit a34d694

Browse files
borsbors
committed
Auto merge of #953 - RalfJung:contributing, r=oli-obk
add CONTRIBUTING guide
2 parents 9a14624 + 1fb934b commit a34d694

File tree

2 files changed

+146
-124
lines changed

2 files changed

+146
-124
lines changed

‎CONTRIBUTING.md

+141
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Contribution Guide
2+
3+
If you want to hack on miri yourself, great! Here are some resources you might
4+
find useful.
5+
6+
## Getting started
7+
8+
Check out the issues on this GitHub repository for some ideas. There's lots that
9+
needs to be done that we haven't documented in the issues yet, however. For more
10+
ideas or help with hacking on Miri, you can contact us (`oli-obk` and `RalfJ`)
11+
on the [Rust Zulip].
12+
13+
[Rust Zulip]: https://rust-lang.zulipchat.com
14+
15+
### Fixing Miri when rustc changes
16+
17+
Miri is heavily tied to rustc internals, so it is very common that rustc changes
18+
break Miri. Fixing those is a good way to get starting working on Miri.
19+
Usually, Miri will require changes similar to the other consumers of the changed
20+
rustc API, so reading the rustc PR diff is a good way to get an idea for what is
21+
needed.
22+
23+
When submitting a PR against Miri after fixing it for rustc changes, make sure
24+
you update the `rust-version` file. That file always contains the exact rustc
25+
git commit with which Miri works, and it is the version that our CI tests Miri
26+
against.
27+
28+
## Building Miri with a nightly rustc
29+
30+
Miri heavily relies on internal rustc interfaces to execute MIR. Still, some
31+
things (like adding support for a new intrinsic or a shim for an external
32+
function being called) can be done by working just on the Miri side.
33+
34+
To prepare, make sure you are using a nightly Rust compiler. Then you should be
35+
able to just `cargo build` Miri.
36+
37+
In case this fails, your nightly might be incompatible with Miri master. The
38+
`rust-version` file contains the commit hash of rustc that Miri is currently
39+
tested against; you can use that to find a nightly that works or you might have
40+
to wait for the next nightly to get released. You can also use
41+
[`rustup-toolchain-install-master`](https://github.com/kennytm/rustup-toolchain-install-master)
42+
to install that exact version of rustc as a toolchain:
43+
```
44+
rustup-toolchain-install-master $(cat rust-version) -c rust-src
45+
```
46+
47+
Another common problem is outdated dependencies: Miri does not come with a
48+
lockfile (it cannot, due to how it gets embedded into the rustc build). So you
49+
have to run `cargo update` every now and then yourself to make sure you are
50+
using the latest versions of everything (which is what gets tested on CI).
51+
52+
## Testing the Miri driver
53+
[testing-miri]: #testing-the-miri-driver
54+
55+
The Miri driver in the `miri` binary is the "heart" of Miri: it is basically a
56+
version of `rustc` that, instead of compiling your code, runs it. It accepts
57+
all the same flags as `rustc` (though the ones only affecting code generation
58+
and linking obviously will have no effect) [and more][miri-flags].
59+
60+
Running the Miri driver requires some fiddling with environment variables, so
61+
the `miri` script helps you do that. For example, you can run the driver on a
62+
particular file by doing
63+
64+
```sh
65+
./miri run tests/run-pass/format.rs
66+
./miri run tests/run-pass/hello.rs --target i686-unknown-linux-gnu
67+
```
68+
69+
and you can run the test suite using:
70+
71+
```
72+
./miri test
73+
```
74+
75+
`./miri test FILTER` only runs those tests that contain `FILTER` in their
76+
filename (including the base directory, e.g. `./miri test fail` will run all
77+
compile-fail tests).
78+
79+
You can get a trace of which MIR statements are being executed by setting the
80+
`MIRI_LOG` environment variable. For example:
81+
82+
```sh
83+
MIRI_LOG=info ./miri run tests/run-pass/vecs.rs
84+
```
85+
86+
Setting `MIRI_LOG` like this will configure logging for Miri itself as well as
87+
the `rustc::mir::interpret` and `rustc_mir::interpret` modules in rustc. You
88+
can also do more targeted configuration, e.g. the following helps debug the
89+
stacked borrows implementation:
90+
91+
```sh
92+
MIRI_LOG=rustc_mir::interpret=info,miri::stacked_borrows ./miri run tests/run-pass/vecs.rs
93+
```
94+
95+
In addition, you can set `MIRI_BACKTRACE=1` to get a backtrace of where an
96+
evaluation error was originally raised.
97+
98+
## Testing `cargo miri`
99+
100+
Working with the driver directly gives you full control, but you also lose all
101+
the convenience provided by cargo. Once your test case depends on a crate, it
102+
is probably easier to test it with the cargo wrapper. You can install your
103+
development version of Miri using
104+
105+
```
106+
./miri install
107+
```
108+
109+
and then you can use it as if it was installed by `rustup`. Make sure you use
110+
the same toolchain when calling `cargo miri` that you used when installing Miri!
111+
112+
There's a test for the cargo wrapper in the `test-cargo-miri` directory; run
113+
`./run-test.py` in there to execute it.
114+
115+
## Building Miri with a locally built rustc
116+
117+
A big part of the Miri driver lives in rustc, so working on Miri will sometimes
118+
require using a locally built rustc. The bug you want to fix may actually be on
119+
the rustc side, or you just need to get more detailed trace of the execution
120+
than what is possible with release builds -- in both cases, you should develop
121+
miri against a rustc you compiled yourself, with debug assertions (and hence
122+
tracing) enabled.
123+
124+
The setup for a local rustc works as follows:
125+
```sh
126+
git clone https://github.com/rust-lang/rust/ rustc
127+
cd rustc
128+
cp config.toml.example config.toml
129+
# Now edit `config.toml` and set `debug-assertions = true`.
130+
# This step can take 30 minutes and more.
131+
./x.py build src/rustc
132+
# If you change something, you can get a faster rebuild by doing
133+
./x.py --keep-stage 0 build src/rustc
134+
# You may have to change the architecture in the next command
135+
rustup toolchain link custom build/x86_64-unknown-linux-gnu/stage2
136+
# Now cd to your Miri directory, then configure rustup
137+
rustup override set custom
138+
```
139+
140+
With this, you should now have a working development setup! See
141+
[above][testing-miri] for how to proceed working with the Miri driver.

‎README.md

+5-124
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ program, and cannot run all programs:
5050
[`copy_nonoverlapping`]: https://doc.rust-lang.org/stable/std/ptr/fn.copy_nonoverlapping.html
5151

5252

53-
## Running Miri on your own project (and its test suite)
53+
## Using Miri
5454

5555
Install Miri via `rustup`:
5656

@@ -183,131 +183,12 @@ Moreover, Miri recognizes some environment variables:
183183
architecture to test against. `miri` and `cargo miri` accept the `--target`
184184
flag for the same purpose.
185185

186-
## Development and Debugging
187-
188-
If you want to hack on miri yourself, great! Here are some resources you might
189-
find useful.
190-
191-
### Using a nightly rustc
192-
193-
Miri heavily relies on internal rustc interfaces to execute MIR. Still, some
194-
things (like adding support for a new intrinsic or a shim for an external
195-
function being called) can be done by working just on the Miri side.
196-
197-
To prepare, make sure you are using a nightly Rust compiler. Then you should be
198-
able to just `cargo build` Miri.
199-
200-
In case this fails, your nightly might be incompatible with Miri master. The
201-
`rust-version` file contains the commit hash of rustc that Miri is currently
202-
tested against; you can use that to find a nightly that works or you might have
203-
to wait for the next nightly to get released. You can also use
204-
[`rustup-toolchain-install-master`](https://github.com/kennytm/rustup-toolchain-install-master)
205-
to install that exact version of rustc as a toolchain:
206-
```
207-
rustup-toolchain-install-master $(cat rust-version) -c rust-src
208-
```
209-
210-
Another common problem is outdated dependencies: Miri does not come with a
211-
lockfile (it cannot, due to how it gets embedded into the rustc build). So you
212-
have to run `cargo update` every now and then yourself to make sure you are
213-
using the latest versions of everything (which is what gets tested on CI).
214-
215-
### Testing the Miri driver
216-
[testing-miri]: #testing-the-miri-driver
217-
218-
The Miri driver in the `miri` binary is the "heart" of Miri: it is basically a
219-
version of `rustc` that, instead of compiling your code, runs it. It accepts
220-
all the same flags as `rustc` (though the ones only affecting code generation
221-
and linking obviously will have no effect) [and more][miri-flags].
222-
223-
Running the Miri driver requires some fiddling with environment variables, so
224-
the `miri` script helps you do that. For example, you can run the driver on a
225-
particular file by doing
226-
227-
```sh
228-
./miri run tests/run-pass/format.rs
229-
./miri run tests/run-pass/hello.rs --target i686-unknown-linux-gnu
230-
```
231-
232-
and you can run the test suite using:
233-
234-
```
235-
./miri test
236-
```
237-
238-
`./miri test FILTER` only runs those tests that contain `FILTER` in their
239-
filename (including the base directory, e.g. `./miri test fail` will run all
240-
compile-fail tests).
241-
242-
You can get a trace of which MIR statements are being executed by setting the
243-
`MIRI_LOG` environment variable. For example:
244-
245-
```sh
246-
MIRI_LOG=info ./miri run tests/run-pass/vecs.rs
247-
```
248-
249-
Setting `MIRI_LOG` like this will configure logging for Miri itself as well as
250-
the `rustc::mir::interpret` and `rustc_mir::interpret` modules in rustc. You
251-
can also do more targeted configuration, e.g. the following helps debug the
252-
stacked borrows implementation:
253-
254-
```sh
255-
MIRI_LOG=rustc_mir::interpret=info,miri::stacked_borrows ./miri run tests/run-pass/vecs.rs
256-
```
257-
258-
In addition, you can set `MIRI_BACKTRACE=1` to get a backtrace of where an
259-
evaluation error was originally raised.
260-
261-
### Testing `cargo miri`
262-
263-
Working with the driver directly gives you full control, but you also lose all
264-
the convenience provided by cargo. Once your test case depends on a crate, it
265-
is probably easier to test it with the cargo wrapper. You can install your
266-
development version of Miri using
267-
268-
```
269-
./miri install
270-
```
271-
272-
and then you can use it as if it was installed by `rustup`. Make sure you use
273-
the same toolchain when calling `cargo miri` that you used when installing Miri!
274-
275-
There's a test for the cargo wrapper in the `test-cargo-miri` directory; run
276-
`./run-test.py` in there to execute it.
277-
278-
### Using a locally built rustc
279-
280-
A big part of the Miri driver lives in rustc, so working on Miri will sometimes
281-
require using a locally built rustc. The bug you want to fix may actually be on
282-
the rustc side, or you just need to get more detailed trace of the execution
283-
than what is possible with release builds -- in both cases, you should develop
284-
miri against a rustc you compiled yourself, with debug assertions (and hence
285-
tracing) enabled.
286-
287-
The setup for a local rustc works as follows:
288-
```sh
289-
git clone https://github.com/rust-lang/rust/ rustc
290-
cd rustc
291-
cp config.toml.example config.toml
292-
# Now edit `config.toml` and set `debug-assertions = true`.
293-
# This step can take 30 minutes and more.
294-
./x.py build src/rustc
295-
# If you change something, you can get a faster rebuild by doing
296-
./x.py --keep-stage 0 build src/rustc
297-
# You may have to change the architecture in the next command
298-
rustup toolchain link custom build/x86_64-unknown-linux-gnu/stage2
299-
# Now cd to your Miri directory, then configure rustup
300-
rustup override set custom
301-
```
302-
303-
With this, you should now have a working development setup! See
304-
[above][testing-miri] for how to proceed working with the Miri driver.
305-
306186
## Contributing and getting help
307187

308-
Check out the issues on this GitHub repository for some ideas. There's lots that
309-
needs to be done that I haven't documented in the issues yet, however. For more
310-
ideas or help with running or hacking on Miri, you can open an issue here on
188+
If you want to contribute to Miri, great! Please check out our
189+
[contribution guide](CONTRIBUTING.md).
190+
191+
For help with running Miri, you can open an issue here on
311192
GitHub or contact us (`oli-obk` and `RalfJ`) on the [Rust Zulip].
312193

313194
[Rust Zulip]: https://rust-lang.zulipchat.com

0 commit comments

Comments
 (0)