add relnotes-api-list tool

Author: pietroalbini

Cargo.lock

@@ -3111,6 +3111,16 @@ version = "0.8.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2b15c43186be67a4fd63bee50d0303afffcef381492ebe2c5d87f324e1b8815c"
 
+[[package]]
+name = "relnotes-api-list"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "rustdoc-json-types",
+ "serde",
+ "serde_json",
+]
+
 [[package]]
 name = "remote-test-client"
 version = "0.1.0"

Cargo.toml

@@ -30,6 +30,7 @@ members = [
   "src/tools/miri/cargo-miri",
   "src/tools/miropt-test-tools",
   "src/tools/opt-dist",
+  "src/tools/relnotes-api-list",
   "src/tools/remote-test-client",
   "src/tools/remote-test-server",
   "src/tools/replace-version-placeholder",

src/bootstrap/src/core/build_steps/dist.rs

@@ -2616,3 +2616,49 @@ impl Step for Gcc {
         tarball.generate()
     }
 }
+
+#[derive(Clone, Debug, Eq, PartialEq, Hash)]
+pub struct RelnotesApiList {
+    pub host: TargetSelection,
+}
+
+impl Step for RelnotesApiList {
+    type Output = ();
+    const DEFAULT: bool = true;
+
+    fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
+        let default = run.builder.config.docs;
+        run.alias("relnotes-api-list").default_condition(default)
+    }
+
+    fn make_run(run: RunConfig<'_>) {
+        run.builder.ensure(RelnotesApiList { host: run.target });
+    }
+
+    fn run(self, builder: &Builder<'_>) -> Self::Output {
+        let host = self.host;
+        let dest = builder.out.join("dist").join(format!("relnotes-api-list-{host}.json"));
+        builder.create_dir(dest.parent().unwrap());
+
+        if std::env::var_os("EMILY_SKIP_DOC").is_none() { // TODO: remove the condition
+            builder.ensure(
+                crate::core::build_steps::doc::Std::new(
+                    builder.top_stage,
+                    host,
+                    DocumentationFormat::Json,
+                )
+                // Crates containing symbols exported by any std crate:
+                .add_extra_crate("rustc-literal-escaper")
+                .add_extra_crate("std_detect"),
+            );
+        }
+
+        builder.info("Generating the API list for the release notes");
+        builder
+            .tool_cmd(Tool::RelnotesApiList)
+            .arg(builder.json_doc_out(host))
+            .arg(&dest)
+            .run(builder);
+        builder.info(&format!("API list for the release notes available at {}", dest.display()));
+    }
+}

src/bootstrap/src/core/build_steps/doc.rs

@@ -559,11 +559,17 @@ pub struct Std {
     pub target: TargetSelection,
     pub format: DocumentationFormat,
     crates: Vec<String>,
+    extra_crates: Vec<String>,
 }
 
 impl Std {
     pub(crate) fn new(stage: u32, target: TargetSelection, format: DocumentationFormat) -> Self {
-        Std { stage, target, format, crates: vec![] }
+        Std { stage, target, format, crates: vec![], extra_crates: vec![] }
+    }
+
+    pub(crate) fn add_extra_crate(mut self, krate: &str) -> Self {
+        self.extra_crates.push(krate.to_string());
+        self
     }
 }
 
@@ -591,6 +597,7 @@ impl Step for Std {
                 DocumentationFormat::Html
             },
             crates,
+            extra_crates: vec![],
         });
     }
 
@@ -601,7 +608,7 @@ impl Step for Std {
     fn run(self, builder: &Builder<'_>) {
         let stage = self.stage;
         let target = self.target;
-        let crates = if self.crates.is_empty() {
+        let mut crates = if self.crates.is_empty() {
             builder
                 .in_tree_crates("sysroot", Some(target))
                 .iter()
@@ -610,6 +617,7 @@ impl Step for Std {
         } else {
             self.crates
         };
+        crates.extend(self.extra_crates.iter().cloned());
 
         let out = match self.format {
             DocumentationFormat::Html => builder.doc_out(target),

src/bootstrap/src/core/build_steps/tool.rs

@@ -519,6 +519,7 @@ bootstrap_tool!(
     FeaturesStatusDump, "src/tools/features-status-dump", "features-status-dump";
     OptimizedDist, "src/tools/opt-dist", "opt-dist", submodules = &["src/tools/rustc-perf"];
     RunMakeSupport, "src/tools/run-make-support", "run_make_support", artifact_kind = ToolArtifactKind::Library;
+    RelnotesApiList, "src/tools/relnotes-api-list", "relnotes-api-list";
 );
 
 /// These are the submodules that are required for rustbook to work due to

src/bootstrap/src/core/builder/mod.rs

@@ -952,6 +952,7 @@ impl<'a> Builder<'a> {
                 tool::CoverageDump,
                 tool::LlvmBitcodeLinker,
                 tool::RustcPerf,
+                tool::RelnotesApiList,
             ),
             Kind::Clippy => describe!(
                 clippy::Std,
@@ -1128,7 +1129,8 @@ impl<'a> Builder<'a> {
                 dist::PlainSourceTarball,
                 dist::BuildManifest,
                 dist::ReproducibleArtifacts,
-                dist::Gcc
+                dist::Gcc,
+                dist::RelnotesApiList,
             ),
             Kind::Install => describe!(
                 install::Docs,

src/tools/relnotes-api-list/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "relnotes-api-list"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+anyhow = "1"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+rustdoc-json-types = { path = "../../rustdoc-json-types" }

src/tools/relnotes-api-list/README.md

@@ -0,0 +1,17 @@
+# API list generator for the release notes
+
+Rust's [release notes] include a "Stabilized APIs" section for each
+release, listing all APIs that became stable each release. This tool supports
+the creation of that section by generating a JSON file containing a concise
+representation of the standard library API. The [relnotes tool] will then
+compare the JSON files of two releases to generate the section.
+
+The tool is executed by CI and produces the `relnotes-api-list-$target.json`
+dist artifact. You can also run the tool locally with:
+
+```
+./x dist relnotes-api-list
+```
+
+[release notes]: https://doc.rust-lang.org/stable/releases.html
+[relnotes tool]: https://github.com/rust-lang/relnotes

src/tools/relnotes-api-list/src/convert_to_schema.rs

@@ -0,0 +1,150 @@
+use crate::pretty_print::pretty_impl;
+use crate::schema::SchemaItem;
+use crate::stability::{Stability, StabilityStore};
+use crate::store::{Store, StoreItem};
+use crate::url::UrlStore;
+use crate::visitor::{Visitor, walk_item};
+use anyhow::{Error, bail};
+use rustdoc_json_types::{ItemEnum, Visibility};
+
+pub(crate) struct ConvertToSchema<'a> {
+    store: &'a Store,
+    stability: &'a StabilityStore,
+    urls: &'a UrlStore,
+
+    name_stack: Vec<String>,
+}
+
+impl<'a> Visitor<'a> for ConvertToSchema<'a> {
+    type Result = Vec<SchemaItem>;
+
+    fn visit_item(&mut self, item: &StoreItem<'a>) -> Result<Vec<SchemaItem>, Error> {
+        if item.visibility != expected_visibility(item) {
+            return Ok(Vec::new());
+        }
+
+        match (self.stability.get(item.crate_id, item.id), &item.inner) {
+            (Some(Stability::Stable), _) => {}
+            (Some(Stability::Unstable), _) => return Ok(Vec::new()),
+
+            // `impl` blocks are not required to have stability attributes, so we should not error
+            // out if they are missing them.
+            (None, ItemEnum::Impl(_)) => {}
+
+            (None, _) => bail!(
+                "stability attribute is missing for {} {:?}",
+                self.name_stack.join("::"),
+                item.id
+            ),
+        }
+
+        let mut pop_name = false;
+        if let Some(name) = &item.name {
+            self.name_stack.push(name.clone());
+            pop_name = true;
+        }
+
+        let result = match &item.inner {
+            ItemEnum::AssocConst { .. }
+            | ItemEnum::AssocType { .. }
+            | ItemEnum::Constant { .. }
+            | ItemEnum::Enum(_)
+            | ItemEnum::Macro(_)
+            | ItemEnum::Module(_)
+            | ItemEnum::Static(_)
+            | ItemEnum::Struct(_)
+            | ItemEnum::StructField(_)
+            | ItemEnum::Trait(_)
+            | ItemEnum::TypeAlias(_)
+            | ItemEnum::Union(_)
+            | ItemEnum::Variant(_)
+            | ItemEnum::ProcMacro(_)
+            | ItemEnum::Function(_) => self.include(item),
+
+            ItemEnum::Primitive(p) => {
+                // We don't want primitives to have the `std::` prefix.
+                let old_stack = std::mem::replace(&mut self.name_stack, vec![p.name.clone()]);
+                let result = self.include(item);
+                self.name_stack = old_stack;
+                result
+            }
+
+            ItemEnum::Use(_) => walk_item(self, item),
+
+            ItemEnum::Impl(impl_) => {
+                if impl_.trait_.is_some() {
+                    Ok(vec![SchemaItem {
+                        name: pretty_impl(impl_),
+                        deprecated: item.deprecation.is_some(),
+                        url: None, // TODO: is there an URL we can put here?
+
+                        // We are intentionally not walking inside impls of traits: we don't want
+                        // all types in the standard library to show up in the changelog if a new
+                        // item is added in a trait.
+                        children: Vec::new(),
+                    }])
+                } else {
+                    walk_item(self, item)
+                }
+            }
+
+            ItemEnum::TraitAlias(_) | ItemEnum::ExternType | ItemEnum::ExternCrate { .. } => {
+                Ok(Vec::new())
+            }
+        };
+
+        if pop_name {
+            self.name_stack.pop();
+        }
+        result
+    }
+
+    fn store(&self) -> &'a Store {
+        self.store
+    }
+}
+
+impl<'a> ConvertToSchema<'a> {
+    pub(crate) fn new(store: &'a Store, stability: &'a StabilityStore, urls: &'a UrlStore) -> Self {
+        Self { store, stability, urls, name_stack: Vec::new() }
+    }
+
+    fn include(&mut self, item: &StoreItem<'a>) -> Result<Vec<SchemaItem>, Error> {
+        let item = SchemaItem {
+            name: self.name_stack.join("::"),
+            url: Some(self.urls.for_item(item)?.into()),
+            deprecated: item.deprecation.is_some(),
+            children: walk_item(self, item)?,
+        };
+        Ok(vec![item])
+    }
+}
+
+/// Some items don't have a visibility associated to them, and are instead public by default. This
+/// function determines what visibility a public item must have.
+fn expected_visibility(item: &StoreItem<'_>) -> Visibility {
+    match &item.inner {
+        ItemEnum::AssocType { .. }
+        | ItemEnum::AssocConst { .. }
+        | ItemEnum::Variant(_)
+        | ItemEnum::Impl(_) => Visibility::Default,
+
+        ItemEnum::Module(_)
+        | ItemEnum::ExternCrate { .. }
+        | ItemEnum::Use(_)
+        | ItemEnum::Union(_)
+        | ItemEnum::Struct(_)
+        | ItemEnum::StructField(_)
+        | ItemEnum::Enum(_)
+        | ItemEnum::Function(_)
+        | ItemEnum::Trait(_)
+        | ItemEnum::TraitAlias(_)
+        | ItemEnum::TypeAlias(_)
+        | ItemEnum::Constant { .. }
+        | ItemEnum::Static(_)
+        | ItemEnum::ExternType
+        | ItemEnum::Macro(_)
+        | ItemEnum::ProcMacro(_)
+        | ItemEnum::Primitive(_) => Visibility::Public,
+    }
+}