X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=CONTRIBUTING.md;h=223fd0065bf4a0cd78ba6847a3ec694f3e0da5eb;hb=e52e0d855799fe651922be4a038fe84fe9009c72;hp=f6147bbbe53556cca011bd73ffc0e06fef3d1e35;hpb=392342fcaf4c08c060d7ea7db2c03f3b5830def9;p=rust.git diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f6147bbbe53..223fd0065bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,277 +1,42 @@ -# Contribution Guide +# Contributing to Rust -If you want to hack on Miri yourself, great! Here are some resources you might -find useful. +Thank you for your interest in contributing to Rust! There are many ways to contribute +and we appreciate all of them. -## Getting started +The best way to get started is by asking for help in the [#new +members](https://rust-lang.zulipchat.com/#narrow/stream/122652-new-members) +Zulip stream. We have lots of docs below of how to get started on your own, but +the Zulip stream is the best place to *ask* for help. -Check out the issues on this GitHub repository for some ideas. In particular, -look for the green `E-*` labels which mark issues that should be rather -well-suited for onboarding. For more ideas or help with hacking on Miri, you can -contact us (`oli-obk` and `RalfJ`) on the [Rust Zulip]. +Documentation for contributing to Rust is located in the [Guide to Rustc Development](https://rustc-dev-guide.rust-lang.org/), +commonly known as the [rustc-dev-guide]. Despite the name, this guide documents +not just how to develop rustc (the Rust compiler), but also how to contribute to the standard library and rustdoc. -[Rust Zulip]: https://rust-lang.zulipchat.com +## About the [rustc-dev-guide] -## Preparing the build environment +The [rustc-dev-guide] is meant to help document how rustc –the Rust compiler– works, +as well as to help new contributors get involved in rustc development. It is recommend +to read and understand the [rustc-dev-guide] before making a contribution. This guide +talks about the different bots in the Rust ecosystem, the Rust development tools, +bootstrapping, the compiler architecture, source code representation, and more. -Miri heavily relies on internal and unstable rustc interfaces to execute MIR, -which means it is important that you install a version of rustc that Miri -actually works with. +## [Getting help](https://rustc-dev-guide.rust-lang.org/getting-started.html#asking-questions) -The `rust-version` file contains the commit hash of rustc that Miri is currently -tested against. Other versions will likely not work. After installing -[`rustup-toolchain-install-master`], you can run the following command to -install that exact version of rustc as a toolchain: -``` -./rustup-toolchain -``` -This will set up a rustup toolchain called `miri` and set it as an override for -the current directory. +There are many ways you can get help when you're stuck. Rust has many platforms for this: +[internals], [rust-zulip], and [rust-discord]. It is recommended to ask for help on +the [rust-zulip], but any of these platforms are a great way to seek help and even +find a mentor! You can learn more about asking questions and getting help in the +[Asking Questions](https://rustc-dev-guide.rust-lang.org/getting-started.html#asking-questions) chapter of the [rustc-dev-guide]. -You can also create a `.auto-everything` file (contents don't matter, can be empty), which -will cause any `./miri` command to automatically call `rustup-toolchain`, `clippy` and `rustfmt` -for you. If you don't want all of these to happen, you can add individual `.auto-toolchain`, -`.auto-clippy` and `.auto-fmt` files respectively. +## Bug reports -[`rustup-toolchain-install-master`]: https://github.com/kennytm/rustup-toolchain-install-master +Did a compiler error message tell you to come here? If you want to create an ICE report, +refer to [this section][contributing-bug-reports] and [open an issue][issue template]. -## Building and testing Miri - -Invoking Miri requires getting a bunch of flags right and setting up a custom -sysroot with xargo. The `miri` script takes care of that for you. With the -build environment prepared, compiling Miri is just one command away: - -``` -./miri build -``` - -Run `./miri` without arguments to see the other commands our build tool -supports. - -### Testing the Miri driver - -The Miri driver compiled from `src/bin/miri.rs` is the "heart" of Miri: it is -basically a version of `rustc` that, instead of compiling your code, runs it. -It accepts all the same flags as `rustc` (though the ones only affecting code -generation and linking obviously will have no effect) [and more][miri-flags]. - -[miri-flags]: README.md#miri--z-flags-and-environment-variables - -For example, you can (cross-)run the driver on a particular file by doing - -```sh -./miri run tests/pass/format.rs -./miri run tests/pass/hello.rs --target i686-unknown-linux-gnu -``` - -and you can (cross-)run the entire test suite using: - -``` -./miri test -MIRI_TEST_TARGET=i686-unknown-linux-gnu ./miri test -``` - -If your target doesn't support libstd, you can run miri with - -``` -MIRI_NO_STD=1 MIRI_TEST_TARGET=thumbv7em-none-eabihf ./miri test tests/fail/alloc/no_global_allocator.rs -MIRI_NO_STD=1 ./miri run tests/pass/no_std.rs --target thumbv7em-none-eabihf -``` - -to avoid attempting (and failing) to build libstd. Note that almost no tests will pass -this way, but you can run individual tests. - -`./miri test FILTER` only runs those tests that contain `FILTER` in their -filename (including the base directory, e.g. `./miri test fail` will run all -compile-fail tests). - -You can get a trace of which MIR statements are being executed by setting the -`MIRI_LOG` environment variable. For example: - -```sh -MIRI_LOG=info ./miri run tests/pass/vec.rs -``` - -Setting `MIRI_LOG` like this will configure logging for Miri itself as well as -the `rustc_middle::mir::interpret` and `rustc_mir::interpret` modules in rustc. You -can also do more targeted configuration, e.g. the following helps debug the -stacked borrows implementation: - -```sh -MIRI_LOG=rustc_mir::interpret=info,miri::stacked_borrows ./miri run tests/pass/vec.rs -``` - -In addition, you can set `MIRI_BACKTRACE=1` to get a backtrace of where an -evaluation error was originally raised. - -#### UI testing - -We use ui-testing in Miri, meaning we generate `.stderr` and `.stdout` files for the output -produced by Miri. You can use `./miri bless` to automatically (re)generate these files when -you add new tests or change how Miri presents certain output. - -Note that when you also use `MIRIFLAGS` to change optimizations and similar, the ui output -will change in unexpected ways. In order to still be able -to run the other checks while ignoring the ui output, use `MIRI_SKIP_UI_CHECKS=1 ./miri test`. - -For more info on how to configure ui tests see [the documentation on the ui test crate][ui_test] - -[ui_test]: ui_test/README.md - -### Testing `cargo miri` - -Working with the driver directly gives you full control, but you also lose all -the convenience provided by cargo. Once your test case depends on a crate, it -is probably easier to test it with the cargo wrapper. You can install your -development version of Miri using - -``` -./miri install -``` - -and then you can use it as if it was installed by `rustup`. Make sure you use -the same toolchain when calling `cargo miri` that you used when installing Miri! -Usually this means you have to write `cargo +miri miri ...` to select the `miri` -toolchain that was installed by `./rustup-toolchain`. - -There's a test for the cargo wrapper in the `test-cargo-miri` directory; run -`./run-test.py` in there to execute it. Like `./miri test`, this respects the -`MIRI_TEST_TARGET` environment variable to execute the test for another target. - -### Using a modified standard library - -Miri re-builds the standard library into a custom sysroot, so it is fairly easy -to test Miri against a modified standard library -- you do not even have to -build Miri yourself, the Miri shipped by `rustup` will work. All you have to do -is set the `MIRI_LIB_SRC` environment variable to the `library` folder of a -`rust-lang/rust` repository checkout. Note that changing files in that directory -does not automatically trigger a re-build of the standard library; you have to -clear the Miri build cache manually (on Linux, `rm -rf ~/.cache/miri`; -and on Windows, `rmdir /S "%LOCALAPPDATA%\rust-lang\miri\cache"`). - -### Benchmarking - -Miri comes with a few benchmarks; you can run `./miri bench` to run them with the locally built -Miri. Note: this will run `./miri install` as a side-effect. Also requires `hyperfine` to be -installed (`cargo install hyperfine`). - -## Configuring `rust-analyzer` - -To configure `rust-analyzer` and VS Code for working on Miri, save the following -to `.vscode/settings.json` in your local Miri clone: - -```json -{ - "rust-analyzer.rustc.source": "discover", - "rust-analyzer.linkedProjects": [ - "./Cargo.toml", - "./cargo-miri/Cargo.toml" - ], - "rust-analyzer.checkOnSave.overrideCommand": [ - "env", - "AUTO_OPS=42", - "./miri", - "check", - "--message-format=json" - ], - "rust-analyzer.buildScripts.overrideCommand": [ - "env", - "AUTO_OPS=42", - "./miri", - "check", - "--message-format=json", - ], - "rust-analyzer.rustfmt.extraArgs": [ - "+nightly" - ], -} -``` - -> #### Note -> -> If you are [building Miri with a locally built rustc][], set -> `rust-analyzer.rustcSource` to the relative path from your Miri clone to the -> root `Cargo.toml` of the locally built rustc. For example, the path might look -> like `../rust/Cargo.toml`. - -See the rustc-dev-guide's docs on ["Configuring `rust-analyzer` for `rustc`"][rdg-r-a] -for more information about configuring VS Code and `rust-analyzer`. - -[rdg-r-a]: https://rustc-dev-guide.rust-lang.org/building/suggested.html#configuring-rust-analyzer-for-rustc - -## Advanced topic: other build environments - -We described above the simplest way to get a working build environment for Miri, -which is to use the version of rustc indicated by `rustc-version`. But -sometimes, that is not enough. - -### Updating `rustc-version` - -The `rustc-version` file is regularly updated to keep Miri close to the latest -version of rustc. Usually, new contributors do not have to worry about this. But -sometimes a newer rustc is needed for a patch, and sometimes Miri needs fixing -for changes in rustc. In both cases, `rustc-version` needs updating. - -To update the `rustc-version` file and install the latest rustc, you can run: -``` -./rustup-toolchain HEAD -``` - -Now edit Miri until `./miri test` passes, and submit a PR. Generally, it is -preferred to separate updating `rustc-version` and doing what it takes to get -Miri working again, from implementing new features that rely on the updated -rustc. This avoids blocking all Miri development on landing a big PR. - -### Building Miri with a locally built rustc - -[building Miri with a locally built rustc]: #building-miri-with-a-locally-built-rustc - -A big part of the Miri driver lives in rustc, so working on Miri will sometimes -require using a locally built rustc. The bug you want to fix may actually be on -the rustc side, or you just need to get more detailed trace of the execution -than what is possible with release builds -- in both cases, you should develop -Miri against a rustc you compiled yourself, with debug assertions (and hence -tracing) enabled. - -The setup for a local rustc works as follows: -```sh -# Clone the rust-lang/rust repo. -git clone https://github.com/rust-lang/rust rustc -cd rustc -# Create a config.toml with defaults for working on Miri. -./x.py setup compiler - # Now edit `config.toml` and under `[rust]` set `debug-assertions = true`. - -# Build a stage 2 rustc, and build the rustc libraries with that rustc. -# This step can take 30 minutes or more. -./x.py build --stage 2 compiler/rustc -# If you change something, you can get a faster rebuild by doing -./x.py build --keep-stage 0 --stage 2 compiler/rustc -# You may have to change the architecture in the next command -rustup toolchain link stage2 build/x86_64-unknown-linux-gnu/stage2 -# Now cd to your Miri directory, then configure rustup -rustup override set stage2 -``` - -Note: When you are working with a locally built rustc or any other toolchain that -is not the same as the one in `rust-version`, you should not have `.auto-everything` or -`.auto-toolchain` as that will keep resetting your toolchain. - -``` -rm -f .auto-everything .auto-toolchain -``` - -Important: You need to delete the Miri cache when you change the stdlib; otherwise the -old, chached version will be used. On Linux, the cache is located at `~/.cache/miri`, -and on Windows, it is located at `%LOCALAPPDATA%\rust-lang\miri\cache`; the exact -location is printed after the library build: "A libstd for Miri is now available in ...". - -Note: `./x.py --stage 2 compiler/rustc` currently errors with `thread 'main' -panicked at 'fs::read(stamp) failed with No such file or directory (os error 2)`, -you can simply ignore that error; Miri will build anyway. - -For more information about building and configuring a local compiler, -see . - -With this, you should now have a working development setup! See -[above](#building-and-testing-miri) for how to proceed working on Miri. +[Contributing to Rust]: https://rustc-dev-guide.rust-lang.org/contributing.html#contributing-to-rust +[rustc-dev-guide]: https://rustc-dev-guide.rust-lang.org/ +[contributing-bug-reports]: https://rustc-dev-guide.rust-lang.org/contributing.html#bug-reports +[issue template]: https://github.com/rust-lang/rust/issues/new/choose +[internals]: https://internals.rust-lang.org +[rust-discord]: http://discord.gg/rust-lang +[rust-zulip]: https://rust-lang.zulipchat.com