From a05f547641362bc1517c0e39d39f0b0f1d42d8cf Mon Sep 17 00:00:00 2001 From: Alona Enraght-Moony Date: Mon, 27 Oct 2025 21:08:23 +0000 Subject: [PATCH] book: Update "Initial Integration" to rustc_public name I went through the "Initial Integration" and fixed references to the old project name, and cleaned up bits that were confusing: - Add link to `demo/`, to show a complete version - Replace references to `stable_mir` with `rustc_public` - Reference recent nightly toolchain - Document need for `#![feature(rustc_private)]` - Invoke `run!` macro qualified, instead of via `#[macro_use]` - Give type of arguments to `run!` - Don't duplicate list of `extern crate`s --- book/src/initial.md | 52 ++++++++++++++++++++------------------------- 1 file changed, 23 insertions(+), 29 deletions(-) diff --git a/book/src/initial.md b/book/src/initial.md index 9556b30..75c210f 100644 --- a/book/src/initial.md +++ b/book/src/initial.md @@ -1,25 +1,29 @@ # Initial Integration -In order to use `stable_mir` in your crate, you will need to do the following: +For an example of how to use `rustc_public`, see the [`demo/`] directory of the project-stable-mir repo. +For a tutorial, read on! -1. Use a nightly toolchain that includes the `stable_mir` crate. +In order to use `rustc_public` in your crate, you will need to do the following: + +1. Use a nightly toolchain that includes the `rustc_public` 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: +3. Declare `rustc_public` as an external crate at the top of your crate: ```rust -extern crate stable_mir; +#![feature(rustc_private)] +extern crate rustc_public; ``` 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.: +Therefore, the same `rustc_public` 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" +channel = "nightly-2025-10-27" components = ["llvm-tools", "rustc-dev", "rust-src"] ``` @@ -29,28 +33,28 @@ 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. +The `run` and `run_with_tcx` macros, both from present in the `rustc_public` crate. In order to use the `run` macro, you first need to declare the following external crates: ```rust +#![feature(rustc_private)] +extern crate rustc_public; + extern crate rustc_driver; extern crate rustc_interface; -#[macro_use] -extern crate rustc_smir; -// This one you should know already. =) -extern crate stable_mir; +extern crate rustc_middle; ``` Then start the driver using the `run!()` macro: ```rust - let result = run!(rustc_args, callback_fn); +let result = rustc_public::run!(rustc_args, callback_fn); ``` This macro takes two arguments: -1. A vector with the command arguments to the compiler. +1. A `&[String]` with the command line 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`. @@ -63,18 +67,6 @@ The second option is the `run_with_tcx!()` macro, which is very similar to the ` 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. @@ -86,7 +78,7 @@ is running: ```rust fn print_items(rustc_args: Vec) { let _result = run!(rustc_args, || { - for item in stable_mir::all_local_items() { + for item in rustc_public::all_local_items() { // Using items inside the callback! println!(" - {}", item.name()) } @@ -94,11 +86,11 @@ fn print_items(rustc_args: Vec) { } ``` -However, the following usage isn't valid, and `stable_mir` will panic when we invoke the `name()` function. +However, the following usage isn't valid, and `rustc_public` will panic 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())}); + let result = run!(rustc_args, || { ControlFlow::Continue(rustc_public::all_local_items())}); if let ControlFlow::Continue(items) = result { for item in items { // Using item outside the callback function is wrong! @@ -116,4 +108,6 @@ TODO ## Analyzing monomorphic instances -TODO \ No newline at end of file +TODO + +[`demo/`](https://github.com/rust-lang/project-stable-mir/tree/main/demo) \ No newline at end of file