Move the book to book/ folder and add more content (#84)

Started a "Getting Started" guide, and added a few tips.

Related to #76

Co-authored-by: Oli Scherer <github35764891676564198441@oli-obk.de>

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

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<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.
+
+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<String>) {
+    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 panic when we invoke the `name()` function.
+
+```rust
+fn broken_print_items(rustc_args: Vec<String>) {
+    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

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

demo/rust-toolchain.toml

@@ -1,3 +1,5 @@
 [toolchain]
-channel = "nightly-2024-04-02"
-components = ["llvm-tools-preview", "rustc-dev", "rust-src", "rustfmt"]
+# Most users will want to pin down a specific version, e.g.:
+# channel = "nightly-2024-06-17"
+channel = "nightly"
+components = ["llvm-tools", "rustc-dev", "rust-src"]