Completions de Shell & Páginas Man

Gere completions de shell e páginas man diretamente de suas definições clap para que a documentação nunca fique desatualizada.

Receita

# Gera completions bash em tempo de build
cargo add clap_complete --features generator

use clap::{CommandFactory, Parser};
use clap_complete::{generate, shells::Bash};
use std::io;
 
#[derive(Parser)]
#[command(name = "mytool")]
struct Cli {}
 
fn main() {
    let mut cmd = Cli::command();
    generate(Bash, &mut cmd, "mytool", &mut io::stdout());
}

Quando usar isso: Qualquer CLI que seus usuários instalam localmente e esperam que a autocompletação funcione como ferramentas nativas do sistema.

Exemplo de Trabalho

// build.rs
use clap::CommandFactory;
use std::{env, fs, path::PathBuf};
 
fn main() {
    let out = PathBuf::from(env::var("OUT_DIR").unwrap());
    let mut cmd = mytool::Cli::command();
    for (shell, path) in [
        (clap_complete::Shell::Bash, out.join("mytool.bash")),
        (clap_complete::Shell::Zsh, out.join("_mytool")),
        (clap_complete::Shell::Fish, out.join("mytool.fish")),
    ] {
        let mut file = fs::File::create(&path).unwrap();
        clap_complete::generate(shell, &mut cmd, "mytool", &mut file);
    }
    println!("cargo:rerun-if-changed=src/lib.rs");
}

# Instala completion bash (exemplo)
sudo cp target/debug/build/mytool-*/out/mytool.bash \
  /etc/bash_completion.d/mytool

O que isso demonstra:

• build.rs regenera completions a cada mudança na CLI
• Suporta bash, zsh, fish, powershell e elvish
• Fonte única de verdade: o derive Parser
• Empacota completions em arquivos de release

Mergulho Profundo

Páginas Man com clap_mangen

use clap_mangen::Man;
 
let man = Man::new(Cli::command());
man.render(&mut std::io::stdout())?;

Instale em share/man/man1/mytool.1 em seu pipeline de empacotamento.

Checklist de Distribuição

Geração em Tempo de Execução vs. Tempo de Build

• Tempo de Build - Envie completions no tarball de release (recomendado)
• Tempo de Execução - Subcomando mytool completions bash imprime o script para eval

Armadilhas

• Completions desatualizadas após mudanças de flag - Usuários autocompletam flags antigas. Correção: Regenerar em CI e empacotar com releases.
• Renomeação do binário - O script de completion codifica o nome. Correção: Passe o nome de instalação para generate().
• Aliases de subcomando ausentes - Apenas subcomandos definidos completam. Correção: Adicione visible_alias em clap.
• Página Man sem seção - Man espera a seção 1 para comandos de usuário. Correção: Use man 1 mytool na documentação.
• Nushell / shells customizadas - Nem todos os shells são suportados. Correção: Documente a instalação manual para shells não suportados.

Alternativas

FAQs

Relacionados

• clap - definições de origem
• Empacotamento e Distribuição - envie com releases
• Boas Práticas de CLI - descoberta
• Fundamentos de CLI - fundamentos de --help

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.