Reference complete examples

examples/rustc-driver-example.rs

@@ -1,17 +1,20 @@
 #![feature(rustc_private)]
 
+// NOTE: For the example to compile, you will need to first run the following:
+//   rustup component add rustc-dev
+
 extern crate rustc;
 extern crate rustc_error_codes;
 extern crate rustc_errors;
 extern crate rustc_hash;
 extern crate rustc_hir;
 extern crate rustc_interface;
+extern crate rustc_session;
 extern crate rustc_span;
 
-use rustc::session;
-use rustc::session::config;
 use rustc_errors::registry;
 use rustc_hash::{FxHashMap, FxHashSet};
+use rustc_session::config;
 use rustc_span::source_map;
 use std::path;
 use std::process;
@@ -24,60 +27,41 @@ fn main() {
         .output()
         .unwrap();
     let sysroot = str::from_utf8(&out.stdout).unwrap().trim();
-    let filename = "main.rs";
-    let contents = "static HELLO: &str = \"Hello, world!\"; fn main() { println!(\"{}\", HELLO); }";
-    let errors = registry::Registry::new(&rustc_error_codes::DIAGNOSTICS);
     let config = rustc_interface::Config {
         // Command line options
         opts: config::Options {
             maybe_sysroot: Some(path::PathBuf::from(sysroot)),
             ..config::Options::default()
         },
-
         // cfg! configuration in addition to the default ones
-        // FxHashSet<(String, Option<String>)>
+        crate_cfg: FxHashSet::default(), // FxHashSet<(String, Option<String>)>
-        crate_cfg: FxHashSet::default(),
-
         input: config::Input::Str {
-            name: source_map::FileName::Custom(String::from(filename)),
+            name: source_map::FileName::Custom("main.rs".to_string()),
-            input: String::from(contents),
+            input: "static HELLO: &str = \"Hello, world!\"; fn main() { println!(\"{}\", HELLO); }"
+                .to_string(),
         },
-        // Option<PathBuf>
+        input_path: None,  // Option<PathBuf>
-        input_path: None,
+        output_dir: None,  // Option<PathBuf>
-        // Option<PathBuf>
+        output_file: None, // Option<PathBuf>
-        output_dir: None,
+        file_loader: None, // Option<Box<dyn FileLoader + Send + Sync>>
-        // Option<PathBuf>
+        diagnostic_output: rustc_session::DiagnosticOutput::Default,
-        output_file: None,
-        // Option<Box<dyn FileLoader + Send + Sync>>
-        file_loader: None,
-        diagnostic_output: session::DiagnosticOutput::Default,
-
         // Set to capture stderr output during compiler execution
-        // Option<Arc<Mutex<Vec<u8>>>>
+        stderr: None,                    // Option<Arc<Mutex<Vec<u8>>>>
-        stderr: None,
+        crate_name: None,                // Option<String>
-
+        lint_caps: FxHashMap::default(), // FxHashMap<lint::LintId, lint::Level>
-        // Option<String>
-        crate_name: None,
-        // FxHashMap<lint::LintId, lint::Level>
-        lint_caps: FxHashMap::default(),
-
         // This is a callback from the driver that is called when we're registering lints;
         // it is called during plugin registration when we have the LintStore in a non-shared state.
         //
         // Note that if you find a Some here you probably want to call that function in the new
         // function being registered.
-        // Option<Box<dyn Fn(&Session, &mut LintStore) + Send + Sync>>
+        register_lints: None, // Option<Box<dyn Fn(&Session, &mut LintStore) + Send + Sync>>
-        register_lints: None,
-
         // This is a callback from the driver that is called just after we have populated
         // the list of queries.
         //
         // The second parameter is local providers and the third parameter is external providers.
-        // Option<fn(&Session, &mut ty::query::Providers<'_>, &mut ty::query::Providers<'_>)>
+        override_queries: None, // Option<fn(&Session, &mut ty::query::Providers<'_>, &mut ty::query::Providers<'_>)>
-        override_queries: None,
-
         // Registry of diagnostics codes.
-        registry: errors,
+        registry: registry::Registry::new(&rustc_error_codes::DIAGNOSTICS),
     };
     rustc_interface::run_compiler(config, |compiler| {
         compiler.enter(|queries| {

examples/rustc-driver-getting-diagnostics.rs

@@ -0,0 +1,89 @@
+#![feature(rustc_private)]
+
+// NOTE: For the example to compile, you will need to first run the following:
+//   rustup component add rustc-dev
+
+extern crate rustc;
+extern crate rustc_error_codes;
+extern crate rustc_errors;
+extern crate rustc_hash;
+extern crate rustc_hir;
+extern crate rustc_interface;
+extern crate rustc_session;
+extern crate rustc_span;
+
+use rustc_errors::registry;
+use rustc_session::config;
+use rustc_span::source_map;
+use std::io;
+use std::path;
+use std::process;
+use std::str;
+use std::sync;
+
+// Buffer diagnostics in a Vec<u8>.
+#[derive(Clone)]
+pub struct DiagnosticSink(sync::Arc<sync::Mutex<Vec<u8>>>);
+
+impl io::Write for DiagnosticSink {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        self.0.lock().unwrap().write(buf)
+    }
+    fn flush(&mut self) -> io::Result<()> {
+        self.0.lock().unwrap().flush()
+    }
+}
+
+fn main() {
+    let out = process::Command::new("rustc")
+        .arg("--print=sysroot")
+        .current_dir(".")
+        .output()
+        .unwrap();
+    let sysroot = str::from_utf8(&out.stdout).unwrap().trim();
+    let buffer = sync::Arc::new(sync::Mutex::new(Vec::new()));
+    let config = rustc_interface::Config {
+        opts: config::Options {
+            maybe_sysroot: Some(path::PathBuf::from(sysroot)),
+            // Configure the compiler to emit diagnostics in compact JSON format.
+            error_format: config::ErrorOutputType::Json {
+                pretty: false,
+                json_rendered: rustc_errors::emitter::HumanReadableErrorType::Default(
+                    rustc_errors::emitter::ColorConfig::Never,
+                ),
+            },
+            ..config::Options::default()
+        },
+        // This program contains a type error.
+        input: config::Input::Str {
+            name: source_map::FileName::Custom("main.rs".to_string()),
+            input: "fn main() { let x: &str = 1; }".to_string(),
+        },
+        // Redirect the diagnostic output of the compiler to a buffer.
+        diagnostic_output: rustc_session::DiagnosticOutput::Raw(Box::from(DiagnosticSink(
+            buffer.clone(),
+        ))),
+        crate_cfg: rustc_hash::FxHashSet::default(),
+        input_path: None,
+        output_dir: None,
+        output_file: None,
+        file_loader: None,
+        stderr: None,
+        crate_name: None,
+        lint_caps: rustc_hash::FxHashMap::default(),
+        register_lints: None,
+        override_queries: None,
+        registry: registry::Registry::new(&rustc_error_codes::DIAGNOSTICS),
+    };
+    rustc_interface::run_compiler(config, |compiler| {
+        compiler.enter(|queries| {
+            queries.global_ctxt().unwrap().take().enter(|tcx| {
+                // Run the analysis phase on the local crate to trigger the type error.
+                tcx.analysis(rustc_hir::def_id::LOCAL_CRATE);
+            });
+        });
+    });
+    // Read buffered diagnostics.
+    let diagnostics = String::from_utf8(buffer.lock().unwrap().clone()).unwrap();
+    println!("{}", diagnostics);
+}

examples/rustc-driver-interacting-with-the-ast.rs

@@ -0,0 +1,78 @@
+#![feature(rustc_private)]
+
+// NOTE: For the example to compile, you will need to first run the following:
+//   rustup component add rustc-dev
+
+extern crate rustc;
+extern crate rustc_error_codes;
+extern crate rustc_errors;
+extern crate rustc_hash;
+extern crate rustc_hir;
+extern crate rustc_interface;
+extern crate rustc_session;
+extern crate rustc_span;
+
+use rustc_errors::registry;
+use rustc_session::config;
+use rustc_span::source_map;
+use std::path;
+use std::process;
+use std::str;
+
+fn main() {
+    let out = process::Command::new("rustc")
+        .arg("--print=sysroot")
+        .current_dir(".")
+        .output()
+        .unwrap();
+    let sysroot = str::from_utf8(&out.stdout).unwrap().trim();
+    let config = rustc_interface::Config {
+        opts: config::Options {
+            maybe_sysroot: Some(path::PathBuf::from(sysroot)),
+            ..config::Options::default()
+        },
+        input: config::Input::Str {
+            name: source_map::FileName::Custom("main.rs".to_string()),
+            input: "fn main() { let message = \"Hello, world!\"; println!(\"{}\", message); }"
+                .to_string(),
+        },
+        diagnostic_output: rustc_session::DiagnosticOutput::Default,
+        crate_cfg: rustc_hash::FxHashSet::default(),
+        input_path: None,
+        output_dir: None,
+        output_file: None,
+        file_loader: None,
+        stderr: None,
+        crate_name: None,
+        lint_caps: rustc_hash::FxHashMap::default(),
+        register_lints: None,
+        override_queries: None,
+        registry: registry::Registry::new(&rustc_error_codes::DIAGNOSTICS),
+    };
+    rustc_interface::run_compiler(config, |compiler| {
+        compiler.enter(|queries| {
+            // Analyze the crate and inspect the types under the cursor.
+            queries.global_ctxt().unwrap().take().enter(|tcx| {
+                // Every compilation contains a single crate.
+                let krate = tcx.hir().krate();
+                // Iterate over the top-level items in the crate, looking for the main function.
+                for (_, item) in &krate.items {
+                    // Use pattern-matching to find a specific node inside the main function.
+                    if let rustc_hir::ItemKind::Fn(_, _, body_id) = item.kind {
+                        let expr = &tcx.hir().body(body_id).value;
+                        if let rustc_hir::ExprKind::Block(block, _) = expr.kind {
+                            if let rustc_hir::StmtKind::Local(local) = block.stmts[0].kind {
+                                if let Some(expr) = local.init {
+                                    let hir_id = expr.hir_id; // hir_id identifies the string "Hello, world!"
+                                    let def_id = tcx.hir().local_def_id(item.hir_id); // def_id identifies the main function
+                                    let ty = tcx.typeck_tables_of(def_id).node_type(hir_id);
+                                    println!("{:?}: {:?}", expr, ty); // prints expr(HirId { owner: DefIndex(3), local_id: 4 }: "Hello, world!"): &'static str
+                                }
+                            }
+                        }
+                    }
+                }
+            })
+        });
+    });
+}

src/rustc-driver-getting-diagnostics.md

@@ -4,100 +4,38 @@
 
 ## Getting diagnostics
 
-NOTE: For the example to compile, you will need to first run the following:
-
-    rustup component add rustc-dev
-
 To get diagnostics from the compiler, 
 configure `rustc_interface::Config` to output diagnostic to a buffer, 
 and run `TyCtxt.analysis`:
 
 ```rust
-#![feature(rustc_private)]
+// See https://github.com/rust-lang/rustc-dev-guide/blob/master/examples/rustc-driver-getting-diagnostics.rs for complete program.
-
+let buffer = sync::Arc::new(sync::Mutex::new(Vec::new()));
-extern crate rustc;
+let config = rustc_interface::Config {
-extern crate rustc_error_codes;
+    opts: config::Options {
-extern crate rustc_errors;
+        // Configure the compiler to emit diagnostics in compact JSON format.
-extern crate rustc_hash;
+        error_format: config::ErrorOutputType::Json {
-extern crate rustc_hir;
+            pretty: false,
-extern crate rustc_interface;
+            json_rendered: rustc_errors::emitter::HumanReadableErrorType::Default(
-extern crate rustc_session;
+                rustc_errors::emitter::ColorConfig::Never,
-extern crate rustc_span;
+            ),
-
-use rustc_errors::registry;
-use rustc_session::config;
-use rustc_span::source_map;
-use std::io;
-use std::path;
-use std::process;
-use std::str;
-use std::sync;
-
-// Buffer diagnostics in a Vec<u8>.
-#[derive(Clone)]
-pub struct DiagnosticSink(sync::Arc<sync::Mutex<Vec<u8>>>);
-
-impl io::Write for DiagnosticSink {
-    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
-        self.0.lock().unwrap().write(buf)
-    }
-    fn flush(&mut self) -> io::Result<()> {
-        self.0.lock().unwrap().flush()
-    }
-}
-
-fn main() {
-    let out = process::Command::new("rustc")
-        .arg("--print=sysroot")
-        .current_dir(".")
-        .output()
-        .unwrap();
-    let sysroot = str::from_utf8(&out.stdout).unwrap().trim();
-    let buffer = sync::Arc::new(sync::Mutex::new(Vec::new()));
-    let config = rustc_interface::Config {
-        opts: config::Options {
-            maybe_sysroot: Some(path::PathBuf::from(sysroot)),
-            // Configure the compiler to emit diagnostics in compact JSON format.
-            error_format: config::ErrorOutputType::Json {
-                pretty: false,
-                json_rendered: rustc_errors::emitter::HumanReadableErrorType::Default(
-                    rustc_errors::emitter::ColorConfig::Never,
-                ),
-            },
-            ..config::Options::default()
         },
-        // This program contains a type error.
+        /* other config */
-        input: config::Input::Str {
+    },
-            name: source_map::FileName::Custom("main.rs".to_string()),
+    // Redirect the diagnostic output of the compiler to a buffer.
-            input: "fn main() { let x: &str = 1; }".to_string(),
+    diagnostic_output: rustc_session::DiagnosticOutput::Raw(Box::from(DiagnosticSink(
-        },
+        buffer.clone(),
-        // Redirect the diagnostic output of the compiler to a buffer.
+    ))),
-        diagnostic_output: rustc_session::DiagnosticOutput::Raw(Box::from(DiagnosticSink(
+    /* other config */
-            buffer.clone(),
+};
-        ))),
+rustc_interface::run_compiler(config, |compiler| {
-        crate_cfg: rustc_hash::FxHashSet::default(),
+    compiler.enter(|queries| {
-        input_path: None,
+        queries.global_ctxt().unwrap().take().enter(|tcx| {
-        output_dir: None,
+            // Run the analysis phase on the local crate to trigger the type error.
-        output_file: None,
+            tcx.analysis(rustc_hir::def_id::LOCAL_CRATE);
-        file_loader: None,
-        stderr: None,
-        crate_name: None,
-        lint_caps: rustc_hash::FxHashMap::default(),
-        register_lints: None,
-        override_queries: None,
-        registry: registry::Registry::new(&rustc_error_codes::DIAGNOSTICS),
-    };
-    rustc_interface::run_compiler(config, |compiler| {
-        compiler.enter(|queries| {
-            queries.global_ctxt().unwrap().take().enter(|tcx| {
-                // Run the analysis phase on the local crate to trigger the type error.
-                tcx.analysis(rustc_hir::def_id::LOCAL_CRATE);
-            });
         });
     });
-    // Read and print buffered diagnostics.
+});
-    let diagnostics = String::from_utf8(buffer.lock().unwrap().clone()).unwrap();
+// Read buffered diagnostics.
-    println!("{}", diagnostics);
+let diagnostics = String::from_utf8(buffer.lock().unwrap().clone()).unwrap();
-}
-
 ```

src/rustc-driver-interacting-with-the-ast.md

@@ -4,18 +4,18 @@
 
 ## Getting the type of an expression
 
-NOTE: For the example to compile, you will need to first run the following:
-
-    rustup component add rustc-dev
-
 To get the type of an expression, use the `global_ctxt` to get a `TyCtxt`:
 
 ```rust
-// In this example, config specifies the rust program:
+// See https://github.com/rust-lang/rustc-dev-guide/blob/master/examples/rustc-driver-interacting-with-the-ast.rs for complete program.
-//   fn main() { let message = \"Hello, world!\"; println!(\"{}\", message); }
+let config = rustc_interface::Config {
-// Our goal is to get the type of the string literal "Hello, world!".
+    input: config::Input::Str {
-//
+        name: source_map::FileName::Custom("main.rs".to_string()),
-// See https://github.com/rust-lang/rustc-dev-guide/blob/master/examples/rustc-driver-example.rs for a complete example of configuring rustc_interface
+        input: "fn main() { let message = \"Hello, world!\"; println!(\"{}\", message); }"
+            .to_string(),
+    },
+    /* other config */
+};
 rustc_interface::run_compiler(config, |compiler| {
     compiler.enter(|queries| {
         // Analyze the crate and inspect the types under the cursor.