<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>src/tools/miri/CONTRIBUTING.md - fork/rust @ master</title>
<meta name="description" content="src/tools/miri/CONTRIBUTING.md in fork/rust at master.">
<meta property="og:title" content="src/tools/miri/CONTRIBUTING.md - fork/rust @ master">
<meta property="og:description" content="src/tools/miri/CONTRIBUTING.md in fork/rust at master.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="master" data-tip="3bcad65fbf67b6edf87c949531fbc13435882e6b">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/rust</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/rust</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">bors</span><span class="commit-message" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">Auto merge of #103046 - JanBeh:PR_clarify_cmp_terminology, r=workingjubilee</span><span class="snapshot-sha sha" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">3bcad65fbf6</span><time datetime="2023-10-05T15:24:54+00:00" title="2023-10-05 15:24:54 +0000">2023-10-05</time></p>
<header class="topbar"><details class="switcher"><summary>master</summary><div class="menu"><strong>branches</strong><a class="current" href="/fork/rust/ref/master/">master</a><strong>tags</strong><a href="/fork/rust/ref/1.39.0/">1.39.0</a><a href="/fork/rust/ref/1.40.0/">1.40.0</a><a href="/fork/rust/ref/1.41.0/">1.41.0</a><a href="/fork/rust/ref/1.41.1/">1.41.1</a><a href="/fork/rust/ref/1.42.0/">1.42.0</a><a href="/fork/rust/ref/1.43.0/">1.43.0</a><a href="/fork/rust/ref/1.43.1/">1.43.1</a><a href="/fork/rust/ref/1.44.0/">1.44.0</a><a class="all" href="/fork/rust/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/rust/">rust</a> / <a href="/fork/rust/ref/master/tree/src/">src</a> / <a href="/fork/rust/ref/master/tree/src/tools/">tools</a> / <a href="/fork/rust/ref/master/tree/src/tools/miri/">miri</a> / <span class="cur">CONTRIBUTING.md</span></nav>
<span class="view-stats"><span>10.5 KiB</span><span>286 lines</span></span><span class="actions"><a class="raw" href="/fork/rust/raw/4e50b8fae81ce91633d2908a17a0087b3c66c86a/src/tools/miri/CONTRIBUTING.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>Contribution Guide</h1>
<p>If you want to hack on Miri yourself, great!  Here are some resources you might
find useful.</p>
<h2>Getting started</h2>
<p>Check out the issues on this GitHub repository for some ideas. In particular,
look for the green <code>E-*</code> 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 (<code>oli-obk</code> and <code>RalfJ</code>) on the <a href="https://rust-lang.zulipchat.com">Rust Zulip</a>.</p>
<h2>Preparing the build environment</h2>
<p>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.</p>
<p>The <code>rust-version</code> file contains the commit hash of rustc that Miri is currently
tested against. Other versions will likely not work. After installing
<a href="https://github.com/kennytm/rustup-toolchain-install-master"><code>rustup-toolchain-install-master</code></a>, you can run the following command to
install that exact version of rustc as a toolchain:</p>
<pre>./miri toolchain
</pre>
<p>This will set up a rustup toolchain called <code>miri</code> and set it as an override for
the current directory.</p>
<p>You can also create a <code>.auto-everything</code> file (contents don't matter, can be empty), which
will cause any <code>./miri</code> command to automatically call <code>./miri toolchain</code>, <code>clippy</code> and <code>rustfmt</code>
for you. If you don't want all of these to happen, you can add individual <code>.auto-toolchain</code>,
<code>.auto-clippy</code> and <code>.auto-fmt</code> files respectively.</p>
<h2>Building and testing Miri</h2>
<p>Invoking Miri requires getting a bunch of flags right and setting up a custom
sysroot. The <code>miri</code> script takes care of that for you. With the
build environment prepared, compiling Miri is just one command away:</p>
<pre>./miri build
</pre>
<p>Run <code>./miri</code> without arguments to see the other commands our build tool
supports.</p>
<h3>Testing the Miri driver</h3>
<p>The Miri driver compiled from <code>src/bin/miri.rs</code> is the "heart" of Miri: it is
basically a version of <code>rustc</code> that, instead of compiling your code, runs it.
It accepts all the same flags as <code>rustc</code> (though the ones only affecting code
generation and linking obviously will have no effect) <a href="/fork/rust/ref/master/blob/src/tools/miri/README.md#miri--z-flags-and-environment-variables">and more</a>.</p>
<p>For example, you can (cross-)run the driver on a particular file by doing</p>
<pre class="language-bash"><a-f>./miri</a-f> run tests/pass/format.rs
<a-f>./miri</a-f> run tests/pass/hello.rs <a-co>--target</a-co> i686-unknown-linux-gnu</pre>
<p>and you can (cross-)run the entire test suite using:</p>
<pre>./miri test
MIRI_TEST_TARGET=i686-unknown-linux-gnu ./miri test
</pre>
<p>If your target doesn't support libstd, you can run miri with</p>
<pre>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
</pre>
<p>to avoid attempting (and failing) to build libstd. Note that almost no tests will pass
this way, but you can run individual tests.</p>
<p><code>./miri test FILTER</code> only runs those tests that contain <code>FILTER</code> in their
filename (including the base directory, e.g. <code>./miri test fail</code> will run all
compile-fail tests).</p>
<p>You can get a trace of which MIR statements are being executed by setting the
<code>MIRI_LOG</code> environment variable.  For example:</p>
<pre class="language-bash"><a-pr>MIRI_LOG</a-pr>=info <a-f>./miri</a-f> run tests/pass/vec.rs</pre>
<p>Setting <code>MIRI_LOG</code> like this will configure logging for Miri itself as well as
the <code>rustc_middle::mir::interpret</code> and <code>rustc_mir::interpret</code> modules in rustc. You
can also do more targeted configuration, e.g. the following helps debug the
stacked borrows implementation:</p>
<pre class="language-bash"><a-pr>MIRI_LOG</a-pr>=rustc_mir::interpret=info,miri::stacked_borrows <a-f>./miri</a-f> run tests/pass/vec.rs</pre>
<p>In addition, you can set <code>MIRI_BACKTRACE=1</code> to get a backtrace of where an
evaluation error was originally raised.</p>
<h3>UI testing</h3>
<p>We use ui-testing in Miri, meaning we generate <code>.stderr</code> and <code>.stdout</code> files for the output
produced by Miri. You can use <code>./miri test --bless</code> to automatically (re)generate these files when
you add new tests or change how Miri presents certain output.</p>
<p>Note that when you also use <code>MIRIFLAGS</code> 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 <code>MIRI_SKIP_UI_CHECKS=1 ./miri test</code>.</p>
<p>For more info on how to configure ui tests see <a href="ui_test/README.md">the documentation on the ui test crate</a></p>
<h3>Testing <code>cargo miri</code></h3>
<p>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</p>
<pre>./miri install
</pre>
<p>and then you can use it as if it was installed by <code>rustup</code> as a component of the
<code>miri</code> toolchain. Note that the <code>miri</code> and <code>cargo-miri</code> executables are placed
in the <code>miri</code> toolchain's sysroot to prevent conflicts with other toolchains.
The Miri binaries in the <code>cargo</code> bin directory (usually <code>~/.cargo/bin</code>) are managed by rustup.</p>
<p>There's a test for the cargo wrapper in the <code>test-cargo-miri</code> directory; run
<code>./run-test.py</code> in there to execute it. Like <code>./miri test</code>, this respects the
<code>MIRI_TEST_TARGET</code> environment variable to execute the test for another target.</p>
<h3>Using a modified standard library</h3>
<p>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 <code>rustup</code> will work. All you have to do
is set the <code>MIRI_LIB_SRC</code> environment variable to the <code>library</code> folder of a
<code>rust-lang/rust</code> 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, <code>rm -rf ~/.cache/miri</code>;
on Windows, <code>rmdir /S "%LOCALAPPDATA%\rust-lang\miri\cache"</code>;
and on macOS, <code>rm -rf ~/Library/Caches/org.rust-lang.miri</code>).</p>
<h3>Benchmarking</h3>
<p>Miri comes with a few benchmarks; you can run <code>./miri bench</code> to run them with the locally built
Miri. Note: this will run <code>./miri install</code> as a side-effect. Also requires <code>hyperfine</code> to be
installed (<code>cargo install hyperfine</code>).</p>
<h2>Configuring <code>rust-analyzer</code></h2>
<p>To configure <code>rust-analyzer</code> and VS Code for working on Miri, save the following
to <code>.vscode/settings.json</code> in your local Miri clone:</p>
<pre class="language-json">{
    <a-s>&quot;rust-analyzer.rustc.source&quot;</a-s>: <a-s>&quot;discover&quot;</a-s>,
    <a-s>&quot;rust-analyzer.linkedProjects&quot;</a-s>: [
        <a-s>&quot;Cargo.toml&quot;</a-s>,
        <a-s>&quot;cargo-miri/Cargo.toml&quot;</a-s>,
        <a-s>&quot;miri-script/Cargo.toml&quot;</a-s>,<a-n>
    ],
    </a-n><a-s>&quot;rust-analyzer.check.overrideCommand&quot;</a-s><a-n>: [
        </a-n><a-s>&quot;env&quot;</a-s><a-n>,
        </a-n><a-s>&quot;MIRI_AUTO_OPS=no&quot;</a-s><a-n>,
        </a-n><a-s>&quot;./miri&quot;</a-s><a-n>,
        </a-n><a-s>&quot;cargo&quot;</a-s><a-n>,
        </a-n><a-s>&quot;clippy&quot;</a-s><a-n>, </a-n><a-c>// make this `check` when working with a locally built rustc</a-c><a-n>
        </a-n><a-s>&quot;--message-format=json&quot;</a-s><a-n>,</a-n><a-n>
    ],
    </a-n><a-c>// Contrary to what the name suggests, this also affects proc macros.</a-c><a-n>
    </a-n><a-s>&quot;rust-analyzer.cargo.buildScripts.overrideCommand&quot;</a-s><a-n>: [
        </a-n><a-s>&quot;env&quot;</a-s><a-n>,
        </a-n><a-s>&quot;MIRI_AUTO_OPS=no&quot;</a-s><a-n>,
        </a-n><a-s>&quot;./miri&quot;</a-s><a-n>,
        </a-n><a-s>&quot;cargo&quot;</a-s><a-n>,
        </a-n><a-s>&quot;check&quot;</a-s><a-n>,
        </a-n><a-s>&quot;--message-format=json&quot;</a-s><a-n>,</a-n><a-n>
    ],
}</a-n></pre>
<blockquote>
<h4>Note</h4>
<p>If you are [building Miri with a locally built rustc][], set
<code>rust-analyzer.rustcSource</code> to the relative path from your Miri clone to the
root <code>Cargo.toml</code> of the locally built rustc. For example, the path might look
like <code>../rust/Cargo.toml</code>.</p>
</blockquote>
<p>See the rustc-dev-guide's docs on <a href="https://rustc-dev-guide.rust-lang.org/building/suggested.html#configuring-rust-analyzer-for-rustc">"Configuring <code>rust-analyzer</code> for <code>rustc</code>"</a>
for more information about configuring VS Code and <code>rust-analyzer</code>.</p>
<h2>Advanced topic: Working on Miri in the rustc tree</h2>
<p>We described above the simplest way to get a working build environment for Miri,
which is to use the version of rustc indicated by <code>rustc-version</code>. But
sometimes, that is not enough.</p>
<p>A big part of the Miri driver is shared with rustc, so working on Miri will
sometimes require also working on rustc itself. In this case, you should <em>not</em>
work in a clone of the Miri repository, but in a clone of the
<a href="https://github.com/rust-lang/rust/">main Rust repository</a>. There is a copy of
Miri located at <code>src/tools/miri</code> that you can work on directly. A maintainer
will eventually sync those changes back into this repository.</p>
<p>When working on Miri in the rustc tree, here's how you can run tests:</p>
<pre>./x.py test miri --stage 0
</pre>
<p><code>--bless</code> will work, too.</p>
<p>You can also directly run Miri on a Rust source file:</p>
<pre>./x.py run miri --stage 0 --args src/tools/miri/tests/pass/hello.rs
</pre>
<h2>Advanced topic: Syncing with the rustc repo</h2>
<p>We use the <a href="https://github.com/josh-project/josh"><code>josh</code> proxy</a> to transmit changes between the
rustc and Miri repositories. You can install it as follows:</p>
<pre class="language-bash"><a-f>cargo</a-f> +stable install josh-proxy <a-co>--git</a-co> https://github.com/josh-project/josh <a-co>--tag</a-co> r22.12.06</pre>
<p>Josh will automatically be started and stopped by <code>./miri</code>.</p>
<h3>Importing changes from the rustc repo</h3>
<p>We assume we start on an up-to-date master branch in the Miri repo.</p>
<pre class="language-bash"><a-c># Fetch and merge rustc side of the history. Takes ca 5 min the first time.</a-c>
<a-c># This will also update the &#39;rustc-version&#39; file.</a-c>
<a-f>./miri</a-f> rustc-pull
<a-c># Update local toolchain and apply formatting.</a-c>
<a-f>./miri</a-f> toolchain <a-o>&amp;&amp;</a-o> <a-f>./miri</a-f> fmt
<a-f>git</a-f> commit <a-co>-am</a-co> <a-s>&quot;rustup&quot;</a-s></pre>
<p>Now push this to a new branch in your Miri fork, and create a PR. It is worth
running <code>./miri test</code> locally in parallel, since the test suite in the Miri repo
is stricter than the one on the rustc side, so some small tweaks might be
needed.</p>
<h3>Exporting changes to the rustc repo</h3>
<p>Keep in mind that pushing is the most complicated job that josh has to do -- pulling just filters
the rustc history, but pushing needs to construct a new rustc history that would filter to the given
Miri history! To avoid problems, it is a good idea to always pull immediately before you push. If
you are getting strange errors, chances are you are running into <a href="https://github.com/josh-project/josh/issues/998">this josh
bug</a>. In that case, please get in touch on Zulip.</p>
<p>We will use the josh proxy to push to your fork of rustc. Run the following in the Miri repo,
assuming we are on an up-to-date master branch:</p>
<pre class="language-bash"><a-c># Push the Miri changes to your rustc fork (substitute your github handle for YOUR_NAME).</a-c>
<a-f>./miri</a-f> rustc-push YOUR_NAME miri</pre>
<p>This will create a new branch called 'miri' in your fork, and the output should
include a link to create a rustc PR that will integrate those changes into the
main repository.</p>
<p>If this fails due to authentication problems, it can help to make josh push via ssh instead of
https. Add the following to your <code>.gitconfig</code>:</p>
<pre class="language-toml"><a-p>[</a-p><a-pr>url</a-pr> <a-s>&quot;git@github.com:&quot;</a-s><a-p>]</a-p>
    <a-pr>pushInsteadOf</a-pr> <a-o>=</a-o> <a-pr>https</a-pr>://<a-pr>github</a-pr><a-p>.</a-p><a-pr>com</a-pr>/</pre>
</section><div class="code-panel"><pre class="code src" data-hl="src/tools/miri/CONTRIBUTING.md"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"># Contribution Guide</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">If you want to hack on Miri yourself, great!  Here are some resources you might</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">find useful.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">## Getting started</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text">Check out the issues on this GitHub repository for some ideas. In particular,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">look for the green `E-*` labels which mark issues that should be rather</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text">well-suited for onboarding. For more ideas or help with hacking on Miri, you can</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">contact us (`oli-obk` and `RalfJ`) on the [Rust Zulip].</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">[Rust Zulip]: https://rust-lang.zulipchat.com</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">## Preparing the build environment</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">Miri heavily relies on internal and unstable rustc interfaces to execute MIR,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text">which means it is important that you install a version of rustc that Miri</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">actually works with.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">The `rust-version` file contains the commit hash of rustc that Miri is currently</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text">tested against. Other versions will likely not work. After installing</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text">[`rustup-toolchain-install-master`], you can run the following command to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text">install that exact version of rustc as a toolchain:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text">./miri toolchain</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text">This will set up a rustup toolchain called `miri` and set it as an override for</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">the current directory.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text">You can also create a `.auto-everything` file (contents don't matter, can be empty), which</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text">will cause any `./miri` command to automatically call `./miri toolchain`, `clippy` and `rustfmt`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text">for you. If you don't want all of these to happen, you can add individual `.auto-toolchain`,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text">`.auto-clippy` and `.auto-fmt` files respectively.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text">[`rustup-toolchain-install-master`]: https://github.com/kennytm/rustup-toolchain-install-master</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text">## Building and testing Miri</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text">Invoking Miri requires getting a bunch of flags right and setting up a custom</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text">sysroot. The `miri` script takes care of that for you. With the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text">build environment prepared, compiling Miri is just one command away:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text">./miri build</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text">Run `./miri` without arguments to see the other commands our build tool</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text">supports.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text">### Testing the Miri driver</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text">The Miri driver compiled from `src/bin/miri.rs` is the &quot;heart&quot; of Miri: it is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text">basically a version of `rustc` that, instead of compiling your code, runs it.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text">It accepts all the same flags as `rustc` (though the ones only affecting code</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text">generation and linking obviously will have no effect) [and more][miri-flags].</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text">[miri-flags]: README.md#miri--z-flags-and-environment-variables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text">For example, you can (cross-)run the driver on a particular file by doing</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text">```sh</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text">./miri run tests/pass/format.rs</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text">./miri run tests/pass/hello.rs --target i686-unknown-linux-gnu</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text">and you can (cross-)run the entire test suite using:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text">./miri test</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text">MIRI_TEST_TARGET=i686-unknown-linux-gnu ./miri test</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text">If your target doesn't support libstd, you can run miri with</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text">MIRI_NO_STD=1 MIRI_TEST_TARGET=thumbv7em-none-eabihf ./miri test tests/fail/alloc/no_global_allocator.rs</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text">MIRI_NO_STD=1 ./miri run tests/pass/no_std.rs --target thumbv7em-none-eabihf</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text">to avoid attempting (and failing) to build libstd. Note that almost no tests will pass</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text">this way, but you can run individual tests.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text">`./miri test FILTER` only runs those tests that contain `FILTER` in their</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text">filename (including the base directory, e.g. `./miri test fail` will run all</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text">compile-fail tests).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text">You can get a trace of which MIR statements are being executed by setting the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text">`MIRI_LOG` environment variable.  For example:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text">```sh</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text">MIRI_LOG=info ./miri run tests/pass/vec.rs</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text">Setting `MIRI_LOG` like this will configure logging for Miri itself as well as</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text">the `rustc_middle::mir::interpret` and `rustc_mir::interpret` modules in rustc. You</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text">can also do more targeted configuration, e.g. the following helps debug the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text">stacked borrows implementation:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text">```sh</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text">MIRI_LOG=rustc_mir::interpret=info,miri::stacked_borrows ./miri run tests/pass/vec.rs</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text">In addition, you can set `MIRI_BACKTRACE=1` to get a backtrace of where an</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text">evaluation error was originally raised.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text">### UI testing</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text">We use ui-testing in Miri, meaning we generate `.stderr` and `.stdout` files for the output</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text">produced by Miri. You can use `./miri test --bless` to automatically (re)generate these files when</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text">you add new tests or change how Miri presents certain output.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text">Note that when you also use `MIRIFLAGS` to change optimizations and similar, the ui output</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text">will change in unexpected ways. In order to still be able</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text">to run the other checks while ignoring the ui output, use `MIRI_SKIP_UI_CHECKS=1 ./miri test`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text">For more info on how to configure ui tests see [the documentation on the ui test crate][ui_test]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text">[ui_test]: ui_test/README.md</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text">### Testing `cargo miri`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text">Working with the driver directly gives you full control, but you also lose all</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text">the convenience provided by cargo. Once your test case depends on a crate, it</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text">is probably easier to test it with the cargo wrapper. You can install your</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text">development version of Miri using</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text">./miri install</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text">and then you can use it as if it was installed by `rustup` as a component of the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text">`miri` toolchain. Note that the `miri` and `cargo-miri` executables are placed</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text">in the `miri` toolchain's sysroot to prevent conflicts with other toolchains.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text">The Miri binaries in the `cargo` bin directory (usually `~/.cargo/bin`) are managed by rustup.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text">There's a test for the cargo wrapper in the `test-cargo-miri` directory; run</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text">`./run-test.py` in there to execute it. Like `./miri test`, this respects the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text">`MIRI_TEST_TARGET` environment variable to execute the test for another target.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L140" href="#L140">140</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L141" href="#L141">141</a><span class="code-text">### Using a modified standard library</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L142" href="#L142">142</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L143" href="#L143">143</a><span class="code-text">Miri re-builds the standard library into a custom sysroot, so it is fairly easy</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L144" href="#L144">144</a><span class="code-text">to test Miri against a modified standard library -- you do not even have to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L145" href="#L145">145</a><span class="code-text">build Miri yourself, the Miri shipped by `rustup` will work. All you have to do</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L146" href="#L146">146</a><span class="code-text">is set the `MIRI_LIB_SRC` environment variable to the `library` folder of a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L147" href="#L147">147</a><span class="code-text">`rust-lang/rust` repository checkout. Note that changing files in that directory</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L148" href="#L148">148</a><span class="code-text">does not automatically trigger a re-build of the standard library; you have to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L149" href="#L149">149</a><span class="code-text">clear the Miri build cache manually (on Linux, `rm -rf ~/.cache/miri`;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L150" href="#L150">150</a><span class="code-text">on Windows, `rmdir /S &quot;%LOCALAPPDATA%\rust-lang\miri\cache&quot;`;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L151" href="#L151">151</a><span class="code-text">and on macOS, `rm -rf ~/Library/Caches/org.rust-lang.miri`).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L152" href="#L152">152</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L153" href="#L153">153</a><span class="code-text">### Benchmarking</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L154" href="#L154">154</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L155" href="#L155">155</a><span class="code-text">Miri comes with a few benchmarks; you can run `./miri bench` to run them with the locally built</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L156" href="#L156">156</a><span class="code-text">Miri. Note: this will run `./miri install` as a side-effect. Also requires `hyperfine` to be</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L157" href="#L157">157</a><span class="code-text">installed (`cargo install hyperfine`).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L158" href="#L158">158</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L159" href="#L159">159</a><span class="code-text">## Configuring `rust-analyzer`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L160" href="#L160">160</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L161" href="#L161">161</a><span class="code-text">To configure `rust-analyzer` and VS Code for working on Miri, save the following</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L162" href="#L162">162</a><span class="code-text">to `.vscode/settings.json` in your local Miri clone:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L163" href="#L163">163</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L164" href="#L164">164</a><span class="code-text">```json</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L165" href="#L165">165</a><span class="code-text">{</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L166" href="#L166">166</a><span class="code-text">    &quot;rust-analyzer.rustc.source&quot;: &quot;discover&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L167" href="#L167">167</a><span class="code-text">    &quot;rust-analyzer.linkedProjects&quot;: [</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L168" href="#L168">168</a><span class="code-text">        &quot;Cargo.toml&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L169" href="#L169">169</a><span class="code-text">        &quot;cargo-miri/Cargo.toml&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L170" href="#L170">170</a><span class="code-text">        &quot;miri-script/Cargo.toml&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L171" href="#L171">171</a><span class="code-text">    ],</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L172" href="#L172">172</a><span class="code-text">    &quot;rust-analyzer.check.overrideCommand&quot;: [</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L173" href="#L173">173</a><span class="code-text">        &quot;env&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L174" href="#L174">174</a><span class="code-text">        &quot;MIRI_AUTO_OPS=no&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L175" href="#L175">175</a><span class="code-text">        &quot;./miri&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L176" href="#L176">176</a><span class="code-text">        &quot;cargo&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L177" href="#L177">177</a><span class="code-text">        &quot;clippy&quot;, // make this `check` when working with a locally built rustc</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L178" href="#L178">178</a><span class="code-text">        &quot;--message-format=json&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L179" href="#L179">179</a><span class="code-text">    ],</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L180" href="#L180">180</a><span class="code-text">    // Contrary to what the name suggests, this also affects proc macros.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L181" href="#L181">181</a><span class="code-text">    &quot;rust-analyzer.cargo.buildScripts.overrideCommand&quot;: [</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L182" href="#L182">182</a><span class="code-text">        &quot;env&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L183" href="#L183">183</a><span class="code-text">        &quot;MIRI_AUTO_OPS=no&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L184" href="#L184">184</a><span class="code-text">        &quot;./miri&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L185" href="#L185">185</a><span class="code-text">        &quot;cargo&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L186" href="#L186">186</a><span class="code-text">        &quot;check&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L187" href="#L187">187</a><span class="code-text">        &quot;--message-format=json&quot;,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L188" href="#L188">188</a><span class="code-text">    ],</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L189" href="#L189">189</a><span class="code-text">}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L190" href="#L190">190</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L191" href="#L191">191</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L192" href="#L192">192</a><span class="code-text">&gt; #### Note</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L193" href="#L193">193</a><span class="code-text">&gt;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L194" href="#L194">194</a><span class="code-text">&gt; If you are [building Miri with a locally built rustc][], set</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L195" href="#L195">195</a><span class="code-text">&gt; `rust-analyzer.rustcSource` to the relative path from your Miri clone to the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L196" href="#L196">196</a><span class="code-text">&gt; root `Cargo.toml` of the locally built rustc. For example, the path might look</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L197" href="#L197">197</a><span class="code-text">&gt; like `../rust/Cargo.toml`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L198" href="#L198">198</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L199" href="#L199">199</a><span class="code-text">See the rustc-dev-guide's docs on [&quot;Configuring `rust-analyzer` for `rustc`&quot;][rdg-r-a]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L200" href="#L200">200</a><span class="code-text">for more information about configuring VS Code and `rust-analyzer`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L201" href="#L201">201</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L202" href="#L202">202</a><span class="code-text">[rdg-r-a]: https://rustc-dev-guide.rust-lang.org/building/suggested.html#configuring-rust-analyzer-for-rustc</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L203" href="#L203">203</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L204" href="#L204">204</a><span class="code-text">## Advanced topic: Working on Miri in the rustc tree</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L205" href="#L205">205</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L206" href="#L206">206</a><span class="code-text">We described above the simplest way to get a working build environment for Miri,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L207" href="#L207">207</a><span class="code-text">which is to use the version of rustc indicated by `rustc-version`. But</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L208" href="#L208">208</a><span class="code-text">sometimes, that is not enough.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L209" href="#L209">209</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L210" href="#L210">210</a><span class="code-text">A big part of the Miri driver is shared with rustc, so working on Miri will</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L211" href="#L211">211</a><span class="code-text">sometimes require also working on rustc itself. In this case, you should *not*</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L212" href="#L212">212</a><span class="code-text">work in a clone of the Miri repository, but in a clone of the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L213" href="#L213">213</a><span class="code-text">[main Rust repository](https://github.com/rust-lang/rust/). There is a copy of</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L214" href="#L214">214</a><span class="code-text">Miri located at `src/tools/miri` that you can work on directly. A maintainer</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L215" href="#L215">215</a><span class="code-text">will eventually sync those changes back into this repository.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L216" href="#L216">216</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L217" href="#L217">217</a><span class="code-text">When working on Miri in the rustc tree, here's how you can run tests:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L218" href="#L218">218</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L219" href="#L219">219</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L220" href="#L220">220</a><span class="code-text">./x.py test miri --stage 0</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L221" href="#L221">221</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L222" href="#L222">222</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L223" href="#L223">223</a><span class="code-text">`--bless` will work, too.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L224" href="#L224">224</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L225" href="#L225">225</a><span class="code-text">You can also directly run Miri on a Rust source file:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L226" href="#L226">226</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L227" href="#L227">227</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L228" href="#L228">228</a><span class="code-text">./x.py run miri --stage 0 --args src/tools/miri/tests/pass/hello.rs</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L229" href="#L229">229</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L230" href="#L230">230</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L231" href="#L231">231</a><span class="code-text">## Advanced topic: Syncing with the rustc repo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L232" href="#L232">232</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L233" href="#L233">233</a><span class="code-text">We use the [`josh` proxy](https://github.com/josh-project/josh) to transmit changes between the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L234" href="#L234">234</a><span class="code-text">rustc and Miri repositories. You can install it as follows:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L235" href="#L235">235</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L236" href="#L236">236</a><span class="code-text">```sh</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L237" href="#L237">237</a><span class="code-text">cargo +stable install josh-proxy --git https://github.com/josh-project/josh --tag r22.12.06</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L238" href="#L238">238</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L239" href="#L239">239</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L240" href="#L240">240</a><span class="code-text">Josh will automatically be started and stopped by `./miri`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L241" href="#L241">241</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L242" href="#L242">242</a><span class="code-text">### Importing changes from the rustc repo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L243" href="#L243">243</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L244" href="#L244">244</a><span class="code-text">We assume we start on an up-to-date master branch in the Miri repo.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L245" href="#L245">245</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L246" href="#L246">246</a><span class="code-text">```sh</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L247" href="#L247">247</a><span class="code-text"># Fetch and merge rustc side of the history. Takes ca 5 min the first time.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L248" href="#L248">248</a><span class="code-text"># This will also update the 'rustc-version' file.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L249" href="#L249">249</a><span class="code-text">./miri rustc-pull</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L250" href="#L250">250</a><span class="code-text"># Update local toolchain and apply formatting.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L251" href="#L251">251</a><span class="code-text">./miri toolchain &amp;&amp; ./miri fmt</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L252" href="#L252">252</a><span class="code-text">git commit -am &quot;rustup&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L253" href="#L253">253</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L254" href="#L254">254</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L255" href="#L255">255</a><span class="code-text">Now push this to a new branch in your Miri fork, and create a PR. It is worth</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L256" href="#L256">256</a><span class="code-text">running `./miri test` locally in parallel, since the test suite in the Miri repo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L257" href="#L257">257</a><span class="code-text">is stricter than the one on the rustc side, so some small tweaks might be</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L258" href="#L258">258</a><span class="code-text">needed.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L259" href="#L259">259</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L260" href="#L260">260</a><span class="code-text">### Exporting changes to the rustc repo</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L261" href="#L261">261</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L262" href="#L262">262</a><span class="code-text">Keep in mind that pushing is the most complicated job that josh has to do -- pulling just filters</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L263" href="#L263">263</a><span class="code-text">the rustc history, but pushing needs to construct a new rustc history that would filter to the given</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L264" href="#L264">264</a><span class="code-text">Miri history! To avoid problems, it is a good idea to always pull immediately before you push. If</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L265" href="#L265">265</a><span class="code-text">you are getting strange errors, chances are you are running into [this josh</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L266" href="#L266">266</a><span class="code-text">bug](https://github.com/josh-project/josh/issues/998). In that case, please get in touch on Zulip.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L267" href="#L267">267</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L268" href="#L268">268</a><span class="code-text">We will use the josh proxy to push to your fork of rustc. Run the following in the Miri repo,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L269" href="#L269">269</a><span class="code-text">assuming we are on an up-to-date master branch:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L270" href="#L270">270</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L271" href="#L271">271</a><span class="code-text">```sh</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L272" href="#L272">272</a><span class="code-text"># Push the Miri changes to your rustc fork (substitute your github handle for YOUR_NAME).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L273" href="#L273">273</a><span class="code-text">./miri rustc-push YOUR_NAME miri</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L274" href="#L274">274</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L275" href="#L275">275</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L276" href="#L276">276</a><span class="code-text">This will create a new branch called 'miri' in your fork, and the output should</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L277" href="#L277">277</a><span class="code-text">include a link to create a rustc PR that will integrate those changes into the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L278" href="#L278">278</a><span class="code-text">main repository.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L279" href="#L279">279</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L280" href="#L280">280</a><span class="code-text">If this fails due to authentication problems, it can help to make josh push via ssh instead of</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L281" href="#L281">281</a><span class="code-text">https. Add the following to your `.gitconfig`:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L282" href="#L282">282</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L283" href="#L283">283</a><span class="code-text">```toml</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L284" href="#L284">284</a><span class="code-text">[url &quot;git@github.com:&quot;]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L285" href="#L285">285</a><span class="code-text">    pushInsteadOf = https://github.com/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L286" href="#L286">286</a><span class="code-text">```</span></span></pre></div></div>
</main>
</body>
</html>
