diff --git a/.github/workflows/deploy_mdbook.yml b/.github/workflows/deploy_mdbook.yml index 235ff91..f37de59 100644 --- a/.github/workflows/deploy_mdbook.yml +++ b/.github/workflows/deploy_mdbook.yml @@ -19,12 +19,12 @@ jobs: run: cargo install mdbook --version "^0.4" --locked - name: Run mdbook - run: mdbook build + run: mdbook build book - name: Upload book uses: actions/upload-pages-artifact@v2 with: - path: book/ + path: book/build retention-days: "3" - name: Deploy Book @@ -32,5 +32,5 @@ jobs: if: ${{ github.event_name == 'push' && startsWith('refs/heads/main', github.ref) }} with: branch: gh-pages - folder: book/ + folder: book/build single-commit: true diff --git a/.gitignore b/.gitignore index 9262d70..b68cfbd 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ -/book +/book/build **/target .idea diff --git a/README.md b/README.md index 823135d..39c6347 100644 --- a/README.md +++ b/README.md @@ -20,21 +20,16 @@ API based on the rust compiler mid-level intermediate representation (MIR) that for development of tools that want to perform sophisticated analyses and make stronger guarantees about the behavior of Rust programs. +This is the repository we use to organise and document our work. -This is the repository we use to organise our work. Please refer to our [charter] as well -as our [github pages website][gh-pages] for more information on our goals and -current scope. +If you are wondering how to use Stable MIR in your project, please check out the [Getting Started][tutorial] chapter. -If you are wondering how to use Stable MIR in your project, also see the [rustc_smir crate][rustc_smir]. - -[charter]: ./CHARTER.md [gh-pages]: https://rust-lang.github.io/project-stable-mir -[rustc_smir]: https://github.com/rust-lang/rust/tree/master/compiler/rustc_smir +[tutorial]: https://rust-lang.github.io/project-stable-mir/getting-started.html ## How Can I Get Involved? - [You can find a list of the current members available on `rust-lang/team`.][team-toml] @@ -46,5 +41,7 @@ yourself over there and ask us any questions you have. [open issues]: https://github.com/rust-lang/project-stable-mir/issues + [chat-link]: https://rust-lang.zulipchat.com/#narrow/stream/320896-project-stable-mir + [team-toml]: https://github.com/rust-lang/team/blob/master/teams/project-stable-mir.toml diff --git a/SUMMARY.md b/SUMMARY.md deleted file mode 100644 index 6ff8301..0000000 --- a/SUMMARY.md +++ /dev/null @@ -1,7 +0,0 @@ -# Summary - -- [Welcome](./README.md) -- [Charter](./CHARTER.md) -- [Meetings](./meetings/README.md) -- [Draft RFCs](./draft-rfcs/README.md) -- [Developer Documentation](./dev/README.md) diff --git a/book.toml b/book.toml deleted file mode 100644 index 93b82ea..0000000 --- a/book.toml +++ /dev/null @@ -1,10 +0,0 @@ -[book] -authors = ["{{GROUP_NAME}} Members"] -language = "en" -multilingual = false -src = "." -title = "{{GROUP_NAME}} {{GROUP_TYPE}} Group" - -[output.html] -no-section-label=true -git-repository-url="https://github.com/rust-lang/{{GROUP_SLUG}}" diff --git a/book/book.toml b/book/book.toml new file mode 100644 index 0000000..5151850 --- /dev/null +++ b/book/book.toml @@ -0,0 +1,17 @@ +[book] +title = "Stable MIR Librarification Project" +language = "en" + +[output.html] +curly-quotes = true +git-repository-url = "https://github.com/rust-lang/project-stable-mir" +site-url = "/project-stable-mir/" + +[output.html.playground] +runnable = false + +[rust] +edition = "2021" + +[build] +build-dir = "build" \ No newline at end of file diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md new file mode 100644 index 0000000..4a13297 --- /dev/null +++ b/book/src/SUMMARY.md @@ -0,0 +1,8 @@ +# Project StableMIR + +- [Welcome](./welcome.md) +- [Getting Started](./getting-started.md) + - [Initial Integration](./initial.md) + - [Migrating to StableMIR](./migrating.md) + - [Tool Development: Tips and Tricks](./tricks.md) +- [Contributing](./contributing.md) \ No newline at end of file diff --git a/dev/README.md b/book/src/contributing.md similarity index 100% rename from dev/README.md rename to book/src/contributing.md diff --git a/book/src/getting-started.md b/book/src/getting-started.md new file mode 100644 index 0000000..5d0750c --- /dev/null +++ b/book/src/getting-started.md @@ -0,0 +1,29 @@ +# Getting Started + +The StableMIR APIs are currently exposed as a crate in the compiler named `stable_mir`[^release]. +This crate includes the definition of structures and methods to be stabilized, +which are expected to become the stable APIs in the compiler. + +These APIs were designed to provide information about a Rust crate, including the body of functions, as well as type +and layout information. + +This chapter has two sections directed at different use cases. + +1. If you already have a crate that uses some of the Rust compiler libraries, + and you are interested in migrating them to the StableMIR APIs, + you can find more details about your use case at the [Migrating to StableMIR](./migrating.md) section. +2. If you are starting your integration with the Rust compiler via StableMIR, we recommend reading through the + [Initial Integration](./initial.md) chapter. + +We also include a [Tips and Tricks](./tricks.md) section that is related to a few common obstacles tool writers +encounter, +that is not directly related to the `stable_mir` crate and APIs. + +Our repository also includes a little [demo crate](https://github.com/rust-lang/project-stable-mir/tree/main/demo) that +demonstrate how `stable_mir` crate can be used to analyze the main function of a crate. + +The latest crate documentation can be found in the +[nightly documentation here](https://doc.rust-lang.org/nightly/nightly-rustc/stable_mir/index.html) + +[^release]: We are planning to release the `stable_mir` crate into crates.io in the near future. +See issue [#0030](https://github.com/rust-lang/project-stable-mir/issues/30) for the current release status. diff --git a/book/src/initial.md b/book/src/initial.md new file mode 100644 index 0000000..a0b95c9 --- /dev/null +++ b/book/src/initial.md @@ -0,0 +1,119 @@ +# Initial Integration + +In order to use `stable_mir` in your crate, you will need to do the following: + +1. Use a nightly toolchain that includes the `stable_mir` crate. +2. Install at least the following rustup components: "rustc-dev" and "llvm-tools" +3. Declare `stable_mir` as an external crate at the top of your crate: + +```rust +extern crate stable_mir; +``` + +For 1 and 2, we highly recommend adding a "rust-toolchain.toml" file to your project. +We also recommend to pin down a specific nightly version, to ensure all users and tests are using the same compiler +version. +Therefore, the same `stable_mir` crate version. E.g.: + +```toml +# Example of a rust-toolchain.toml +[toolchain] +# Update the date to change the toolchain version. +channel = "nightly-2024-06-17" +components = ["llvm-tools", "rustc-dev", "rust-src"] +``` + +## Initializing StableMIR + +There's currently no stable way to initialize the Rust compiler and StableMIR. +See [#0069](https://github.com/rust-lang/project-stable-mir/issues/69) for more details. + +Instead, StableMIR includes two unstable workarounds to give you a quick start. +The `run` and `run_with_tcx` macros, both from present in the `rustc_smir` crate. + +In order to use the `run` macro, you first need to declare the following external crates: + +```rust +extern crate rustc_driver; +extern crate rustc_interface; +#[macro_use] +extern crate rustc_smir; +// This one you should know already. =) +extern crate stable_mir; +``` + +Then start the driver using the `run!()` macro: + +```rust + let result = run!(rustc_args, callback_fn); +``` + +This macro takes two arguments: + +1. A vector with the command arguments to the compiler. +2. A callback function, which can either be a closure expression or a function ident. + - This callback function shouldn't take any argument, and it should return a `ControlFlow`. + +It will trigger the compilation in the current process, with the provided arguments, and invoke the callback after the +compiler ran all its analyses, but before code generation. + +The macro will return a `Result>` representing the compilation result and the callback return value. + +The second option is the `run_with_tcx!()` macro, which is very similar to the `run` macro. +The main difference is that this macro passes a copy of the Rust compiler context (`TyCtxt`) to the callback, +which allows the user to also make calls to internal compiler APIs. + +Note that this option also requires the declaration of the `rustc_middle` external crate, i.e., you should now have the +following declarations: + +```rust +extern crate rustc_driver; +extern crate rustc_interface; +extern crate rustc_middle; // This one is new! +#[macro_use] +extern crate rustc_smir; +extern crate stable_mir; +``` + +## Scope of StableMIR objects + +StableMIR objects should not be used outside the scope of the callback function. +Any usage outside this scope can panic or return an incorrect value. + +For example, the following code is valid, since the logic we are storing is only used while the callback function +is running: + +```rust +fn print_items(rustc_args: Vec) { + let _result = run!(rustc_args, || { + for item in stable_mir::all_local_items() { + // Using items inside the callback! + println!(" - {}", item.name()) + } + }); +} +``` + +However, the following usage isn't valid, and `stable_mir` will crash when we invoke the `name()` function. + +```rust +fn broken_print_items(rustc_args: Vec) { + let result = run!(rustc_args, || { ControlFlow::Continue(stable_mir::all_local_items())}); + if let ControlFlow::Continue(items) = result { + for item in items { + // Using item outside the callback function is wrong! + println!(" - {}", item.name()) + } + } +} +``` + +StableMIR objects should also not be shared across different threads. + +## Analyzing crate definitions + +TODO + +## Analyzing monomorphic instances + +TODO \ No newline at end of file diff --git a/book/src/migrating.md b/book/src/migrating.md new file mode 100644 index 0000000..10228e7 --- /dev/null +++ b/book/src/migrating.md @@ -0,0 +1,4 @@ +# Migrating to StableMIR + +For now, we recommend looking at +the [Kani migration documentation](https://model-checking.github.io/kani/stable-mir.html). \ No newline at end of file diff --git a/book/src/tricks.md b/book/src/tricks.md new file mode 100644 index 0000000..d8c1191 --- /dev/null +++ b/book/src/tricks.md @@ -0,0 +1,32 @@ +# Tricks and tips + +The goal of this project is to provide an interface to the Rust compiler that can be used to empower users to build +their own analysis tools. +Most of these tools, however, have similar requirements that goes beyond analyzing with the Rust compiler IR. +For example, most tools want to be able to analyze cargo crates, including their dependencies. + +In this section, we document a few tricks that we found useful while developing different Rust analysis tools. + +## Storing MIR for dependencies + +There is a compiler flag, `-Z always-encode-mir`, that can be used for storing the MIR of all functions in the crate +metadata. + +## Handling the Std Library + +Either use `Xargo` or `cargo -Z build-std` to build a new version of the std library that includes the MIR body of +all functions. + +You can then use the compiler `--sysroot` argument to point to the version you compiled. + +## Enabling Rust Analyzer for compiler crates + +1. Ensure that any crate that use rustc data structures have the following configuration in their `Cargo.toml` + +```toml +[package.metadata.rust-analyzer] +rustc_private = true +``` + +2. Set the `rust-analyzer.rustc.source` to "discover". + See [Rust Analyzer manual](https://rust-analyzer.github.io/manual.html) for more advanced options. \ No newline at end of file diff --git a/book/src/welcome.md b/book/src/welcome.md new file mode 120000 index 0000000..fe84005 --- /dev/null +++ b/book/src/welcome.md @@ -0,0 +1 @@ +../../README.md \ No newline at end of file diff --git a/draft-rfcs/README.md b/draft-rfcs/README.md deleted file mode 100644 index 23f6932..0000000 --- a/draft-rfcs/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# RFC drafts - -This folder contains drafts of RFCs that the group is preparing to submit. - - diff --git a/meetings/README.md b/meetings/README.md deleted file mode 100644 index ff3da0c..0000000 --- a/meetings/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# Meetings - -This folder contains the minutes of all the recorded meetings that have happened -so far.