Make cargo --list print description for custom subcommands

Author: dtolnay

Cargo.toml

@@ -73,6 +73,11 @@ itertools = "0.10.0"
 # for more information.
 rustc-workspace-hack = "1.0.0"
 
+[target.'cfg(target_os = "linux")'.dependencies]
+cargo-subcommand-metadata = { path = "crates/cargo-subcommand-metadata", version = "0.1.0" }
+memmap = "0.7"
+object = "0.28"
+
 [target.'cfg(windows)'.dependencies]
 fwdansi = "1.1.0"
 

crates/cargo-subcommand-metadata/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "cargo-subcommand-metadata"
+version = "0.1.0"
+edition = "2021"
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/rust-lang/cargo"
+description = "Embed metadata into a Cargo subcommand, so that `cargo --list` can show a description of the subcommand"

crates/cargo-subcommand-metadata/src/lib.rs

@@ -0,0 +1,113 @@
+/// Cargo's name for the purpose of ELF notes.
+///
+/// The `name` field of an ELF note is designated to hold the entry's "owner" or
+/// "originator". No formal mechanism exists for avoiding name conflicts. By
+/// convention, vendors use their own name such as "XYZ Computer Company".
+pub const ELF_NOTE_NAME: &str = "rust-lang/cargo";
+
+/// Values used by Cargo as the `type` of its ELF notes.
+///
+/// Each originator controls its own note types. Multiple interpretations of a
+/// single type value can exist. A program must recognize both the `name` and
+/// the `type` to understand a descriptor.
+#[repr(i32)]
+#[non_exhaustive]
+pub enum ElfNoteType {
+    //              DESCRIP
+    Description = 0xDE5C819,
+}
+
+/// Embed a description into a compiled Cargo subcommand, to be shown by `cargo
+/// --list`.
+///
+/// The following restrictions apply to a subcommand description:
+///
+/// - String length can be at most 280 bytes in UTF-8, although much shorter is
+///   better.
+/// - Must not contain the characters `\n`, `\r`, or `\x1B` (ESC).
+///
+/// Please consider running `cargo --list` and following the style of the
+/// existing descriptions of the built-in Cargo subcommands.
+///
+/// # Example
+///
+/// ```
+/// // subcommand's main.rs
+///
+/// cargo_subcommand_metadata::description! {
+///     "Draw a spiffy visualization of things"
+/// }
+///
+/// fn main() {
+///     /* … */
+/// }
+/// ```
+#[macro_export]
+macro_rules! description {
+    ($description:expr) => {
+        const _: () = {
+            const CARGO_SUBCOMMAND_DESCRIPTION: &str = $description;
+
+            assert!(
+                CARGO_SUBCOMMAND_DESCRIPTION.len() <= 280,
+                "subcommand description too long, must be at most 280",
+            );
+
+            #[cfg(target_os = "linux")]
+            const _: () = {
+                #[repr(C)]
+                struct ElfNote {
+                    namesz: u32,
+                    descsz: u32,
+                    ty: $crate::ElfNoteType,
+
+                    name: [u8; $crate::ELF_NOTE_NAME.len()],
+                    // At least 1 to nul-terminate the string as is convention
+                    // (though not required), plus zero padding to a multiple of 4
+                    // bytes.
+                    name_padding: [$crate::private::Padding;
+                        1 + match ($crate::ELF_NOTE_NAME.len() + 1) % 4 {
+                            0 => 0,
+                            r => 4 - r,
+                        }],
+
+                    desc: [u8; CARGO_SUBCOMMAND_DESCRIPTION.len()],
+                    // Zero padding to a multiple of 4 bytes.
+                    desc_padding: [$crate::private::Padding;
+                        match CARGO_SUBCOMMAND_DESCRIPTION.len() % 4 {
+                            0 => 0,
+                            r => 4 - r,
+                        }],
+                }
+
+                #[used]
+                #[link_section = ".note.cargo.subcommand"]
+                static ELF_NOTE: ElfNote = {
+                    ElfNote {
+                        namesz: $crate::ELF_NOTE_NAME.len() as u32 + 1,
+                        descsz: CARGO_SUBCOMMAND_DESCRIPTION.len() as u32,
+                        ty: $crate::ElfNoteType::Description,
+                        name: unsafe { *$crate::ELF_NOTE_NAME.as_ptr().cast() },
+                        name_padding: $crate::private::padding(),
+                        desc: unsafe { *CARGO_SUBCOMMAND_DESCRIPTION.as_ptr().cast() },
+                        desc_padding: $crate::private::padding(),
+                    }
+                };
+            };
+        };
+    };
+}
+
+// Implementation details. Not public API.
+#[doc(hidden)]
+pub mod private {
+    #[derive(Copy, Clone)]
+    #[repr(u8)]
+    pub enum Padding {
+        Zero = 0,
+    }
+
+    pub const fn padding<const N: usize>() -> [Padding; N] {
+        [Padding::Zero; N]
+    }
+}

src/bin/cargo/cli.rs

@@ -12,6 +12,7 @@ use std::fmt::Write;
 use super::commands;
 use super::list_commands;
 use crate::command_prelude::*;
+use crate::subcommand_metadata;
 use cargo::core::features::HIDDEN;
 
 lazy_static::lazy_static! {
@@ -121,6 +122,8 @@ Run with 'cargo -Z [FLAG] [COMMAND]'",
                 CommandInfo::External { path } => {
                     if let Some(desc) = known_external_desc {
                         drop_println!(config, "    {:<20} {}", name, desc);
+                    } else if let Some(desc) = subcommand_metadata::description(&path) {
+                        drop_println!(config, "    {:<20} {}", name, desc);
                     } else if is_verbose {
                         drop_println!(config, "    {:<20} {}", name, path.display());
                     } else {

src/bin/cargo/main.rs

@@ -13,6 +13,7 @@ use std::path::{Path, PathBuf};
 
 mod cli;
 mod commands;
+mod subcommand_metadata;
 
 use crate::command_prelude::*;
 

src/bin/cargo/subcommand_metadata.rs

@@ -0,0 +1,63 @@
+use std::path::Path;
+
+pub(crate) fn description(path: &Path) -> Option<String> {
+    implementation::description(path)
+}
+
+#[cfg(target_os = "linux")]
+mod implementation {
+    use memmap::Mmap;
+    use object::endian::LittleEndian;
+    use object::read::elf::{ElfFile64, FileHeader, SectionHeader};
+    use std::fs::File;
+    use std::path::Path;
+    use std::str;
+
+    pub(super) fn description(path: &Path) -> Option<String> {
+        let executable_file = File::open(path).ok()?;
+        let data = &*unsafe { Mmap::map(&executable_file) }.ok()?;
+        let elf = ElfFile64::<LittleEndian>::parse(data).ok()?;
+        let endian = elf.endian();
+        let file_header = elf.raw_header();
+        let section_headers = file_header.section_headers(endian, data).ok()?;
+        let string_table = file_header
+            .section_strings(endian, data, section_headers)
+            .ok()?;
+
+        let mut description = None;
+        for section_header in section_headers {
+            if section_header.name(endian, string_table).ok() == Some(b".note.cargo.subcommand") {
+                if let Ok(Some(mut notes)) = section_header.notes(endian, data) {
+                    while let Ok(Some(note)) = notes.next() {
+                        if note.name() == cargo_subcommand_metadata::ELF_NOTE_NAME.as_bytes()
+                            && note.n_type(endian)
+                                == cargo_subcommand_metadata::ElfNoteType::Description as u32
+                        {
+                            if description.is_some() {
+                                return None;
+                            }
+                            description = Some(note.desc());
+                        }
+                    }
+                }
+            }
+        }
+
+        let description: &[u8] = description?;
+        let description: &str = str::from_utf8(description).ok()?;
+        if description.len() > 280 || description.contains(&['\n', '\r', '\x1B']) {
+            return None;
+        }
+
+        Some(description.to_owned())
+    }
+}
+
+#[cfg(not(target_os = "linux"))]
+mod implementation {
+    use std::path::Path;
+
+    pub(super) fn description(_path: &Path) -> Option<String> {
+        None
+    }
+}