core/intrinsics/
mir.rs

1//! Rustc internal tooling for hand-writing MIR.
2//!
3//! If for some reasons you are not writing rustc tests and have found yourself considering using
4//! this feature, turn back. This is *exceptionally* unstable. There is no attempt at all to make
5//! anything work besides those things which the rustc test suite happened to need. If you make a
6//! typo you'll probably ICE. Really, this is not the solution to your problems. Consider instead
7//! supporting the [stable MIR project group](https://github.com/rust-lang/project-stable-mir).
8//!
9//! The documentation for this module describes how to use this feature. If you are interested in
10//! hacking on the implementation, most of that documentation lives at
11//! `rustc_mir_build/src/build/custom/mod.rs`.
12//!
13//! Typical usage will look like this:
14//!
15//! ```rust
16//! #![feature(core_intrinsics, custom_mir)]
17//! #![allow(internal_features)]
18//!
19//! use core::intrinsics::mir::*;
20//!
21//! #[custom_mir(dialect = "built")]
22//! pub fn simple(x: i32) -> i32 {
23//!     mir! {
24//!         let temp2: i32;
25//!
26//!         {
27//!             let temp1 = x;
28//!             Goto(my_second_block)
29//!         }
30//!
31//!         my_second_block = {
32//!             temp2 = Move(temp1);
33//!             RET = temp2;
34//!             Return()
35//!         }
36//!     }
37//! }
38//! ```
39//!
40//! The `custom_mir` attribute tells the compiler to treat the function as being custom MIR. This
41//! attribute only works on functions - there is no way to insert custom MIR into the middle of
42//! another function. The `dialect` and `phase` parameters indicate which [version of MIR][dialect
43//! docs] you are inserting here. Generally you'll want to use `#![custom_mir(dialect = "built")]`
44//! if you want your MIR to be modified by the full MIR pipeline, or `#![custom_mir(dialect =
45//! "runtime", phase = "optimized")]` if you don't.
46//!
47//! [dialect docs]:
48//!     https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/enum.MirPhase.html
49//!
50//! The input to the [`mir!`] macro is:
51//!
52//!  - An optional return type annotation in the form of `type RET = ...;`. This may be required
53//!    if the compiler cannot infer the type of RET.
54//!  - A possibly empty list of local declarations. Locals can also be declared inline on
55//!    assignments via `let`. Type inference generally works. Shadowing does not.
56//!  - A list of basic blocks. The first of these is the start block and is where execution begins.
57//!    All blocks other than the start block need to be given a name, so that they can be referred
58//!    to later.
59//!     - Each block is a list of semicolon terminated statements, followed by a terminator. The
60//!       syntax for the various statements and terminators is designed to be as similar as pos