Move book to the book/ folder and add content

.github/workflows/deploy_mdbook.yml

@@ -19,18 +19,18 @@ 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
  uses: JamesIves/github-pages-deploy-action@v4
  if: ${{ github.event_name == 'push' && startsWith('refs/heads/main', github.ref) }}
  with:
  branch: gh-pages
- folder: book/
+ folder: book/build
  single-commit: true

.gitignore

@@ -1,4 +1,4 @@
-/book
+/book/build
 **/target
 
 .idea

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

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"

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)

book/src/getting-started.md

@@ -0,0 +1,26 @@
+# 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.
+
+[^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.

book/src/initial.md

@@ -0,0 +1,68 @@
+# 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 component: "rustc-dev"
+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 = ["rustc-dev"]
+```
+
+## 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<B,C>`.
+
+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<C, CompilerError<B>>` representing the compilation result and the callback return value.
+
+## Analyzing crate definitions
+
+TODO
+
+## Analyzing monomorphic instances
+
+TODO

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).

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.

book/src/welcome.md

@@ -0,0 +1 @@
+../../README.md